Winamp Developer Wiki - User contributions [en]

Tips for Writing an Awesome Online Service

2010-03-05T16:54:35Z

SMonty: /* Tour Tracker */

==Overview==

"A Winamp Online Service is simply a web page"
quote from an unidentified if not too creative web page developer, circa 2009.

When I first heard the above statement I was somewhat surprised. Winamp Online Services are not just web pages. True, you could create a web page and use it as an Online Service but that would be like, .... well like using your smart phone to just make phone calls. There's so much more creative things that can be done. In this document I'd like to point out some cool things that have already been done with Online Services hopefully generating ideas for even more fantastic mashups.

To start with, if you are unfamiliar with what an Online Service is, you can find an excellent description of creating, submitting and managing a service at the [[Online_Service_Developer]] page.

Most importantly, a full description of the JavaScript APIs that can be called from an Online Service can be found at the [[Complete_JavaScript_API_technology_framework]] page. These are the api methods that can make Online Services special, far beyond a 'normal' web page. Not to mention that I also wrote the wiki doc above, so if you like this one, the API reference above would also be good.

If you happened to actually read the two links listed above, rather than coming back to them after reading this, you may have realized what I will be driving at in this document:

'''In order to make an absolutely astounding Online Service, the web page must use the underlying APIs to integrate with the Winamp music player.'''

To restate this, there are facilities to control and retrieve information from the Winamp player. These apis turn a web page into a cool Winamp Online Service. Can you think of some cool things to do with this?....I thought you could. Let's see some Online Services that have already been done.

==Tour Tracker==
In case you don't know (check out the Winamp Online Services), the Tour Tracker Online Service provides a way for users to see upcoming concert information for the bands they are currently listening to on the Winamp player. There are links on this service to purchase tickets to the concerts. Way easier than the old days.

Here is some JavaScript code from the Tour Tracker Online Service.

<code>
function getartist() {
if (!artist) {
if (window.external && window.external.Transport) {
artist = window.external.Transport.GetMetadata("artist");
songtitle = window.external.Transport.GetMetadata("title");

document.location.href="index.php?artist=" + artist;
}
}
}
</code>

This code retrieves the artist name and the title from the currently playing track. So what could you do with that? Well, how about....

<code>
function loadscript() {
// just load ONCE on page-load
if (window.external && window.external.Transport) {
var refreshval = ReadCookie("refresh");
if (refreshval == 1) {
document.getElementById("refreshcheckbox").checked = true;
rc = window.external.Transport.RegisterForEvents(onEvents);
}
}
}

function unloadscript() {
if (window.external && window.external.Transport) {
rc = window.external.Transport.UnregisterFromEvents(onEvents);
}
}
</code>

Here the JavaScript code is registering to receive 'events' from the Winamp player. The loadscript() function is executed when the web page is first loaded and the unloadscript() is executed when the page is unloaded. The function 'onEvents' is called when events occur in the player. Note that the refresh flag is read from the cookie and is used to set the "refreshcheckbox" UI element on the page. Don't forget to 'Transport.UnregisterFromEvents()' when the page unloads.

<code>
function onEvents(event){
if (event.event == "OnPlay" && document.getElementById
("refreshcheckbox").checked == true) {
if (document.getElementById("WindowBox").style.display=="block") {
// empty then block
// don't switch if user is in the process of purchasing tickets!
} else {
getartist();
}
}
}
</code>

Here is the onEvents handler. event.event == "OnPlay" is the event fired whenever a new music track is started on the Winamp player. What this means is that the Tour Tracker Online Service can retrieve the author and title whenever a new track starts playing. Tour Tracker then uses this information to open a new web page in the browser to a site that can show up-coming concerts for the artist and allow the user to purchase tickets.

<code>
function browsetab(urldata) {
var urltouse = urldata.toLowerCase();
urltouse = urltouse.replace(' ', '-');
window.external.Application.LaunchURL(urltouse);
}
</code>

In the following screenshot, you can see that the currently playing song is 'Stuck with You' by Huey Lewis and the News. The Tour Tracker Online Service appears in the browser, showing scheduled concerts for the band. There is an Auto-Refresh checkbox in the upper right corner of the screen (not visible in the screenshot), that will cause Tour Tracker to automatically bring up concert information (if any) for the artist for the next track (John Waite).

[[File:TourTrackerWinampOnlineService.PNG]]

Now is that 'just' a web page? I think not.

==AOL Radio==
The AOL Radio Online Service does something else interesting. Here are two screenshots, one with the default Bento skin and another with a custom skin.

Here's the first

[[File:Radiowithbentoskin.PNG]]

And here's the second

[[File:Radiowithnewskin.PNG]]

Do you see something different? Okay, Okay, other than the color difference. Did you notice that the AOL Radio Online Service web page changed color also? This is a good example of making an online service blend in with the Winamp player. Also notice the 'Sponsored Links'. This is a good example of NOT making it blend in with the Winamp player. But to be fair, the 'Sponsored Links' is somewhat different than the rest of the page so let's talk about the page itself.

The AOL Radio Online Service web page uses code like the following to obtain the color and font information about the Winamp player.

<code>
function updateSkinColors()
{
// globals for anyone who wants 'em!
sColorItemBg = window.external.Skin.GetClassicColor(0);
sColorItemFg = window.external.Skin.GetClassicColor(1);
sColorWndBg = window.external.Skin.GetClassicColor(2);
sColorBtnFg = window.external.Skin.GetClassicColor(3);
sColorWndFg = window.external.Skin.GetClassicColor(4);
sColorHilite = window.external.Skin.GetClassicColor(5);
sColorSel = window.external.Skin.GetClassicColor(6);
sColorListHeadBg = window.external.Skin.GetClassicColor(7);
sColorListHeadFont = window.external.Skin.GetClassicColor(8);
sColorListHeadTop = window.external.Skin.GetClassicColor(9);
sColorListHeadMid = window.external.Skin.GetClassicColor(10);
sColorListHeadBot = window.external.Skin.GetClassicColor(11);
sColorListHeadEmpty = window.external.Skin.GetClassicColor(12);
sColorScrollFg = window.external.Skin.GetClassicColor(13);
sColorScrollBg = window.external.Skin.GetClassicColor(14);
sColorScrollInvFg = window.external.Skin.GetClassicColor(15);
sColorScrollInvBg = window.external.Skin.GetClassicColor(16);
sColorScrollEmpty = window.external.Skin.GetClassicColor(17);
sColorSelbarFg = window.external.Skin.GetClassicColor(18);
sColorSelbarBg = window.external.Skin.GetClassicColor(19);
sColorInactSelbarFg = window.external.Skin.GetClassicColor(20);
sColorInactSelbarBg = window.external.Skin.GetClassicColor(21);

sColorPlFg = window.external.Skin.GetPlaylistColor(0);
sColorPlCurrentFg = window.external.Skin.GetPlaylistColor(1);
sColorPlBg = window.external.Skin.GetPlaylistColor(2);
sColorPlSelbar = window.external.Skin.GetPlaylistColor(3);
sColorPlGenericFg = window.external.Skin.GetPlaylistColor(4);
sColorPlGenericBg = window.external.Skin.GetPlaylistColor(5);

sFontName = window.external.Skin.font;
sFontSize = window.external.Skin.fontsize;
.
.
.
}
</code>

The page then uses script such as this to change the page to use the same colors and fonts.

<code>
function updateColors()
{
.
.
.
$("#wa_body").css("backgroundColor", sColorItemBg);
$("#nav").css({ backgroundColor: sColorSelbarBg, color: sColorSelbarFg });
$("#upgrade_msg").css("borderColor", sColorSelbarBg);
.
.
.
}
</code>

In the code above we're adjusting the css attributes for the elements identified with id= parameter set to the text after the "#"s. And we set them to the values we retrieved from the Winamp player in the previous function.

With these functions, you can make an Online Service look totally integrated inside the Winamp player. When done right, it doesn't even look like a separate web page.

==Song of the Day==
Here is another example of outstanding use of one of the apis, the Transport API.

Below is a snapshot of the "Song of the Day" Online Service from Spinner.

[[File:Songoftheday.PNG]]

Notice the big, ol' round button in the center of the track information. Notice how the first track has a "Pause" button and all the rest have "Play" buttons. That's because I clicked on the play button for the first song and it started playing and now, I can pause it. If you listen to this track, Winamp will eventually move on to the next track in the playlist and, magically, the buttons will change as Winamp begins to play the next track. Also notice that when you click to play one of the items on the web page, a Playlist is created and the song you selected begins to play. How can this be done? Well, it isn't really magic. You don't need to be Harry Potter to do this.

This can be done using the Transport, Transport Events and Playqueue apis.

====Transport====
The Transport API controls the Winamp player, like pushing buttons on the front of a CD player. When the user presses on the buttons on this page, the page calls the following api methods depending on which button was previously being shown:

window.external.Transport.Play();
or
window.external.Transport.Pause();

Simple, huh?
===Transport Events===
But how does the web page know to change from the pause image to the play image when the track ends? Conversly, how does it know to switch from play to pause when it starts the next song? The answer is to register for events from the Winamp player. You've seen this already in the first example we talked about, the Tour Tracker Online Service. Remember this api method?

window.external.Transport.RegisterForEvents(onEvents);

Note: Don't forget to "UnregisterFromEvents" when you are done.

The onEvents function is passed a parameter indicating what kind of event occurred. Let's say "OnPlay" or "OnEndOfFile" (actually the end of a track). With these two events you can change the appropriate images.

===PlayQueue API===
Now what about that queing things to be played thingy? That can be done with the methods of the PlayQueue api. The following api call will clear the list of tracks to be played. You might want to use the Transport.Stop() api to stop the Winamp player as clearing the play queue will not stop the currently playing song.

window.external.PlayQueue.ClearQueue();

To enqueue tracks to be played, you need to call....wait for it..... the Enqueue method.

window.external.PlayQueue.Enqueue(<URL>);

Where <URL> is replaced with a string containing the URL of the track to be played. Do this for each of the tracks that you want queued.

Finally, how do we get the song that was clicked to begin playing? Especially if it was not the first one in our newly constructed Playqueue? You do this by changing the value of the PlayQueue cursor property.

window.external.PlayQueue.cursor = n;

Where n is the offset into the play queue of the track to be played. Be aware that this value is zero (0) based, meaning the first track in the play queue is at cursor=0.

Now just use the Transport.Play() method to kick off the music.

==Finale==
So. We've looked at three different Winamp Online Services. Each one uses apis to do things that 'normal' web pages cannot. The services are more tightly integrated with the Winamp player to cause some very interesting behaviors. Check out the documentation listed at the front of this article and spur on your imagination to create an Awesome Online Service.

Tips for Writing an Awesome Online Service

2010-03-05T16:50:36Z

SMonty: New page: ==Overview== "A Winamp Online Service is simply a web page" quote from an unidentified if not too creative web page developer, circa 2009. When I first heard the above statemen...

==Overview==

"A Winamp Online Service is simply a web page"
quote from an unidentified if not too creative web page developer, circa 2009.

When I first heard the above statement I was somewhat surprised. Winamp Online Services are not just web pages. True, you could create a web page and use it as an Online Service but that would be like, .... well like using your smart phone to just make phone calls. There's so much more creative things that can be done. In this document I'd like to point out some cool things that have already been done with Online Services hopefully generating ideas for even more fantastic mashups.

To start with, if you are unfamiliar with what an Online Service is, you can find an excellent description of creating, submitting and managing a service at the [[Online_Service_Developer]] page.

Most importantly, a full description of the JavaScript APIs that can be called from an Online Service can be found at the [[Complete_JavaScript_API_technology_framework]] page. These are the api methods that can make Online Services special, far beyond a 'normal' web page. Not to mention that I also wrote the wiki doc above, so if you like this one, the API reference above would also be good.

If you happened to actually read the two links listed above, rather than coming back to them after reading this, you may have realized what I will be driving at in this document:

'''In order to make an absolutely astounding Online Service, the web page must use the underlying APIs to integrate with the Winamp music player.'''

To restate this, there are facilities to control and retrieve information from the Winamp player. These apis turn a web page into a cool Winamp Online Service. Can you think of some cool things to do with this?....I thought you could. Let's see some Online Services that have already been done.

==Tour Tracker==
In case you don't know (check out the Winamp Online Services), the Tour Tracker Online Service provides a way for users to see upcoming concert information for the bands they are currently listening to on the Winamp player. There are links on this service to purchase tickets to the concerts. Way easier than the old days.

Here is some JavaScript code from the Tour Tracker Online Service.

<code>
function getartist() {
if (!artist) {
if (window.external && window.external.Transport) {
artist = window.external.Transport.GetMetadata("artist");
songtitle = window.external.Transport.GetMetadata("title");

document.location.href="index.php?artist=" + artist;
}
}
}
</code>

This code retrieves the artist name and the title from the currently playing track. So what could you do with that? Well, how about....

<code>
function loadscript() {
// just load ONCE on page-load
if (window.external && window.external.Transport) {
var refreshval = ReadCookie("refresh");
if (refreshval == 1) {
document.getElementById("refreshcheckbox").checked = true;
rc = window.external.Transport.RegisterForEvents(onEvents);
}
}
}

function unloadscript() {
if (window.external && window.external.Transport) {
rc = window.external.Transport.UnregisterFromEvents(onEvents);
}
}
</code>

Here the JavaScript code is registering to receive 'events' from the Winamp player. The loadscript() function is executed when the web page is first loaded and the unloadscript() is executed when the page is unloaded. The function 'onEvents' is called when events occur in the player. Note that the refresh flag is read from the cookie and is used to set the "refreshcheckbox" UI element on the page. Don't forget to 'Transport.UnregisterFromEvents()' when the page unloads.

<code>
function onEvents(event){
if (event.event == "OnPlay" && document.getElementById
("refreshcheckbox").checked == true) {
if (document.getElementById("WindowBox").style.display=="block") {
// empty then block
// don't switch if user is in the process of xxxing tickets!
} else {
getartist();
}
}
}
</code>

Here is the onEvents handler. event.event == "OnPlay" is the event fired whenever a new music track is started on the Winamp player. What this means is that the Tour Tracker Online Service can retrieve the author and title whenever a new track starts playing. Tour Tracker then uses this information to open a new web page in the browser to a site that can show up-coming concerts for the artist and allow the user to xxx tickets.

<code>
function browsetab(urldata) {
var urltouse = urldata.toLowerCase();
urltouse = urltouse.replace(' ', '-');
window.external.Application.LaunchURL(urltouse);
}
</code>

In the following screenshot, you can see that the currently playing song is 'Stuck with You' by Huey Lewis and the News. The Tour Tracker Online Service appears in the browser, showing scheduled concerts for the band. There is an Auto-Refresh checkbox in the upper right corner of the screen (not visible in the screenshot), that will cause Tour Tracker to automatically bring up concert information (if any) for the artist for the next track (John Waite).

[[File:TourTrackerWinampOnlineService.PNG]]

Now is that 'just' a web page? I think not.

==AOL Radio==
The AOL Radio Online Service does something else interesting. Here are two screenshots, one with the default Bento skin and another with a custom skin.

Here's the first

[[File:Radiowithbentoskin.PNG]]

And here's the second

[[File:Radiowithnewskin.PNG]]

Do you see something different? Okay, Okay, other than the color difference. Did you notice that the AOL Radio Online Service web page changed color also? This is a good example of making an online service blend in with the Winamp player. Also notice the 'Sponsored Links'. This is a good example of NOT making it blend in with the Winamp player. But to be fair, the 'Sponsored Links' is somewhat different than the rest of the page so let's talk about the page itself.

The AOL Radio Online Service web page uses code like the following to obtain the color and font information about the Winamp player.

<code>
function updateSkinColors()
{
// globals for anyone who wants 'em!
sColorItemBg = window.external.Skin.GetClassicColor(0);
sColorItemFg = window.external.Skin.GetClassicColor(1);
sColorWndBg = window.external.Skin.GetClassicColor(2);
sColorBtnFg = window.external.Skin.GetClassicColor(3);
sColorWndFg = window.external.Skin.GetClassicColor(4);
sColorHilite = window.external.Skin.GetClassicColor(5);
sColorSel = window.external.Skin.GetClassicColor(6);
sColorListHeadBg = window.external.Skin.GetClassicColor(7);
sColorListHeadFont = window.external.Skin.GetClassicColor(8);
sColorListHeadTop = window.external.Skin.GetClassicColor(9);
sColorListHeadMid = window.external.Skin.GetClassicColor(10);
sColorListHeadBot = window.external.Skin.GetClassicColor(11);
sColorListHeadEmpty = window.external.Skin.GetClassicColor(12);
sColorScrollFg = window.external.Skin.GetClassicColor(13);
sColorScrollBg = window.external.Skin.GetClassicColor(14);
sColorScrollInvFg = window.external.Skin.GetClassicColor(15);
sColorScrollInvBg = window.external.Skin.GetClassicColor(16);
sColorScrollEmpty = window.external.Skin.GetClassicColor(17);
sColorSelbarFg = window.external.Skin.GetClassicColor(18);
sColorSelbarBg = window.external.Skin.GetClassicColor(19);
sColorInactSelbarFg = window.external.Skin.GetClassicColor(20);
sColorInactSelbarBg = window.external.Skin.GetClassicColor(21);

sColorPlFg = window.external.Skin.GetPlaylistColor(0);
sColorPlCurrentFg = window.external.Skin.GetPlaylistColor(1);
sColorPlBg = window.external.Skin.GetPlaylistColor(2);
sColorPlSelbar = window.external.Skin.GetPlaylistColor(3);
sColorPlGenericFg = window.external.Skin.GetPlaylistColor(4);
sColorPlGenericBg = window.external.Skin.GetPlaylistColor(5);

sFontName = window.external.Skin.font;
sFontSize = window.external.Skin.fontsize;
.
.
.
}
</code>

The page then uses script such as this to change the page to use the same colors and fonts.

<code>
function updateColors()
{
.
.
.
$("#wa_body").css("backgroundColor", sColorItemBg);
$("#nav").css({ backgroundColor: sColorSelbarBg, color: sColorSelbarFg });
$("#upgrade_msg").css("borderColor", sColorSelbarBg);
.
.
.
}
</code>

In the code above we're adjusting the css attributes for the elements identified with id= parameter set to the text after the "#"s. And we set them to the values we retrieved from the Winamp player in the previous function.

With these functions, you can make an Online Service look totally integrated inside the Winamp player. When done right, it doesn't even look like a separate web page.

==Song of the Day==
Here is another example of outstanding use of one of the apis, the Transport API.

Below is a snapshot of the "Song of the Day" Online Service from Spinner.

[[File:Songoftheday.PNG]]

Notice the big, ol' round button in the center of the track information. Notice how the first track has a "Pause" button and all the rest have "Play" buttons. That's because I clicked on the play button for the first song and it started playing and now, I can pause it. If you listen to this track, Winamp will eventually move on to the next track in the playlist and, magically, the buttons will change as Winamp begins to play the next track. Also notice that when you click to play one of the items on the web page, a Playlist is created and the song you selected begins to play. How can this be done? Well, it isn't really magic. You don't need to be Harry Potter to do this.

This can be done using the Transport, Transport Events and Playqueue apis.

====Transport====
The Transport API controls the Winamp player, like pushing buttons on the front of a CD player. When the user presses on the buttons on this page, the page calls the following api methods depending on which button was previously being shown:

window.external.Transport.Play();
or
window.external.Transport.Pause();

Simple, huh?
===Transport Events===
But how does the web page know to change from the pause image to the play image when the track ends? Conversly, how does it know to switch from play to pause when it starts the next song? The answer is to register for events from the Winamp player. You've seen this already in the first example we talked about, the Tour Tracker Online Service. Remember this api method?

window.external.Transport.RegisterForEvents(onEvents);

Note: Don't forget to "UnregisterFromEvents" when you are done.

The onEvents function is passed a parameter indicating what kind of event occurred. Let's say "OnPlay" or "OnEndOfFile" (actually the end of a track). With these two events you can change the appropriate images.

===PlayQueue API===
Now what about that queing things to be played thingy? That can be done with the methods of the PlayQueue api. The following api call will clear the list of tracks to be played. You might want to use the Transport.Stop() api to stop the Winamp player as clearing the play queue will not stop the currently playing song.

window.external.PlayQueue.ClearQueue();

To enqueue tracks to be played, you need to call....wait for it..... the Enqueue method.

window.external.PlayQueue.Enqueue(<URL>);

Where <URL> is replaced with a string containing the URL of the track to be played. Do this for each of the tracks that you want queued.

Finally, how do we get the song that was clicked to begin playing? Especially if it was not the first one in our newly constructed Playqueue? You do this by changing the value of the PlayQueue cursor property.

window.external.PlayQueue.cursor = n;

Where n is the offset into the play queue of the track to be played. Be aware that this value is zero (0) based, meaning the first track in the play queue is at cursor=0.

Now just use the Transport.Play() method to kick off the music.

==Finale==
So. We've looked at three different Winamp Online Services. Each one uses apis to do things that 'normal' web pages cannot. The services are more tightly integrated with the Winamp player to cause some very interesting behaviors. Check out the documentation listed at the front of this article and spur on your imagination to create an Awesome Online Service.

Main Page

2010-03-05T16:48:35Z

SMonty: /* Developer Resources */

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Online Service Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Glossary]]

== Welcome ==
Welcome to Winamp's Developer Network wiki. By consolidating Winamp documentation, code samples, reference materials, and sample articles, we've created a one-stop shop for all things related to Winamp development. The purpose of this site is to help facilitate the development of [[Skin_Developer|Winamp skins]], [[Plug-in_Developer|plug-ins]], [[Visual_Developer|visualization presets]] and [[Online_Service_Developer|online services]]. In order to offer the most relevant material (''and since no one is more of an expert than you''), our goal is to present a wiki that is updated, maintained, and moderated by the Winamp developer community.

Why develop for Winamp, you ask? Besides being a kickass media player with a flexible programming platform, Winamp has a very loyal fan base with over 72 million worldwide users per month. So chances are your creative masterpiece will live well beyond the boundaries of your hard drive. Now that we've got your creative juices flowing (or at a minimum, appealed to your desire for fame and adoration), you can use the '''Developer Network''' as a springboard for everything you need. Most importantly, you can [http://www.winamp.com/user/submit upload] your creation and share it with the World. ''(Note: You'll need a winamp.com account to upload).''

=== How to use the Wiki ===
There are several ways that you can use this wiki. Use it as a reference guide. Start sifting through the content to find the information you need to start developing. If you find out that some key information is missing or you see that something on the site is completely inaccurate, we welcome your contributions. We'd love for you to update the site with killer content and [[Articles]]. Before you start contributing though, make sure you check out the Developer Network [[Policies & Guidelines]] page and create an account. By creating an account or logging into the Winamp Developer Network, you are agreeing to our [[Winamp Developer Network Wiki Terms and Conditions|Terms of Service]] and [http://www.winamp.com/legal/privacy Privacy Policy]

If you've never edited a wiki before, you might want to check out [http://en.wikipedia.org/wiki/Wikipedia:How_to_edit_a_page Wikipedia: How to edit a page]for some pointers.

== Who Should Use the Wiki ==
This wiki is for everyone. Whether you're a seasoned vet, intermediate coder, loyal fan, or even newbie. Primarily though, it's for Winamp developers and user-contributors who want to be actively engaged in the advancement of the Winamp media player. Either by leveraging the content of this site to build better '''skins''', '''plug-ins''', '''visualizations''' and '''online services'''; or by sharing your knowledge and expertise with the community.

===Skin Developer===
To put it as simply as possible, skins change the way your Winamp player looks. If you want to get fancy and say that it changes the GUI (graphical user interface) then you can, but really all you need to know is if you download or create a new skin, Winamp will put on a little mask and pretend to look different. Check [[Skin Developer]] page for more details.

====Classic Skins====
Based on the Winamp 2 model, [[Skin_Developer#Creating_Classic_Skins|Classic skins]] are easier to create than Modern skins, but they do not allow the developer to change the form or function of the player. [[Skin_Developer#Creating_Classic_Skins|Classic skins]] developers may only replace a standard set of images that alter the player's visual appearance.

====Modern Skins====
[[Skin_Developer#Creating_Modern_Skins|Modern skins]] are skins that adhere to the Winamp 3+ skin model. Modern (or freeform) skins offer developers a tremendous amount of flexibility by allowing you to change the player's shape, size, layout, and function. Learn how to create a modern skin for Winamp!

=== Visual Developer===
You know those funny dancing colors you see when you hear music – and no ''Autumn Moonpuppy'', I’m not talking about that time you "toured" with The Dead. [[Visual_Developer|Visualizers]] are dynamic add-ons that produce images, colors, and textures that change based elements of the music being played. Winamp offers two primary visualization platforms (AVS & MilkDrop) allowing you to create different presets. If you’re feeling invincible, you can even attempt to create your own visualization environment.

=== Plug-in Developer===

[[Plug-in_Developer|Plug-ins]] can pretty much do anything! ...within reason, of course. You can alter the sound of your music, turn your mobile phone into a Winamp remote control, or if ya’d like, translate Winamp into another language. Basically, we’ve made the platform flexible enough so that you can craft your idyllic feature and plug it right into Winamp.

'''Types of Plug-ins'''

There are all kinds of categorizes of plug-ins: Input, Output, Visualization, DSP/Effect, General Purpose, Media Library and Portables. That means, you can go nuts in discovering how a single plug-in can change your life. You can read up on the taxonomy of a plug-in here.

'''Start Creating Your Plug-in'''

If you feel like developing one yourself, you can –
# Check out the [[Plug-in_Developer#Tools|suggested tools]]
# Read-up on the [[Plug-in_Developer#SDK_Documentation|SDK documentation]]
# [http://download.nullsoft.com/winamp/plugin-dev/WA5.55_SDK.exe Download the SDK]
# Visit the [http://forums.winamp.com/ Winamp Forums]
# [http://www.winamp.com/user/login Submit your plug-in]. Ain’t it easy?

=== Online Service Developer===
[[Online_Service_Developer|Online Services]] are web pages that are rendered by the embedded browser within Winamp. The awesomeness of these pages is that they can interact with the Winamp Player. In this way a web page can start and stop the player, examine and create playlists, enqueue songs for playback, the colors used in the skin of the player, etc. We're excited to see what you come up with by merging html web pages and the Winamp player.

== Developer Resources ==
*[[Articles]] - link consolidation of all articles written by all types of developers
*[[Plug-in_Developer#SDK_Documentation|SDK Documentation]]
* Download the SDK
*[[Developers_FAQ | Frequently Asked Questions]]
*[[Skin Developer]]
*[[Visual Developer]]
*[[Plug-in Developer]]
*[[Online Service Developer]]
*[[Tips for Writing an Awesome Online Service]]
*[[Glossary|Glossary of Terms]]

== FAQ ==
Check out the [[Developers FAQ]]. Not to mistaken for the standard frequently asked questions that live on the Winamp Forums (although there may be some overlap), this FAQ is specific to developers.

==Contribute to the Wiki ==
Just like the success of Winamp itself, the success of the Developer Network relies on you. We encourage '''everyone''' to contribute - from the expert developer to the passionate user. Your updates, additions, and moderation efforts are critical and we definitely appreciate your efforts making this one of the premier developer sites.

*[[Policies & Guidelines]]

MilkDrop Unleashed Guide

2009-12-22T14:56:06Z

SMonty: /* Usage */

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Main_Page#Glossary_of_Terms|Glossary]]

===Installation===
MilkDrop 2 comes with Winamp. To install it, just download and install the latest version of Winamp. During the installation, make sure the "MilkDrop" visualizer option is checked, so that it gets installed, too.

Once Winamp is installed, launch it. Load some music files into your playlist and start playing some music. (Be sure to play some music before trying to launch the visualizer - otherwise you'll just see a black screen.)

Once music is playing, hit CTRL+K and a list of visualization plug-ins will appear. Select "MilkDrop 2" from the list. Then click the "Start" button, and it will launch the visualizer.

Quick Tips:
* If you want to go full-screen, double-click on the visualizer itself.
* CTRL+SHIFT+K starts or stops the visualizer.
* To configure MilkDrop's options, exit the visualizer and hit ALT+K.

If you have trouble getting MilkDrop to run properly after installation,
try installing various recent WHQL drivers for your video card, or installing
DirectX; doing these two things (especially the first) will fix 99% of
problems. See the Troubleshooting section of the documentation for more
information.

===Tweaking to achieve best image quality===

a) Fullscreen Display Mode [first tab of config screen]

When you run MilkDrop fullscreen, it changes the display mode to whatever you select here. Generally speaking, the speed (framerate) and smoothness of MilkDrop will drop as the resolution (number of pixels on the screen)increases. So, if it's running to slow in fullscreen mode, try selecting a smaller fullscreen display mode.

b) Canvas Stretch [second tab]

This option lets you trade resolution [crispness] for speed. If MilkDrop runs too slow, in any mode (windowed/fullscreen/desktop), try cranking up the canvas stretch to, say, 1.5X or 2X. The image will not look as crisp, but MilkDrop will probably run much faster. (Assuming that your graphics chip was the bottleneck.)

c) Mesh Size [second tab]

This is the main option that affects how much processor (CPU) MilkDrop uses. If you crank it up far beyond the default, expect to be CPU-bound (where your framerate drops because the CPU is the bottleneck). To get MilkDrop to speed up, drop the Mesh Size back down. The Mesh Size decides how many points on the screen the per-vertex equations will be executed for; the higher the mesh size, the more fidelity you will see in the motion.

d) Tips for LCD and laptop users

LCD screens: Note that most LCD screens (flatpanels) usually run at a fixed frequency only - usually 60 Hz - meaning that they update the screen 60 times per second. However, sometimes the video driver reports that it supports other refresh rates, such as 72, 75, 85, etc. It is strongly recommended that [for fullscreen mode, and for Windows in general] you choose a display mode with a 60 Hz refresh rate, for the smoothest possible animation. For this plugin, you will also want to choose Maximum Framerates that divide evenly into 60 - such as 60, 30, 20, 15, 12, 10, 6, 5, and so on - so that the # of times the LCD shows each frame of animation remains constant, resulting in the smoothest possible animation.

e) color (bit) depth: 16 or 32?

The answer, nowadays, is a resounding "32". Video memory is plentiful these days; use 32 bit color, for both your windows desktop (...so that MilkDrop's windowed mode can run at 32 bits) and for MilkDrop's Fullscreen Display Mode setting (where "8888" denotes 32 bits). Some ancient video cards don't have enough memory to run MilkDrop properly (or smoothly) in 32 bits, though; you might want to try 16-bit color if your card has less than 32 MB of video memory, if you are using a laptop, or if your video card is significantly old. In the MilkDrop config panel, 16-bit modes show up as "555" or "565".

If you find that your card runs best in 32-bit color, you should have no problems with brightness levels while running MilkDrop. However, if your card runs best in 16-bit color, you should then adjust the Brightness slider on the second tab of the config panel (which only affects 16-bit color video modes!). The goal is to make the image as bright as possible, without oversaturating it (washing it out, often to bright pink or white). This setting also varies for different cards, depending on how the card rounds color values, so we recommend seeing how bright you can set the slider closer to '0') without oversaturating the image. Usually,a setting of '0' or '2' works the best.

===Usage===

'''4.a. Keyboard Commands'''

The following keys can be used to control MilkDrop while it is running.
(Note: pressing F1 while MilkDrop is running will show you this list)

GENERAL
escape: exit to winamp

PRESET LOADING
BACKSPACE: return to previous preset
SPACE: transition to next preset
H: instant Hard cut (to next preset)
R: toggle random (vs. sequential) preset traversal
L: load a specific preset (invokes the 'Load' menu)
+/-: rate current preset (better/worse)
scroll lock: lock/unlock current preset
(keyboard light on means preset is locked)
(prevents random switch to new preset)
A: aggregate preset - loads a random preset,
steals the warp shader from a different random preset,
and steals the composite shader from a third random preset.
D: cycle between various lock-states for the warp and
composite shaders. When one of these shaders is locked,
loading a new preset will load everything *except* the
locked shaders, creating a mix between the two presets.

PRESET EDITING AND SAVING
M: show/hide the preset-editing menu
S: save new preset (asks you for the new filename)
N: show per-frame variable moNitor
(see [[MilkDrop Preset Authoring]])

MUSIC PLAYBACK
z/x/c/v/b: navigate playlist (prev/play/pause/stop/next)
U: toggle shuffle
P: show playlist
up/down arrows: volume up/down
left/right arrows: rewind/ffwd 5 seconds
SHIFT + left/right arrows: rewind/ffwd 30 seconds

FUNCTION KEYS
F1: show help screen
F2: show song title
F3: show song length
F4: show preset name
F5: show fps (frames per second)
F6: show rating of current preset
F7: re-read custom message file (milk_msg.ini) from disk
F8: jump to new directory (for presets)
F9: toggle stereo 3D on/off

SPRITES AND CUSTOM MESSAGES (FOR VJ's)
T: launch song title animation
Y: enter custom message mode
##: load message ## (where ## is a 2-digit numeric code (00-99)
of a message defined in milk_msg.ini)
*: clear any digits entered.
DELETE: clear message (if visible)
F7: re-read milk_msg.ini from disk
K: enter sprite mode
##: load sprite ## (where ## is a 2-digit numeric code (00-99)
of a sprite defined in milk_img.ini)
*: clear any digits entered.
DELETE: clear newest sprite
SHIFT + DELETE: clear oldest sprite
CTRL+SHIFT+DELETE: clear all sprites
F7: no effect (milk_img.ini is never cached)
SHIFT + K: enter sprite kill mode
##: clear all sprites with code ##
*: clear any digits entered.
CTRL + T/Y: kill song title and/or any custom messages
CTRL + K: kill all sprites

Note that there are more keys available, but because many
are only relevant to people designing their own presets,
they are listed in the preset authoring guide instead.

'''4.b. config panel'''

The configuration panel lets you customize the way MilkDrop runs.
To learn how to get to the configuration panel, see the "Installation"
section above.

Once you're in the config panel, you'll see a number of tabs
at the top, some dropdown boxes, and some checkboxes. Each
of the tabs at the top brings you to a different page of
configuration options. To get help on a setting, simply click
on the '?' in the upper-right corner of the config panel,
and then click on the setting you want help with.

'''4.c. preset authoring'''

Please check the [[MilkDrop Preset Authoring]] guide for instructions on how to create and save your own presets.

'''4.d. rating system'''

The built-in rating system allows you to rate each preset on a scale
from 0 to 5. A rating of 5 is very good, while a rating of 0 is
the worst. The ratings decide how often the presets will be randomly
loaded. If a preset has a rating of 0, it will never be randomly
loaded (unless they're all zero; then they all have an equal chance).

To show the rating for a preset, press F6. You can adjust the
rating for a preset with the +/- keys. When you make adjustments,
they save automatically; there's no need to save the preset to make
the rating change permanent.

Here's a recommended interpretation of the numeric values:
0 = I never want to see this preset again
1 = very ugly
2 = mediocre
3 = fair
4 = good
5 = downright stimulating

If a preset seems "lost" because you set its rating to 0 and it
won't ever come back, you can always load it up by hitting 'L'
to conjure the 'Load Preset' menu, finding the preset you want,
loading it, then hitting +.

'''4.e. custom messages'''

ABOUT CUSTOM MESSAGES:
The "Custom Message" feature of MilkDrop allows you to display
short text messages on the screen while MilkDrop is running.
They are highly configurable; you can set all of the following
parameters: the font, the size, the positioning, color, bold
state, italic state, and so on; and you can even have it
randomize some of these properties.

CREATING THE MESSAGES:
You can save up to 100 messages in the file MILK_MSG.INI in
your Winamp\Plugins\ folder. To open this file, go to the
MilkDrop configuration screen (ALT+K from Winamp) and click the
"Edit Custom Messages" button. Or, you can just edit it
manually if you know how; it's plain-text.

The first thing you see when you open the file is a bunch of
lines that start with two forward slashes (//). These are
comment lines, and they explain the syntax for adding a font
or a message to the file. This is your main reference for
finding out what all the parameters do for the fonts & messages;
it is recommended that you leave this information in the file,
although it can be removed or (modified) and the messages will
still work.

After the comments come first the fonts, then the messages.
The fonts are simply a way to specify a typeface, bold state,
italics state, and red/green/blue color for the font. You can
configure up to 16 fonts like this (numbered 00-15). These fonts
will serve as template fonts for the custom messages.

The next section is the actual messages. Each one has a
text message (the 'text' parameter) that will be shown to the
user, and each one references one of the 16 fonts that were
defined in the previous section. You can also specify the
size (size), position (x,y), a growth factor (growth) that
will grow/shrink the message over its lifetime, the number
of seconds to show the message (time), and the fraction of that
time that is spent fading in (fade).

You can also randomize some of these values: 'randx' and 'randy'
will randomly perturb the (x,y) coordinates every time the message
is shown to the user, and 'randr'/'randg'/'randb' will randomly
perturb the (r,g,b) color in the same way.

Finally, you can override any of the default properties for the
font that this message uses: (face, bold, ital, r, g, b).

INVOCATION AND USAGE:
There are two ways to invoke custom messages: one automatic,
the other manual.

The automatic way is to go to the MilkDrop config panel (ALT+K),
click the 'More Options' button, and set the value in the
'Time between RANDOM custom messages' box to something greater
than zero. This will cause MilkDrop to randomly display custom
messages while it is running, and the average time (in seconds)
between messages will be the value you entered here. If you
wish to disable random custom messages, set this value to -1
(or any negative number). Note that all messages in the file
have an equal change of being picked.

The manual way is to type in the two-digit code (00-99) of the
message while MilkDrop is running. However, you can't use the
numeric keypad for this - you have to use the numbers at the
TOP of your keyboard to do it. If you mess up while entering
the first digit, just press the '*' key to start over.

Note that if you change the MILK_MSG.INI file while MilkDrop
is running, you will not be able to see the changes until
you hit F7, which tells MilkDrop to re-read the MILK_MSG.INI
file from disk.

'''4.f. sprites'''

ABOUT SPRITES:
The "Sprite" feature of MilkDrop allows you to display any image of your choice in the foreground (on top of MilkDrop) while it runs. The sprites can fade in and out, move around, respond to the music, and so on. You define them in a file - milk_img.ini in your winamp\plugins directory - much like you define custom messages, each having an identifying code number from 00 through 99 (used to invoke them). However, the way the individual sprites are defined is different; you write code for them, instead of just setting parameter values. This is a little bit tougher to do (it's very much like preset authoring), but adds a great deal of flexibility to what you can do with the sprites.

CREATING THE SPRITES:

You can define up to 100 sprites in the file MILK_IMG.INI in your Winamp\Plugins\ folder. To open this file, go to the MilkDrop configuration screen (ALT+K from Winamp) and click the "Edit Sprites" button. Or, you can just edit it manually if you know how; it's plain-text.

The first thing you see when you open the file is a bunch of lines that start with two forward slashes (//). These are comment lines, and they explain the syntax for creating a sprite. This is your main reference for finding out what all the parameters do for the fonts & messages; it is recommended that you leave this information in the file, although it can be removed (or modified) and the sprites will still work.

After the comments come the sprite definitions. Each sprite is made up of one parameter that indicates the image file to use (this is the 'img=...' line), and two types of code: initialization code, and regular code.

The first - initialization code - is executed only once, when you launch the sprite. Use it to do one-time initialization of variables (such as the opacity (a), rotation angle (rot), position (x,y), and so on) or to invent new variables that you will access later. This code is marked by the 'init_1=...', 'init_2=...', etc. lines. The second type of code - marked by 'code_1=...', 'code_2=...', etc. is executed every frame, just prior to plastering the sprite on the screen. Use it to animate the sprite, moving it around (changing x,y), scaling it up and down (sx,sy), fading it in and out (a), changing its color, and so on.

Please see the comments included in the sample milk_img.ini file
for full details and examples on how to author sprites.

INVOCATION AND USAGE:
There is currently only one way to invoke sprites: manually. To do this, first press 'K' to enter 'sprite mode' (while running MilkDrop). Now, whenever you type in a two-digit code (00-99), MilkDrop will try to find & launch the sprite you've requested, from the milk_img.ini file. If there is an error, it will display an error message in the upper-right corner. Note that to enter the two-digit code, you can't use the numeric keypad; you have to use the numbers at the TOP of your keyboard.

If you make an error entering the first digit of the code, just press '*' to start over. If you want to clear the most recently-invoked sprite, press DELETE. If you want to clear the oldest sprite, press SHIFT + DELETE. If you want to clear all sprites, press SHIFT + CTRL + DELETE.

If you want to clear sprites by their 2-digit code, press SHIFT + K (instead of just 'K') to enter 'sprite kill mode.' Now, when you enter a two-digit code, instead of invoking the sprite, MilkDrop clears all running sprites with that two-digit code.

===Trouble Shooting===

If MilkDrop has a critical problem (e.g. fails to load, freezes, etc.)or if the image is distorted, torn, corrupted, or all one solid color, try the following two suggestions to resolve the problem. In 90% of these cases it can be fixed. If you have a different problem, scroll down past this part and try to find the appropriate symptom and its solution.

====1. UPDATE YOUR VIDEO DRIVER, OR TRY OTHER DRIVERS====

Almost all display problems are caused by buggy video drivers! A "driver" is a piece of software that translates graphics-related commands from programs, like MilkDrop, into the native language of your specific graphics hardware.

For desktop machines, there are typically three sources for video drivers:
# those from the *chip* manufacturer's website (usually nvidia.com or ati.com) (best source)
# those from the card manufacturer's website (LeadTEK, PNY, etc.)
# those that shipped with Windows (yuck)

For laptops:
# the driver from the *laptop* manufacturer
# (maybe) the driver from the graphics chip manufacturer (ATI, Nvidia, etc) - however, it's fairly common to find that the laptop requires a custom driver written by the laptop manufacturer.
# the driver that shipped with Windows (yuck)

Give them all a shot. Track down every driver you can find for your card, and try it. Try the WHQL ones first - these versions of the drivers have passed "Windows Hardware Quality Labs" certification and are usually the more stable and reliable ones. In general, it's a very good idea to use only Microsoft-certified WHQL drivers for your video card. Often people want to get the newest, fastest beta drivers, but these drivers are almost ALWAYS riddled with new bugs. You can also watch the version number of the drivers a company releases - if the version number just jumped to a new series such as from the 70's to the 80's), watch out, it probably has a lot of bugs that need worked out - give it 3-4 months before expecting the new driver series to work well. With video drivers, the newest isn't always the best!

Here is a list of some common card/chip manufacturers and where to get their drivers. Don't forget to choose the WHQL driver!

[http://www.nvidia.com/page/drivers.html NVIDIA driver]
Card manufacturers using NVIDIA (GeForce) graphics chips:
(note - most of these just link you to the nvidia driver above)
[http://www.xfxforce.com/web/support/showSearchDriversProductCode.jspa XFX]
[http://www.evga.com/support/drivers EVGA]
[http://www.bfgtech.com/driverdownload.aspx BFG]
[http://www2.pny.com/support/support.aspx PNY]
[http://ati.amd.com/support/driver.html ATI driver]
Card manufacturers using ATI (Radeon) graphics chips:
[http://www.visiontek.com/teksupport/drivers/drivers.html VisionTek]
[http://www.dmmdownload.com/current.php Diamond]
[http://downloadcenter.intel.com Intel] - then click 'graphics' on the left
[http://www.sis.com/download SiS] - agree, then select 'graphics drivers'
[http://www.s3graphics.com S3] - then click 'drivers'
[http://www.via.com.tw/en/products/graphics VIA]
[http://www.matrox.com/graphics/en/corpo/support/drivers/home.php Matrox]
[http://www.creative.com/language.asp?sDestUrl=/support/downloads Creative Labs]

For others - or in general - if your graphics chip is made by Trident, for example, then try a [http://www.google.com/ google] search for:

Trident graphics driver

Then click on "support", then "drivers" (or "downloads"), then "graphics driver", and so on.

====2. [RE]INSTALL DIRECTX====

Make sure you have a quasi-recent version of Microsoft DirectX installed. In reality, though, almost every PC in the world has DirectX 9 on it at this point, so this shouldn't be a problem. If you go to download it, you'll only be able to find DirectX 10 - this is fine to install, though, as it includes DirectX 9 inside it. As a last resort, though, if you are having problems, you could try re-installing DirectX to see if it helps.

If you're having a non-critical problem, browse the following list of common problems and their causes and solutions. Note that for each symptom- cause-solution block, there can be multiple symptoms with the same cause and solution, and the same symptom might be listed in multiple blocks.

If the solutions below don't work for you, please visit the forums at http://forums.winamp.com/forumdisplay.php?forumid=84, where you can read the most recent troubleshooting issues and solutions.

ENTRY 1
SYMPTOM:
-any error message saying "Failed to create ..."
or "not enough memory...", or
-only a portion of the screen displays correctly; the rest is
either filled with garbage or badly flickering
CAUSE:
1) Your video card might not have enough memory to run MilkDrop at
the resolution (screen width and height) you've picked,
2) your drivers might be out of date,
3) you might need to reinstall DirectX (very very rare), or
4) your graphics card might be to crappy to *actually* run
pixel shaders well.
SOLUTION:
1) To battle video memory problems:

Go to the config panel and try smaller video modes (e.g.,
320x240 is smaller than 640x480). Even better is to try
a lower color bit depth; if you'd selected a 32-bit ("8888")
video mode before, try a 16- ("565" or "555") or 24-bit ("888")
one, for example. Note that it might only work in one of them;
so make sure you try them all. Trying these things is especially
important on laptops with limited video memory, or older video
cards with a small amount of video memory.

Finally, you can try locking the texture size (or "canvas size")
to 256x256 pixels, just to see if that fixes the problem.
If it does, try using a smaller fullscreen video mode to
free up some memory, or if running windowed, close other
graphics-hungry applications.

2,3) for instructions on how to reinstall DirectX or update
drivers, go here.

4) Go to the MilkDrop config panel (hit ALT+K) and on the second tab,
in the "Pixel Shaders" box, select "None." Now does MilkDrop run
ok? If so, your video card probably just can't reliably run
pixel shaders, due to either inferior hardware, or it could
be the driver. You can always try setting "Pixel Shaders"
back to "Auto" and then installing a newer (preferably WHQL)
video driver.

ENTRY 2
SYMPTOM:
-When I go to the Load Preset menu ('L') in MilkDrop, some of the
presets on disk are missing.
-I downloaded some new presets and put them in my Plugins\MilkDrop2\Presets
directory, but I can't access them from within MilkDrop.
CAUSE:
You probably have an older video card that can't handle the pixel
shaders needed to run some of the presets. MilkDrop automatically
hides any presets from you that you can't run.
SOLUTION:
* You could b uy a new graphics card - one that meets the minimum
recommendation for MilkDrop 2. These cost less than $40.
* You could try forcing MilkDrop to try to run these presets.
Sometimes MilkDrop just hides them from you because it predicts
they will run horribly slow on your graphics card; in case it
is wrong about that, try this. Go into the MilkDrop config
panel (ALT+K) and go to the More Settings tab. Under the
"Pixel Shaders" option, change it from "Auto" to "Shader Model 2"
or "Shader Model 3". Then try to run MilkDrop and see if the
presets appear. If they do, you're in luck; if they don't, your
GPU really doesn't support those shader models.

ENTRY 3
SYMPTOM:
MilkDrop always looks the same - it's always showing the same
preset, and it never changes to a new preset unless I tell it to.
CAUSE:
Scroll Lock is on.
SOLUTION:
The Scroll Lock key is how you tell MilkDrop to lock the current
preset - i.e. don't randomly transition to a new preset unless you
do it. The state of the Scroll Lock key is remembered when you
start or stop MilkDrop, too, so be careful of that. If you are
experiencing this problem, you can fix it in any of the following
three ways:
1. hit Scroll Lock while MilkDrop is running (and the viz window is active);
2. load up the MilkDrop config panel (ALT+K), go to the More Settings
tab, and uncheck the "Start milkdrop with preset lock (scroll lock)
key ON" box;
3. if you're using a modern skin, there is a "random" button on
the frame of the window, which is the inverse of the Scroll Lock
state - i.e. you probably have Scroll Lock on and "random" off.
Click the "Random" button to turn random transitions back on
(and notice that scroll lock gets turned off as a result).

ENTRY 4
SYMPTOM:
I was browsing for presets from within MilkDrop ('L') key and
got lost. How do I get back to my presets?
SOLUTION:
Two ways to fix this. The easiest is to just reset MilkDrop
to its defaults - hit ALT+K to load the MilkDrop config panel,
then click the 'Defaults' button. The next time you launch
MilkDrop, it will start you in the default preset directory.

To fix it manually (and preserve all your settings), run
MilkDrop, hit F8, and paste in this path:
C:\Program Files\Winamp\Plugins\Milkdrop2\presets
[or equivalent].

Another way to fix it is to hit 'L', and browse all the way
down to the root folder (repeatedly select ".."), then
go into Program Files, Winamp, Plugins, MilkDrop2, and finally,
presets.

ENTRY 5
SYMPTOM:
-things flicker through (such as my AIM window ticker, taskbar
clock, web page animations, etc.) when I'm running MilkDrop
in fullscreen mode.
CAUSE:
You're probably running MilkDrop fullscreen at the same
resolution & color depth as your desktop, and Windows isn't
properly handling MilkDrop's request for exclusive access to the
screen, and is still letting other applications paint (draw)
themselves.
SOLUTION:
Change either your Windows desktop resolution or color depth, or
MilkDrop's fullscreen resolution or color depth, so that there
is some difference between the two. (To change your Windows
display settings, go to the Start Menu -> Settings -> Control
Panel -> Display -> Settings tab, and then change the "colors"
or "screen area" settings from there.) Also make sure you're
not using "fake" fullscreen mode (...uncheck this box on the
main screen of the config panel).

===Known Issues / Misc. / Tips:===

a. Tip for video capture: if you'd like to save sequences of video
from this plugin, there are several programs out there that will
let you do this. Warning: you will need a ton of free hard drive
space, and a fast CPU helps. A few of these programs are:
"FRAPS" http://www.fraps.com/
"Hypercam" http://www.hyperionics.com

b. Close other apps:
For the best graphics performance, try to close as many other
applications as you can, before running the plugin, especially
those that tend to work in the background, such as anti-virus
or file-swapping software. Also, if you must leave other
applications open, try to minimize them (i.e. shrink the window
down to the taskbar) so that they stay out of the painting loop.

c. Windows Vista / Winamp with per-user settings
Be aware that if you're running Vista as a non-admin user,
you can't write to (or delete from) files in the Program Files
directory, which is were MilkDrop 2 is installed. So, anything
you try to write or save (like milkdrop's settings file, milk2.ini;
or presets) will probably end up deep in some user-specific,
virtualized "Program Files" directory somewhere on your hard
drive. Yell at Microsoft for this one!

Also, if you installed Winamp with per-user settings (instead of
shared settings) - on any OS, not just Vista - be aware that your
.INI files (milk2.ini, milk2_img.ini, milk2_cfg.ini) are all
stored in a folder like this:

C:\Documents and Settings\\Application Data\Winamp\Plugins

(Note that 'Application Data' is a hidden folder.) However,
presets, textures, and things like that are all shared between
users, in the real [c:\Program Files]\winamp\plugins\milkdrop2 folder.
If you want to keep your presets separate, you can still do that,
though - just put them in a personal folder, and then seek to it
from within MilkDrop. If you're using per-user settings in Winamp,
it will remember which folder you last used.

===Using Line-In===
-----------------------
If you want to use your sound card's Line-In or CD Audio inputs for
sound data (instead of mp3 files), you can do this. Do the following:
1. CONNECT WIRES
Connect your audio source (a stereo, a live feed, whatever) into
the line-in (or microphone) 1/8" jack on your sound card. You
might want to test & verify that your cable is good before doing
this.
2. SELECT SOUND INPUT CHANNEL & ADJUST VOLUME
In Windows, double-click the speaker icon in your systray (where
the clock is). Then, on the menu, go to Options -> Properties
and select the "Recording" option. Then make sure the Line In
(or Microphone) input channel (whichever is appropriate for
your case) is SELECTED (with a check mark) and that the volume
is close to, or at, the maximum. Hit OK.
3. TELL WINAMP TO USE LINE-IN
Open Winamp, and hit CTRL+L (the "Open Location" hotkey). Now
type in "linein://" as the location you want to open. (Leave out
the quotes and make sure you use FORWARD slashes.) Hit PLAY
('x' key for the lazy), and the little built-in oscilloscope (or
spectrum analyzer) in Winamp should start showing your signal.
4. RUN MILKDROP
Run MilkDrop as usual. If the waves are too small or large,
either adjust the volume from Windows' Volume Control, or adjust
the sound level at the source.

If you are doing shows using live audio, and if you have a multiple monitor
setup, you might also want to use the "VJ mode" feature, which lets you
control MilkDrop (even editing shaders on the fly, etc.) via a separate monitor.

Talk:Beginner's Basic Plugin Guide

2009-09-21T16:33:41Z

SMonty: /* Basic gen_empty.dll File Crashes WinAMP On Start Of WinAMP. */

==Is this format okay?==
Hey everyone, this is my first work with any Winamp plugin code and my first edits to the wiki. Sorry if anything is in the wrong format or wrong place. Please feel free to move or work on it; I'm open to suggestions on how to improve. --[[User:Culix|Culix]] 02:29, 10 June 2009 (UTC)

== Questions and TODO ==

I still have a few questions about writing plugins. These should probably be filled into the guide at some point. --[[User:Culix|Culix]] 02:34, 10 June 2009 (UTC)

* How do the naming conventions work for plugins? It seems more complicated than simply naming your file 'gen_*' or 'ml_*'.

The answer to this is complicated, as so much with Winamp. The prefix is actually used by Winamp.exe to find plugins and identify what type they are. There is another way to create plugins that does not require the prefix. This second way is called Wasabi. Wasabi is a way to 'share' code among components of a software system (i.e., Winamp). Wasabi dlls do not need the prefix. We'll get to Wasabi if we keep writing these kinds of tutorials. Is there something specific about the prefixes that leads you to believe that there is a 'real' answer? Maybe I can investigate further.

* For the "cannot convert parameter from 'const char [x]' to 'LPCTSTR'" error, which option from the [http://social.msdn.microsoft.com/Forums/en-US/vclanguage/thread/c1b08c0a-a803-41c3-ac8c-84eba3be1ddb MSDN FAQ] should we actually use? Is it better to change the project settings to use a multi-byte character set?

I would not change the project settings and instead use the L"" or _TEXT constructs to indicate that the strings are wide strings. Winamp programmers prefer to be even more specific and actually call the MessageBoxW() or MessageBoxA() methods to make it absolutely clear as to which function and what form the input is in (this would make the project switch meaningless). Since Winamp is a very popular application around the world it is best to use UNICODE.

Having said that, Winamp is also ancient (in computer years) and so every once in a while you might run across places within Winamp that do not handle UNICODE and will require ASCII strings. For example, notice the description field of the winampGeneralPurposePlugin structure. It was never converted to use UNICODE since that would change the size of the structure requiring a new revision and all the attendant problems that go along with that.

* Why do some people put their 'extern "C" __declspec' code in the header and others in the .cpp? Does it matter?

The point of the extern "C" is to tell the linker not to perform C++ name mangling on the function name. This is necessary when some other application needs to invoke the method and therefore needs to use a name that is easier to use. Technically it doesn't matter whether you put them in a header or cpp file and it boils down to the more common reasons why you choose to put things in header files rather than including them in the cpp file.

===Basic gen_empty.dll File Crashes WinAMP On Start Of WinAMP.===
I have turned off pre-compiled headers in VS 2008 Pro.
Right Click On Solution-->Properties-->Configuration Properties-->Linker-->Additional Dependencies has been blanked.
Right Click On Solution-->Properties-->Configuration Properties-->C/C++ -->Precompiled Headers-->Create/Use Precompiled Header = "Not Using Precompiled Headers"
WinXP with service pack 3.
WinAMP 5.56 with Pacemaker and Playlist File Remover plugins installed.
WinAMP was running just fine with Pacemaker, though Playlist File Remover doesn't send files to the recycle bin like it should (It worked in prior versions of WinAMP, but not 5.56, that's why I want to write a plugin)

I get Visual Studio to compile a gen_empty.dll, but when I copy that to the "C:\Program Files\Winamp\Plugins" folder, WinAMP will crash on launch. It begins to create visible WinAMP application window outlines on the screen, but then it fails to complete. The outlined windows dissapear, and WinAMP.exe process vanishes from the task manager.

Removing the empty blank gen_empty.dll from "C:\Program Files\Winamp\Plugins" fixes the problem, WinAMP starts normally, just as it did before.

I even commented out the MessageBox-es so the functions would do NOTHING, and tried the resulting gen_empty.dll.

'''What is wrong with this generic, blank plugin source code that causes WinAMP 5.56 to fail?'''

<source lang=cpp>
//---------------------------------------------------------------------------
#ifndef gen_empty_h
#define gen_empty_h
#include <windows.h>
#include <stdio.h>

// plugin version (don't touch this)
#define GPPHDR_VER 0x10

// plugin name/title (change this to something you like)
#define GPPHDR_NAME "gen_empty v1.0 (gen_empty.dll)"

// main structure with plugin information, version, name...
typedef struct {
int version; // version of the plugin, defined in "gen_empty.h"
char *description; // name/title of the plugin, defined in "gen_empty.h"
int (*init)(); // function which will be executed on init event
void (*config)(); // function which will be executed on config event
void (*quit)(); // function which will be executed on quit event
HWND hwndParent; // (?)
HINSTANCE hDllInstance; // (?)
} winampGeneralPurposePlugin;

extern winampGeneralPurposePlugin *gen_plugins[256];
typedef winampGeneralPurposePlugin * (*winampGeneralPurposePluginGetter)();
#endif
//---------------------------------------------------------------------------
</source>
 
<source lang=cpp>
//-----------------------------------------------------------------
// This is the main DLL file.

#include <stdio.h>
#include <windows.h>
#include "gen_empty.h"

// these are callback functions/events which will be called by Winamp
int init(void);
void config(void);
void quit(void);

// this structure contains plugin information, version, name...
winampGeneralPurposePlugin plugin = {
GPPHDR_VER, // version of the plugin, defined in "gen_empty.h"
GPPHDR_NAME, // name/title of the plugin, defined in "gen_empty.h"
init, // function name which will be executed on init event
config, // function name which will be executed on config event
quit, // function name which will be executed on quit event
};

// event functions follow

int init() {
//MessageBox(plugin.hwndParent, L"Init event triggered for gen_empty. Plugin installed successfully!", L"", MB_OK);
return 0;

}

void config() {
// MessageBox(plugin.hwndParent, L"Config event triggered for gen_empty.", L"", MB_OK);

}

void quit() {
// MessageBox(0, L"Quit event triggered for gen_empty.", L"", MB_OK);
}

// this is an export function called by winamp which returns this plugin info
extern "C" __declspec(dllexport) winampGeneralPurposePlugin * winampGetGeneralPurposePlugin() {
return &plugin;
}
//-----------------------------------------------------------------</source>

===Doesn't appear to be in the code===
Hi, I examined your code and could see nothing that would cause Winamp to crash. I then copied the code you posted to my development machine, compiled it and moved it to the plugins directory and Winamp worked fine. I tested this on 5.56 and 5.57.

My thought would be to look at some of the project options you may have set as I believe the C++ code is not the problem. My first thought might be the packing for structures.

==Next Steps==
I think a good extension of this article would be to answer the user's question of "Okay, now what?". If we could give them hints about where to go next, possibly depending on the type of plugin they want to write, that might be useful. This may just involve fleshing out the guide articles for each type of plugin and then linking to those... unless someone can think of something better? --[[User:Culix|Culix]] 14:54, 10 June 2009 (UTC)

Basic Plugin Guide - Tutorial

2009-08-07T15:56:14Z

SMonty: /* Another API call */

==Accessing information from Winamp==
Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit. While this is really cool, it lacks something. Maybe it needs to do something. Let's fix that now.

===Keeping it simple===
In order to keep these explanations simple, I'd rather not add a lot of code to create a Windows UI. We will eventually create a UI, but first let's invoke some Winamp 2 API methods. Just to see how they work.

When we last left our hero....err plugin, we had created three methods 'init', 'config' and 'quit'. 'init' is invoked by Winamp when the plugin is first loaded. 'quit' is invoked by Winamp when the plugin is unloaded, i.e., when Winamp is closing. 'config' is invoked when someone configures the plugin. A user can configure a plugin by selecting Options->Preferences->Plug-ins->General Purpose, clicking on the plug-in in the right hand pane and then pressing the 'Configure selected plug-in' button. Note that I will refer to this as 'configuring the plugin' from now on as that much typing is annoying.

While we would normally add code to 'init' to set up our UI and event notification system, let's keep it even simpler than that (we'll cover the basics of that in a future tutorial). Let's add the API calls to the 'config' method for now. Just to see how they work.

===wa_ipc.h===
The top secret, knows everything, key to the executive washroom file is called wa_ipc.h. This file defines constants for all of the Winamp 2 API methods that are made available for external developers. And they are fairly well documented (gasp). Yes, I know this sounds impossible, when do developers actually write documentation? Well trust me this file is very well documented so it does happen.

This header can be found in the SDK under the Winamp SDK\Winamp directory. Add these two lines to the top of gen_myplugin.cpp, beneath the existing includes:
<source lang="cpp">
#include "wa_ipc.h"
#include <stdio.h>
</source>

But wait! This isn't enough. There's always a catch. The compiler has no idea where to find wa_ipc.h. So we have to tell it. So, in Visual Studio, navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp subdirectory under the directory where you installed the Winamp SDK. Now Visual studio should be able to find the header.

===Calling an API Method===
Hmmm, what should we do....What to do?....I know. How about we get the version of Winamp that is currently running? Sounds like a useful thing for a plug-in to do. Place the following code into the 'config' method, immediately under the MessageBox about the config event.

<source lang="cpp">
wchar_t msg[1024];

int version = SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSION);
int majVersion = WINAMP_VERSION_MAJOR(version);
int minVersion = WINAMP_VERSION_MINOR(version);

wsprintf(msg,L"The version of Winamp is: %x\n"
L"Major version: %x\nMinor version: %x\n",
version,
majVersion,
minVersion
);

MessageBox(plugin.hwndParent,msg,L"Winamp Version",MB_OK);
</source>

Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.) Start Winamp. The first thing you should see is the message about 'init' being called. 'Configure' the plugin and you should see the 'config' event message, press OK. If you've done everything correctly you should now see the version message box appear.

===Examining the Code===
The first line declares a buffer of 1024 wchar_t. This buffer is used to format output that we want to add to the MessageBox.

The second line uses Windows SendMessage API to send a message, WM_WA_IPC (second parameter), in this case to plugin.hwndParent (first parameter). WM_WA_IPC indicates a message that Winamp is supposed to handle rather than Windows itself. The third parameter is usually used to pass a parameter (known as a WPARAM in Windows) and is set to 0. The fourth parameter (known as an LPARAM in Windows) is a constant that identifies what we want Winamp to do for us, in this case 'get me the version of winamp'.

But 'Hold on Thar Partner' you might be saying. Where did that plugin.hwndParent come from? We didn't set it in our plug-in. Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it. Notice the method winampGetGeneralPurposePlugin(), it is called by Winamp to retrieve the plugin. This method actually returns a reference to the plugin. Cool huh? Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in. The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.

The next two lines use macros defined in WA_IPC.h to break apart the version into major and minor numbers. Another useful feature when you need to know the version of Winamp to determine whether a feature is supported.

The rest of the new lines format a wide string (wsprintf) so we can use it in MessageBox to print it to the screen.

===Examining the wa_ipc.h file===
How did I know what to use for WPARAM and LPARAM? Well the wa_ipc.h file of course. Go ahead and open it in Visual Studio. The first thing you'll notice is blocks of comments. Blocks of comments? OH YEAH. Let's just look at the comments for five minutes, I'll wait......Seriously, if you scroll down in this file you'll see the Winamp 2 API methods. Searching for IPC_GETVERSION will take you right to the description of how the method works.

Sometimes the method description will indicate that a method is only available at a certain level of Winamp, such as 'requires Winamp 5.0+', i.e. the reason we needed the IPC_GETVERSION.

You may also notice that some methods have both 'normal' and 'wide' versions. 'normal' versions take ANSI/ASCII parameters while 'wide' versions take UNICODE chars and strings.

===Adding another API===
Let's try another API call. Put the following after the previous MessageBox:
<source lang="cpp">
char *winampVersion;

winampVersion = (char *)SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSIONSTRING);
MessageBoxA(NULL,winampVersion,"Winamp Version 2",MB_OK);
</source>
The SendMessage in this code is requesting a string containing the version of the Winamp executable. It will return a char * to a string such as '5.57 build 2514 Beta'. This is useful for fields such as in the Help->About dialog.

The next line invokes the Windows MessageBoxA API to display an ANSI string. I meant to do that. No, no, I really did. I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers. This means that there may be some conversion required before using strings. Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings. The UNICODE version would have a "W" on the end. Versions with neither actually depend on whether the preprocessor directive UNICODE is defined (a setting in the project).

Replace the line with the call to MessageBoxA with the following:
<source lang="cpp">
wsprintf(msg,L"String Version: %S\n",winampVersion);
MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
</source>
See it works. Notice the "%S" (upper case S) in wsprintf this time rather than "%s" (lower case s). "%S" says the input value is an ANSI string and wsprintf can handle it correctly to create the string used in the MessageBox (since UNICODE is defined for this project MessageBox will invoke MessageBoxW).

===Another API call===
Add the following after the previous MessageBox statement:
<source lang="cpp">
enqueueFileWithMetaStruct eFWMS = {0};
eFWMS.filename="c:\\test\\folder\\test.mp3";
eFWMS.title = "Test It Good";
eFWMS.length = 300;
SendMessage(plugin.hwndParent,WM_WA_IPC,(WPARAM)&eFWMS,IPC_ENQUEUEFILE);
</source>
You can use a real filename if you have one. The title and length fields are only used by Winamp in the Winamp playlist until the file is actually played. At that point Winamp will look inside the file for the real title and length.

This example shows how to use that WPARAM thingy (thingy is a technical term). In this method the WPARAM gives Winamp information to use along with the request, in this case a pointer to a structure. The enqueueFileWithMetaStruct structure is defined in WA_IPC.h. The structure contains the path and filename, a title and the length of the song in seconds. This method will Enqueue the file to be played at the bottom of the Winamp playlist.

Compile, copy, restart Winamp and configure your plugin. After four message boxes (less if you became fed up with them and removed some), you will notice that the specified file has been added to the Winamp Playlist with the specified title and length. Note, that if the file does not actually exist, Winamp will simply skip over it when you try and play it.

===What's in a UI===
Now that I think I've gotten the point across let's get rid of those Message Boxes and create some real UI. The first thing we need to....hmmm, footsteps....gotta go....talk about this next time.

Basic Plugin Guide - Tutorial

2009-08-07T15:49:08Z

SMonty: /* Adding another API */

==Accessing information from Winamp==
Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit. While this is really cool, it lacks something. Maybe it needs to do something. Let's fix that now.

===Keeping it simple===
In order to keep these explanations simple, I'd rather not add a lot of code to create a Windows UI. We will eventually create a UI, but first let's invoke some Winamp 2 API methods. Just to see how they work.

When we last left our hero....err plugin, we had created three methods 'init', 'config' and 'quit'. 'init' is invoked by Winamp when the plugin is first loaded. 'quit' is invoked by Winamp when the plugin is unloaded, i.e., when Winamp is closing. 'config' is invoked when someone configures the plugin. A user can configure a plugin by selecting Options->Preferences->Plug-ins->General Purpose, clicking on the plug-in in the right hand pane and then pressing the 'Configure selected plug-in' button. Note that I will refer to this as 'configuring the plugin' from now on as that much typing is annoying.

While we would normally add code to 'init' to set up our UI and event notification system, let's keep it even simpler than that (we'll cover the basics of that in a future tutorial). Let's add the API calls to the 'config' method for now. Just to see how they work.

===wa_ipc.h===
The top secret, knows everything, key to the executive washroom file is called wa_ipc.h. This file defines constants for all of the Winamp 2 API methods that are made available for external developers. And they are fairly well documented (gasp). Yes, I know this sounds impossible, when do developers actually write documentation? Well trust me this file is very well documented so it does happen.

This header can be found in the SDK under the Winamp SDK\Winamp directory. Add these two lines to the top of gen_myplugin.cpp, beneath the existing includes:
<source lang="cpp">
#include "wa_ipc.h"
#include <stdio.h>
</source>

But wait! This isn't enough. There's always a catch. The compiler has no idea where to find wa_ipc.h. So we have to tell it. So, in Visual Studio, navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp subdirectory under the directory where you installed the Winamp SDK. Now Visual studio should be able to find the header.

===Calling an API Method===
Hmmm, what should we do....What to do?....I know. How about we get the version of Winamp that is currently running? Sounds like a useful thing for a plug-in to do. Place the following code into the 'config' method, immediately under the MessageBox about the config event.

<source lang="cpp">
wchar_t msg[1024];

int version = SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSION);
int majVersion = WINAMP_VERSION_MAJOR(version);
int minVersion = WINAMP_VERSION_MINOR(version);

wsprintf(msg,L"The version of Winamp is: %x\n"
L"Major version: %x\nMinor version: %x\n",
version,
majVersion,
minVersion
);

MessageBox(plugin.hwndParent,msg,L"Winamp Version",MB_OK);
</source>

Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.) Start Winamp. The first thing you should see is the message about 'init' being called. 'Configure' the plugin and you should see the 'config' event message, press OK. If you've done everything correctly you should now see the version message box appear.

===Examining the Code===
The first line declares a buffer of 1024 wchar_t. This buffer is used to format output that we want to add to the MessageBox.

The second line uses Windows SendMessage API to send a message, WM_WA_IPC (second parameter), in this case to plugin.hwndParent (first parameter). WM_WA_IPC indicates a message that Winamp is supposed to handle rather than Windows itself. The third parameter is usually used to pass a parameter (known as a WPARAM in Windows) and is set to 0. The fourth parameter (known as an LPARAM in Windows) is a constant that identifies what we want Winamp to do for us, in this case 'get me the version of winamp'.

But 'Hold on Thar Partner' you might be saying. Where did that plugin.hwndParent come from? We didn't set it in our plug-in. Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it. Notice the method winampGetGeneralPurposePlugin(), it is called by Winamp to retrieve the plugin. This method actually returns a reference to the plugin. Cool huh? Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in. The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.

The next two lines use macros defined in WA_IPC.h to break apart the version into major and minor numbers. Another useful feature when you need to know the version of Winamp to determine whether a feature is supported.

The rest of the new lines format a wide string (wsprintf) so we can use it in MessageBox to print it to the screen.

===Examining the wa_ipc.h file===
How did I know what to use for WPARAM and LPARAM? Well the wa_ipc.h file of course. Go ahead and open it in Visual Studio. The first thing you'll notice is blocks of comments. Blocks of comments? OH YEAH. Let's just look at the comments for five minutes, I'll wait......Seriously, if you scroll down in this file you'll see the Winamp 2 API methods. Searching for IPC_GETVERSION will take you right to the description of how the method works.

Sometimes the method description will indicate that a method is only available at a certain level of Winamp, such as 'requires Winamp 5.0+', i.e. the reason we needed the IPC_GETVERSION.

You may also notice that some methods have both 'normal' and 'wide' versions. 'normal' versions take ANSI/ASCII parameters while 'wide' versions take UNICODE chars and strings.

===Adding another API===
Let's try another API call. Put the following after the previous MessageBox:
<source lang="cpp">
char *winampVersion;

winampVersion = (char *)SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSIONSTRING);
MessageBoxA(NULL,winampVersion,"Winamp Version 2",MB_OK);
</source>
The SendMessage in this code is requesting a string containing the version of the Winamp executable. It will return a char * to a string such as '5.57 build 2514 Beta'. This is useful for fields such as in the Help->About dialog.

The next line invokes the Windows MessageBoxA API to display an ANSI string. I meant to do that. No, no, I really did. I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers. This means that there may be some conversion required before using strings. Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings. The UNICODE version would have a "W" on the end. Versions with neither actually depend on whether the preprocessor directive UNICODE is defined (a setting in the project).

Replace the line with the call to MessageBoxA with the following:
<source lang="cpp">
wsprintf(msg,L"String Version: %S\n",winampVersion);
MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
</source>
See it works. Notice the "%S" (upper case S) in wsprintf this time rather than "%s" (lower case s). "%S" says the input value is an ANSI string and wsprintf can handle it correctly to create the string used in the MessageBox (since UNICODE is defined for this project MessageBox will invoke MessageBoxW).

===Another API call===
Add the following after the previous MessageBox statement:
<source lang="cpp">
enqueueFileWithMetaStruct eFWMS = {0};
eFWMS.filename="c:\\test\\folder\\test.mp3";
eFWMS.title = "Test It Good";
eFWMS.length = 300;
SendMessage(plugin.hwndParent,WM_WA_IPC,(WPARAM)&eFWMS,IPC_ENQUEUEFILE);
</source>
You can use a real filename if you have one. The title and length fields are only used by Winamp in the Winamp playlist until the file is actually played, then Winamp will look inside the file for the real title and length.

This example shows how to use that WPARAM thingy (thingy is a technical term). In this method the WPARAM gives Winamp information to use along with the request, in this case the filename and path, a title and length. This method will Enqueue the file to be played at the bottom of the Winamp playlist.

Compile, copy, restart Winamp and configure your plugin. After four message boxes (less if you became fed up with them all and removed some), you will notice that the specified file has been added to the Winamp Playlist with the specified title and length. Note, that if the file does not actually exist, Winamp will simply skip over it when you try and play it.

===What's in a UI===
Now that I think I've gotten the point across let's get rid of those Message Boxes and create some real UI. The first thing we need to....hmmm, footsteps....gotta go....talk about this next time.

Basic Plugin Guide - Tutorial

2009-08-07T15:47:07Z

SMonty: /* Adding another API */

==Accessing information from Winamp==
Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit. While this is really cool, it lacks something. Maybe it needs to do something. Let's fix that now.

===Keeping it simple===
In order to keep these explanations simple, I'd rather not add a lot of code to create a Windows UI. We will eventually create a UI, but first let's invoke some Winamp 2 API methods. Just to see how they work.

When we last left our hero....err plugin, we had created three methods 'init', 'config' and 'quit'. 'init' is invoked by Winamp when the plugin is first loaded. 'quit' is invoked by Winamp when the plugin is unloaded, i.e., when Winamp is closing. 'config' is invoked when someone configures the plugin. A user can configure a plugin by selecting Options->Preferences->Plug-ins->General Purpose, clicking on the plug-in in the right hand pane and then pressing the 'Configure selected plug-in' button. Note that I will refer to this as 'configuring the plugin' from now on as that much typing is annoying.

While we would normally add code to 'init' to set up our UI and event notification system, let's keep it even simpler than that (we'll cover the basics of that in a future tutorial). Let's add the API calls to the 'config' method for now. Just to see how they work.

===wa_ipc.h===
The top secret, knows everything, key to the executive washroom file is called wa_ipc.h. This file defines constants for all of the Winamp 2 API methods that are made available for external developers. And they are fairly well documented (gasp). Yes, I know this sounds impossible, when do developers actually write documentation? Well trust me this file is very well documented so it does happen.

This header can be found in the SDK under the Winamp SDK\Winamp directory. Add these two lines to the top of gen_myplugin.cpp, beneath the existing includes:
<source lang="cpp">
#include "wa_ipc.h"
#include <stdio.h>
</source>

But wait! This isn't enough. There's always a catch. The compiler has no idea where to find wa_ipc.h. So we have to tell it. So, in Visual Studio, navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp subdirectory under the directory where you installed the Winamp SDK. Now Visual studio should be able to find the header.

===Calling an API Method===
Hmmm, what should we do....What to do?....I know. How about we get the version of Winamp that is currently running? Sounds like a useful thing for a plug-in to do. Place the following code into the 'config' method, immediately under the MessageBox about the config event.

<source lang="cpp">
wchar_t msg[1024];

int version = SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSION);
int majVersion = WINAMP_VERSION_MAJOR(version);
int minVersion = WINAMP_VERSION_MINOR(version);

wsprintf(msg,L"The version of Winamp is: %x\n"
L"Major version: %x\nMinor version: %x\n",
version,
majVersion,
minVersion
);

MessageBox(plugin.hwndParent,msg,L"Winamp Version",MB_OK);
</source>

Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.) Start Winamp. The first thing you should see is the message about 'init' being called. 'Configure' the plugin and you should see the 'config' event message, press OK. If you've done everything correctly you should now see the version message box appear.

===Examining the Code===
The first line declares a buffer of 1024 wchar_t. This buffer is used to format output that we want to add to the MessageBox.

The second line uses Windows SendMessage API to send a message, WM_WA_IPC (second parameter), in this case to plugin.hwndParent (first parameter). WM_WA_IPC indicates a message that Winamp is supposed to handle rather than Windows itself. The third parameter is usually used to pass a parameter (known as a WPARAM in Windows) and is set to 0. The fourth parameter (known as an LPARAM in Windows) is a constant that identifies what we want Winamp to do for us, in this case 'get me the version of winamp'.

But 'Hold on Thar Partner' you might be saying. Where did that plugin.hwndParent come from? We didn't set it in our plug-in. Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it. Notice the method winampGetGeneralPurposePlugin(), it is called by Winamp to retrieve the plugin. This method actually returns a reference to the plugin. Cool huh? Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in. The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.

The next two lines use macros defined in WA_IPC.h to break apart the version into major and minor numbers. Another useful feature when you need to know the version of Winamp to determine whether a feature is supported.

The rest of the new lines format a wide string (wsprintf) so we can use it in MessageBox to print it to the screen.

===Examining the wa_ipc.h file===
How did I know what to use for WPARAM and LPARAM? Well the wa_ipc.h file of course. Go ahead and open it in Visual Studio. The first thing you'll notice is blocks of comments. Blocks of comments? OH YEAH. Let's just look at the comments for five minutes, I'll wait......Seriously, if you scroll down in this file you'll see the Winamp 2 API methods. Searching for IPC_GETVERSION will take you right to the description of how the method works.

Sometimes the method description will indicate that a method is only available at a certain level of Winamp, such as 'requires Winamp 5.0+', i.e. the reason we needed the IPC_GETVERSION.

You may also notice that some methods have both 'normal' and 'wide' versions. 'normal' versions take ANSI/ASCII parameters while 'wide' versions take UNICODE chars and strings.

===Adding another API===
Let's try another API call. Put the following after the previous MessageBox:
<source lang="cpp">
char *winampVersion;

winampVersion = (char *)SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSIONSTRING);
MessageBoxA(NULL,winampVersion,"Winamp Version 2",MB_OK);
</source>
The SendMessage in this code is requesting a string containing the version of the Winamp executable. It will return a char * to a string such as '5.57 build 2514 Beta'. This is useful for fields such as in the Help->About dialog.

The next line invokes the Windows MessageBoxA API to display an ANSI string. I meant to do that. No, no, I really did. I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers. This means that there may be some conversion required before using strings. Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings. The UNICODE version would have a "W" on the end. Versions with neither actually depend on whether the preprocessor directive UNICODE is defined (a setting in the project).

Replace the line with the call to MessageBoxA with the following:
<source lang="cpp">
wsprintf(msg,L"String Version: %S\n",winampVersion);
MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
</source>
See it works. Notice the '%S' in wsprintf. "%S" says the input value is an ANSI string and wsprintf can handle it correctly to create the string used in the MessageBox (since UNICODE is defined for this project).

===Another API call===
Add the following after the previous MessageBox statement:
<source lang="cpp">
enqueueFileWithMetaStruct eFWMS = {0};
eFWMS.filename="c:\\test\\folder\\test.mp3";
eFWMS.title = "Test It Good";
eFWMS.length = 300;
SendMessage(plugin.hwndParent,WM_WA_IPC,(WPARAM)&eFWMS,IPC_ENQUEUEFILE);
</source>
You can use a real filename if you have one. The title and length fields are only used by Winamp in the Winamp playlist until the file is actually played, then Winamp will look inside the file for the real title and length.

This example shows how to use that WPARAM thingy (thingy is a technical term). In this method the WPARAM gives Winamp information to use along with the request, in this case the filename and path, a title and length. This method will Enqueue the file to be played at the bottom of the Winamp playlist.

Compile, copy, restart Winamp and configure your plugin. After four message boxes (less if you became fed up with them all and removed some), you will notice that the specified file has been added to the Winamp Playlist with the specified title and length. Note, that if the file does not actually exist, Winamp will simply skip over it when you try and play it.

===What's in a UI===
Now that I think I've gotten the point across let's get rid of those Message Boxes and create some real UI. The first thing we need to....hmmm, footsteps....gotta go....talk about this next time.

Basic Plugin Guide - Tutorial

2009-08-07T15:41:36Z

SMonty: /* Examining the Code */

==Accessing information from Winamp==
Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit. While this is really cool, it lacks something. Maybe it needs to do something. Let's fix that now.

===Keeping it simple===
In order to keep these explanations simple, I'd rather not add a lot of code to create a Windows UI. We will eventually create a UI, but first let's invoke some Winamp 2 API methods. Just to see how they work.

When we last left our hero....err plugin, we had created three methods 'init', 'config' and 'quit'. 'init' is invoked by Winamp when the plugin is first loaded. 'quit' is invoked by Winamp when the plugin is unloaded, i.e., when Winamp is closing. 'config' is invoked when someone configures the plugin. A user can configure a plugin by selecting Options->Preferences->Plug-ins->General Purpose, clicking on the plug-in in the right hand pane and then pressing the 'Configure selected plug-in' button. Note that I will refer to this as 'configuring the plugin' from now on as that much typing is annoying.

While we would normally add code to 'init' to set up our UI and event notification system, let's keep it even simpler than that (we'll cover the basics of that in a future tutorial). Let's add the API calls to the 'config' method for now. Just to see how they work.

===wa_ipc.h===
The top secret, knows everything, key to the executive washroom file is called wa_ipc.h. This file defines constants for all of the Winamp 2 API methods that are made available for external developers. And they are fairly well documented (gasp). Yes, I know this sounds impossible, when do developers actually write documentation? Well trust me this file is very well documented so it does happen.

This header can be found in the SDK under the Winamp SDK\Winamp directory. Add these two lines to the top of gen_myplugin.cpp, beneath the existing includes:
<source lang="cpp">
#include "wa_ipc.h"
#include <stdio.h>
</source>

But wait! This isn't enough. There's always a catch. The compiler has no idea where to find wa_ipc.h. So we have to tell it. So, in Visual Studio, navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp subdirectory under the directory where you installed the Winamp SDK. Now Visual studio should be able to find the header.

===Calling an API Method===
Hmmm, what should we do....What to do?....I know. How about we get the version of Winamp that is currently running? Sounds like a useful thing for a plug-in to do. Place the following code into the 'config' method, immediately under the MessageBox about the config event.

<source lang="cpp">
wchar_t msg[1024];

int version = SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSION);
int majVersion = WINAMP_VERSION_MAJOR(version);
int minVersion = WINAMP_VERSION_MINOR(version);

wsprintf(msg,L"The version of Winamp is: %x\n"
L"Major version: %x\nMinor version: %x\n",
version,
majVersion,
minVersion
);

MessageBox(plugin.hwndParent,msg,L"Winamp Version",MB_OK);
</source>

Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.) Start Winamp. The first thing you should see is the message about 'init' being called. 'Configure' the plugin and you should see the 'config' event message, press OK. If you've done everything correctly you should now see the version message box appear.

===Examining the Code===
The first line declares a buffer of 1024 wchar_t. This buffer is used to format output that we want to add to the MessageBox.

The second line uses Windows SendMessage API to send a message, WM_WA_IPC (second parameter), in this case to plugin.hwndParent (first parameter). WM_WA_IPC indicates a message that Winamp is supposed to handle rather than Windows itself. The third parameter is usually used to pass a parameter (known as a WPARAM in Windows) and is set to 0. The fourth parameter (known as an LPARAM in Windows) is a constant that identifies what we want Winamp to do for us, in this case 'get me the version of winamp'.

But 'Hold on Thar Partner' you might be saying. Where did that plugin.hwndParent come from? We didn't set it in our plug-in. Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it. Notice the method winampGetGeneralPurposePlugin(), it is called by Winamp to retrieve the plugin. This method actually returns a reference to the plugin. Cool huh? Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in. The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.

The next two lines use macros defined in WA_IPC.h to break apart the version into major and minor numbers. Another useful feature when you need to know the version of Winamp to determine whether a feature is supported.

The rest of the new lines format a wide string (wsprintf) so we can use it in MessageBox to print it to the screen.

===Examining the wa_ipc.h file===
How did I know what to use for WPARAM and LPARAM? Well the wa_ipc.h file of course. Go ahead and open it in Visual Studio. The first thing you'll notice is blocks of comments. Blocks of comments? OH YEAH. Let's just look at the comments for five minutes, I'll wait......Seriously, if you scroll down in this file you'll see the Winamp 2 API methods. Searching for IPC_GETVERSION will take you right to the description of how the method works.

Sometimes the method description will indicate that a method is only available at a certain level of Winamp, such as 'requires Winamp 5.0+', i.e. the reason we needed the IPC_GETVERSION.

You may also notice that some methods have both 'normal' and 'wide' versions. 'normal' versions take ANSI/ASCII parameters while 'wide' versions take UNICODE chars and strings.

===Adding another API===
Let's try another API call. Put the following after the previous MessageBox:
<source lang="cpp">
char *winampVersion;

winampVersion = (char *)SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSIONSTRING);
MessageBoxA(NULL,winampVersion,"Winamp Version 2",MB_OK);
</source>
The SendMessage in this code is requesting a string version of the Winamp executable. It will return a char * to a string such as '5.57 build 2514 Beta'. This is useful for displaying the version and build number, such as in the Help->About dialog.

The next line invokes the Windows MessageBoxA API to display a ANSI string. I meant to do that. No, no, I really did. I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers. This means that there may be some conversion required before using strings. Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings.

Replace the line with the call to MessageBoxA with the following:
<source lang="cpp">
wsprintf(msg,L"String Version: %S\n",winampVersion);
MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
</source>
See it works. Notice the '%S' in wsprintf. "%S" says the input value is an ANSI string and wsprintf can handle it correctly.

===Another API call===
Add the following after the previous MessageBox statement:
<source lang="cpp">
enqueueFileWithMetaStruct eFWMS = {0};
eFWMS.filename="c:\\test\\folder\\test.mp3";
eFWMS.title = "Test It Good";
eFWMS.length = 300;
SendMessage(plugin.hwndParent,WM_WA_IPC,(WPARAM)&eFWMS,IPC_ENQUEUEFILE);
</source>
You can use a real filename if you have one. The title and length fields are only used by Winamp in the Winamp playlist until the file is actually played, then Winamp will look inside the file for the real title and length.

This example shows how to use that WPARAM thingy (thingy is a technical term). In this method the WPARAM gives Winamp information to use along with the request, in this case the filename and path, a title and length. This method will Enqueue the file to be played at the bottom of the Winamp playlist.

Compile, copy, restart Winamp and configure your plugin. After four message boxes (less if you became fed up with them all and removed some), you will notice that the specified file has been added to the Winamp Playlist with the specified title and length. Note, that if the file does not actually exist, Winamp will simply skip over it when you try and play it.

===What's in a UI===
Now that I think I've gotten the point across let's get rid of those Message Boxes and create some real UI. The first thing we need to....hmmm, footsteps....gotta go....talk about this next time.

Basic Plugin Guide - Tutorial

2009-08-07T15:37:21Z

SMonty: /* Calling an API Method */

==Accessing information from Winamp==
Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit. While this is really cool, it lacks something. Maybe it needs to do something. Let's fix that now.

===Keeping it simple===
In order to keep these explanations simple, I'd rather not add a lot of code to create a Windows UI. We will eventually create a UI, but first let's invoke some Winamp 2 API methods. Just to see how they work.

When we last left our hero....err plugin, we had created three methods 'init', 'config' and 'quit'. 'init' is invoked by Winamp when the plugin is first loaded. 'quit' is invoked by Winamp when the plugin is unloaded, i.e., when Winamp is closing. 'config' is invoked when someone configures the plugin. A user can configure a plugin by selecting Options->Preferences->Plug-ins->General Purpose, clicking on the plug-in in the right hand pane and then pressing the 'Configure selected plug-in' button. Note that I will refer to this as 'configuring the plugin' from now on as that much typing is annoying.

While we would normally add code to 'init' to set up our UI and event notification system, let's keep it even simpler than that (we'll cover the basics of that in a future tutorial). Let's add the API calls to the 'config' method for now. Just to see how they work.

===wa_ipc.h===
The top secret, knows everything, key to the executive washroom file is called wa_ipc.h. This file defines constants for all of the Winamp 2 API methods that are made available for external developers. And they are fairly well documented (gasp). Yes, I know this sounds impossible, when do developers actually write documentation? Well trust me this file is very well documented so it does happen.

This header can be found in the SDK under the Winamp SDK\Winamp directory. Add these two lines to the top of gen_myplugin.cpp, beneath the existing includes:
<source lang="cpp">
#include "wa_ipc.h"
#include <stdio.h>
</source>

But wait! This isn't enough. There's always a catch. The compiler has no idea where to find wa_ipc.h. So we have to tell it. So, in Visual Studio, navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp subdirectory under the directory where you installed the Winamp SDK. Now Visual studio should be able to find the header.

===Calling an API Method===
Hmmm, what should we do....What to do?....I know. How about we get the version of Winamp that is currently running? Sounds like a useful thing for a plug-in to do. Place the following code into the 'config' method, immediately under the MessageBox about the config event.

<source lang="cpp">
wchar_t msg[1024];

int version = SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSION);
int majVersion = WINAMP_VERSION_MAJOR(version);
int minVersion = WINAMP_VERSION_MINOR(version);

wsprintf(msg,L"The version of Winamp is: %x\n"
L"Major version: %x\nMinor version: %x\n",
version,
majVersion,
minVersion
);

MessageBox(plugin.hwndParent,msg,L"Winamp Version",MB_OK);
</source>

Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.) Start Winamp. The first thing you should see is the message about 'init' being called. 'Configure' the plugin and you should see the 'config' event message, press OK. If you've done everything correctly you should now see the version message box appear.

===Examining the Code===
The first line declares a buffer of 1024 wchar_t. This buffer is used to format output that we want to add to the MessageBox.

The second line uses Windows SendMessage API to send a message, WM_WA_IPC (second parameter), in this case to plugin.hwndParent (first parameter). WM_WA_IPC indicates a message that Winamp is supposed to handle rather than Windows itself. The third parameter is usually used to pass a parameter (known as a WPARAM in Windows) and is set to 0. The fourth parameter (known as an LPARAM in Windows) is a constant that identifies what we want Winamp to do for us, in this case 'get me the version of winamp'.

But 'Hold on Thar Partner' you might be saying. Where did that plugin.hwndParent come from? We didn't set it in our plug-in. Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it. Notice the method used to retrieve the plugin (winampGetGeneralPurposePlugin) actually returns a reference to the plugin? Cool huh, Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in. The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.

The next two lines use macros defined in WA_IPC.h to break apart the version into major and minor numbers. Another useful feature when you need to know the version of Winamp to determine whether a feature is supported.

The rest of the new lines format a wide string (wsprintf) so we can use it in MessageBox to print it to the screen.
===Examining the wa_ipc.h file===
How did I know what to use for WPARAM and LPARAM? Well the wa_ipc.h file of course. Go ahead and open it in Visual Studio. The first thing you'll notice is blocks of comments. Blocks of comments? OH YEAH. Let's just look at the comments for five minutes, I'll wait......Seriously, if you scroll down in this file you'll see the Winamp 2 API methods. Searching for IPC_GETVERSION will take you right to the description of how the method works.

Sometimes the method description will indicate that a method is only available at a certain level of Winamp, such as 'requires Winamp 5.0+', i.e. the reason we needed the IPC_GETVERSION.

You may also notice that some methods have both 'normal' and 'wide' versions. 'normal' versions take ANSI/ASCII parameters while 'wide' versions take UNICODE chars and strings.

===Adding another API===
Let's try another API call. Put the following after the previous MessageBox:
<source lang="cpp">
char *winampVersion;

winampVersion = (char *)SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSIONSTRING);
MessageBoxA(NULL,winampVersion,"Winamp Version 2",MB_OK);
</source>
The SendMessage in this code is requesting a string version of the Winamp executable. It will return a char * to a string such as '5.57 build 2514 Beta'. This is useful for displaying the version and build number, such as in the Help->About dialog.

The next line invokes the Windows MessageBoxA API to display a ANSI string. I meant to do that. No, no, I really did. I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers. This means that there may be some conversion required before using strings. Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings.

Replace the line with the call to MessageBoxA with the following:
<source lang="cpp">
wsprintf(msg,L"String Version: %S\n",winampVersion);
MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
</source>
See it works. Notice the '%S' in wsprintf. "%S" says the input value is an ANSI string and wsprintf can handle it correctly.

===Another API call===
Add the following after the previous MessageBox statement:
<source lang="cpp">
enqueueFileWithMetaStruct eFWMS = {0};
eFWMS.filename="c:\\test\\folder\\test.mp3";
eFWMS.title = "Test It Good";
eFWMS.length = 300;
SendMessage(plugin.hwndParent,WM_WA_IPC,(WPARAM)&eFWMS,IPC_ENQUEUEFILE);
</source>
You can use a real filename if you have one. The title and length fields are only used by Winamp in the Winamp playlist until the file is actually played, then Winamp will look inside the file for the real title and length.

This example shows how to use that WPARAM thingy (thingy is a technical term). In this method the WPARAM gives Winamp information to use along with the request, in this case the filename and path, a title and length. This method will Enqueue the file to be played at the bottom of the Winamp playlist.

Compile, copy, restart Winamp and configure your plugin. After four message boxes (less if you became fed up with them all and removed some), you will notice that the specified file has been added to the Winamp Playlist with the specified title and length. Note, that if the file does not actually exist, Winamp will simply skip over it when you try and play it.

===What's in a UI===
Now that I think I've gotten the point across let's get rid of those Message Boxes and create some real UI. The first thing we need to....hmmm, footsteps....gotta go....talk about this next time.

Basic Plugin Guide - Tutorial

2009-08-07T15:35:07Z

SMonty: /* Calling an API Method */

==Accessing information from Winamp==
Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit. While this is really cool, it lacks something. Maybe it needs to do something. Let's fix that now.

===Keeping it simple===
In order to keep these explanations simple, I'd rather not add a lot of code to create a Windows UI. We will eventually create a UI, but first let's invoke some Winamp 2 API methods. Just to see how they work.

When we last left our hero....err plugin, we had created three methods 'init', 'config' and 'quit'. 'init' is invoked by Winamp when the plugin is first loaded. 'quit' is invoked by Winamp when the plugin is unloaded, i.e., when Winamp is closing. 'config' is invoked when someone configures the plugin. A user can configure a plugin by selecting Options->Preferences->Plug-ins->General Purpose, clicking on the plug-in in the right hand pane and then pressing the 'Configure selected plug-in' button. Note that I will refer to this as 'configuring the plugin' from now on as that much typing is annoying.

While we would normally add code to 'init' to set up our UI and event notification system, let's keep it even simpler than that (we'll cover the basics of that in a future tutorial). Let's add the API calls to the 'config' method for now. Just to see how they work.

===wa_ipc.h===
The top secret, knows everything, key to the executive washroom file is called wa_ipc.h. This file defines constants for all of the Winamp 2 API methods that are made available for external developers. And they are fairly well documented (gasp). Yes, I know this sounds impossible, when do developers actually write documentation? Well trust me this file is very well documented so it does happen.

This header can be found in the SDK under the Winamp SDK\Winamp directory. Add these two lines to the top of gen_myplugin.cpp, beneath the existing includes:
<source lang="cpp">
#include "wa_ipc.h"
#include <stdio.h>
</source>

But wait! This isn't enough. There's always a catch. The compiler has no idea where to find wa_ipc.h. So we have to tell it. So, in Visual Studio, navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp subdirectory under the directory where you installed the Winamp SDK. Now Visual studio should be able to find the header.

===Calling an API Method===
Hmmm, what should we do....What to do?....I know. How about we get the version of Winamp that is currently running? Sounds like a useful thing for a plug-in to do. Place the following code into the 'config' method, immediately under the MessageBox about the config event.

<source lang="cpp">
wchar_t msg[1024];

int version = SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSION);
int majVersion = WINAMP_VERSION_MAJOR(version);
int minVersion = WINAMP_VERSION_MINOR(version);

wsprintf(msg,L"The version of Winamp is: %x\n"
L"Major version: %x\nMinor version: %x\n",
version,
majVersion,
minVersion
);

MessageBox(plugin.hwndParent,msg,L"Winamp Version",MB_OK);
</source>

Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.) Start Winamp. After Winamp starts and you see the message about the 'init' being called, 'configure' the plugin and you should see the 'config' event message, press OK. If you've done everything correctly you should now see the version message box appear.

===Examining the Code===
The first line declares a buffer of 1024 wchar_t. This buffer is used to format output that we want to add to the MessageBox.

The second line uses Windows SendMessage API to send a message, WM_WA_IPC (second parameter), in this case to plugin.hwndParent (first parameter). WM_WA_IPC indicates a message that Winamp is supposed to handle rather than Windows itself. The third parameter is usually used to pass a parameter (known as a WPARAM in Windows) and is set to 0. The fourth parameter (known as an LPARAM in Windows) is a constant that identifies what we want Winamp to do for us, in this case 'get me the version of winamp'.

But 'Hold on Thar Partner' you might be saying. Where did that plugin.hwndParent come from? We didn't set it in our plug-in. Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it. Notice the method used to retrieve the plugin (winampGetGeneralPurposePlugin) actually returns a reference to the plugin? Cool huh, Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in. The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.

The next two lines use macros defined in WA_IPC.h to break apart the version into major and minor numbers. Another useful feature when you need to know the version of Winamp to determine whether a feature is supported.

The rest of the new lines format a wide string (wsprintf) so we can use it in MessageBox to print it to the screen.
===Examining the wa_ipc.h file===
How did I know what to use for WPARAM and LPARAM? Well the wa_ipc.h file of course. Go ahead and open it in Visual Studio. The first thing you'll notice is blocks of comments. Blocks of comments? OH YEAH. Let's just look at the comments for five minutes, I'll wait......Seriously, if you scroll down in this file you'll see the Winamp 2 API methods. Searching for IPC_GETVERSION will take you right to the description of how the method works.

Sometimes the method description will indicate that a method is only available at a certain level of Winamp, such as 'requires Winamp 5.0+', i.e. the reason we needed the IPC_GETVERSION.

You may also notice that some methods have both 'normal' and 'wide' versions. 'normal' versions take ANSI/ASCII parameters while 'wide' versions take UNICODE chars and strings.

===Adding another API===
Let's try another API call. Put the following after the previous MessageBox:
<source lang="cpp">
char *winampVersion;

winampVersion = (char *)SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSIONSTRING);
MessageBoxA(NULL,winampVersion,"Winamp Version 2",MB_OK);
</source>
The SendMessage in this code is requesting a string version of the Winamp executable. It will return a char * to a string such as '5.57 build 2514 Beta'. This is useful for displaying the version and build number, such as in the Help->About dialog.

The next line invokes the Windows MessageBoxA API to display a ANSI string. I meant to do that. No, no, I really did. I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers. This means that there may be some conversion required before using strings. Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings.

Replace the line with the call to MessageBoxA with the following:
<source lang="cpp">
wsprintf(msg,L"String Version: %S\n",winampVersion);
MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
</source>
See it works. Notice the '%S' in wsprintf. "%S" says the input value is an ANSI string and wsprintf can handle it correctly.

===Another API call===
Add the following after the previous MessageBox statement:
<source lang="cpp">
enqueueFileWithMetaStruct eFWMS = {0};
eFWMS.filename="c:\\test\\folder\\test.mp3";
eFWMS.title = "Test It Good";
eFWMS.length = 300;
SendMessage(plugin.hwndParent,WM_WA_IPC,(WPARAM)&eFWMS,IPC_ENQUEUEFILE);
</source>
You can use a real filename if you have one. The title and length fields are only used by Winamp in the Winamp playlist until the file is actually played, then Winamp will look inside the file for the real title and length.

This example shows how to use that WPARAM thingy (thingy is a technical term). In this method the WPARAM gives Winamp information to use along with the request, in this case the filename and path, a title and length. This method will Enqueue the file to be played at the bottom of the Winamp playlist.

Compile, copy, restart Winamp and configure your plugin. After four message boxes (less if you became fed up with them all and removed some), you will notice that the specified file has been added to the Winamp Playlist with the specified title and length. Note, that if the file does not actually exist, Winamp will simply skip over it when you try and play it.

===What's in a UI===
Now that I think I've gotten the point across let's get rid of those Message Boxes and create some real UI. The first thing we need to....hmmm, footsteps....gotta go....talk about this next time.

Basic Plugin Guide - Tutorial

2009-08-07T15:34:09Z

SMonty: /* wa_ipc.h */

==Accessing information from Winamp==
Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit. While this is really cool, it lacks something. Maybe it needs to do something. Let's fix that now.

===Keeping it simple===
In order to keep these explanations simple, I'd rather not add a lot of code to create a Windows UI. We will eventually create a UI, but first let's invoke some Winamp 2 API methods. Just to see how they work.

When we last left our hero....err plugin, we had created three methods 'init', 'config' and 'quit'. 'init' is invoked by Winamp when the plugin is first loaded. 'quit' is invoked by Winamp when the plugin is unloaded, i.e., when Winamp is closing. 'config' is invoked when someone configures the plugin. A user can configure a plugin by selecting Options->Preferences->Plug-ins->General Purpose, clicking on the plug-in in the right hand pane and then pressing the 'Configure selected plug-in' button. Note that I will refer to this as 'configuring the plugin' from now on as that much typing is annoying.

While we would normally add code to 'init' to set up our UI and event notification system, let's keep it even simpler than that (we'll cover the basics of that in a future tutorial). Let's add the API calls to the 'config' method for now. Just to see how they work.

===wa_ipc.h===
The top secret, knows everything, key to the executive washroom file is called wa_ipc.h. This file defines constants for all of the Winamp 2 API methods that are made available for external developers. And they are fairly well documented (gasp). Yes, I know this sounds impossible, when do developers actually write documentation? Well trust me this file is very well documented so it does happen.

This header can be found in the SDK under the Winamp SDK\Winamp directory. Add these two lines to the top of gen_myplugin.cpp, beneath the existing includes:
<source lang="cpp">
#include "wa_ipc.h"
#include <stdio.h>
</source>

But wait! This isn't enough. There's always a catch. The compiler has no idea where to find wa_ipc.h. So we have to tell it. So, in Visual Studio, navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp subdirectory under the directory where you installed the Winamp SDK. Now Visual studio should be able to find the header.

===Calling an API Method===
Hmmm, what should we do....How about we get the version of Winamp that is currently running? Sounds like a useful thing for a plug-in to do. Place the following code into the 'config' method, immediately under the MessageBox about the config event.

<source lang="cpp">
wchar_t msg[1024];

int version = SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSION);
int majVersion = WINAMP_VERSION_MAJOR(version);
int minVersion = WINAMP_VERSION_MINOR(version);

wsprintf(msg,L"The version of Winamp is: %x\n"
L"Major version: %x\nMinor version: %x\n",
version,
majVersion,
minVersion
);

MessageBox(plugin.hwndParent,msg,L"Winamp Version",MB_OK);
</source>

Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.) Start Winamp. After Winamp starts and you see the message about the 'init' being called, 'configure' the plugin and you should see the 'config' event message, press OK. If you've done everything correctly you should now see the version message box appear.

===Examining the Code===
The first line declares a buffer of 1024 wchar_t. This buffer is used to format output that we want to add to the MessageBox.

The second line uses Windows SendMessage API to send a message, WM_WA_IPC (second parameter), in this case to plugin.hwndParent (first parameter). WM_WA_IPC indicates a message that Winamp is supposed to handle rather than Windows itself. The third parameter is usually used to pass a parameter (known as a WPARAM in Windows) and is set to 0. The fourth parameter (known as an LPARAM in Windows) is a constant that identifies what we want Winamp to do for us, in this case 'get me the version of winamp'.

But 'Hold on Thar Partner' you might be saying. Where did that plugin.hwndParent come from? We didn't set it in our plug-in. Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it. Notice the method used to retrieve the plugin (winampGetGeneralPurposePlugin) actually returns a reference to the plugin? Cool huh, Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in. The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.

The next two lines use macros defined in WA_IPC.h to break apart the version into major and minor numbers. Another useful feature when you need to know the version of Winamp to determine whether a feature is supported.

The rest of the new lines format a wide string (wsprintf) so we can use it in MessageBox to print it to the screen.
===Examining the wa_ipc.h file===
How did I know what to use for WPARAM and LPARAM? Well the wa_ipc.h file of course. Go ahead and open it in Visual Studio. The first thing you'll notice is blocks of comments. Blocks of comments? OH YEAH. Let's just look at the comments for five minutes, I'll wait......Seriously, if you scroll down in this file you'll see the Winamp 2 API methods. Searching for IPC_GETVERSION will take you right to the description of how the method works.

Sometimes the method description will indicate that a method is only available at a certain level of Winamp, such as 'requires Winamp 5.0+', i.e. the reason we needed the IPC_GETVERSION.

You may also notice that some methods have both 'normal' and 'wide' versions. 'normal' versions take ANSI/ASCII parameters while 'wide' versions take UNICODE chars and strings.

===Adding another API===
Let's try another API call. Put the following after the previous MessageBox:
<source lang="cpp">
char *winampVersion;

winampVersion = (char *)SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSIONSTRING);
MessageBoxA(NULL,winampVersion,"Winamp Version 2",MB_OK);
</source>
The SendMessage in this code is requesting a string version of the Winamp executable. It will return a char * to a string such as '5.57 build 2514 Beta'. This is useful for displaying the version and build number, such as in the Help->About dialog.

The next line invokes the Windows MessageBoxA API to display a ANSI string. I meant to do that. No, no, I really did. I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers. This means that there may be some conversion required before using strings. Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings.

Replace the line with the call to MessageBoxA with the following:
<source lang="cpp">
wsprintf(msg,L"String Version: %S\n",winampVersion);
MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
</source>
See it works. Notice the '%S' in wsprintf. "%S" says the input value is an ANSI string and wsprintf can handle it correctly.

===Another API call===
Add the following after the previous MessageBox statement:
<source lang="cpp">
enqueueFileWithMetaStruct eFWMS = {0};
eFWMS.filename="c:\\test\\folder\\test.mp3";
eFWMS.title = "Test It Good";
eFWMS.length = 300;
SendMessage(plugin.hwndParent,WM_WA_IPC,(WPARAM)&eFWMS,IPC_ENQUEUEFILE);
</source>
You can use a real filename if you have one. The title and length fields are only used by Winamp in the Winamp playlist until the file is actually played, then Winamp will look inside the file for the real title and length.

This example shows how to use that WPARAM thingy (thingy is a technical term). In this method the WPARAM gives Winamp information to use along with the request, in this case the filename and path, a title and length. This method will Enqueue the file to be played at the bottom of the Winamp playlist.

Compile, copy, restart Winamp and configure your plugin. After four message boxes (less if you became fed up with them all and removed some), you will notice that the specified file has been added to the Winamp Playlist with the specified title and length. Note, that if the file does not actually exist, Winamp will simply skip over it when you try and play it.

===What's in a UI===
Now that I think I've gotten the point across let's get rid of those Message Boxes and create some real UI. The first thing we need to....hmmm, footsteps....gotta go....talk about this next time.

Basic Plugin Guide - Tutorial

2009-08-07T15:30:32Z

SMonty: /* Accessing information from Winamp */

==Accessing information from Winamp==
Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit. While this is really cool, it lacks something. Maybe it needs to do something. Let's fix that now.

===Keeping it simple===
In order to keep these explanations simple, I'd rather not add a lot of code to create a Windows UI. We will eventually create a UI, but first let's invoke some Winamp 2 API methods. Just to see how they work.

When we last left our hero....err plugin, we had created three methods 'init', 'config' and 'quit'. 'init' is invoked by Winamp when the plugin is first loaded. 'quit' is invoked by Winamp when the plugin is unloaded, i.e., when Winamp is closing. 'config' is invoked when someone configures the plugin. A user can configure a plugin by selecting Options->Preferences->Plug-ins->General Purpose, clicking on the plug-in in the right hand pane and then pressing the 'Configure selected plug-in' button. Note that I will refer to this as 'configuring the plugin' from now on as that much typing is annoying.

While we would normally add code to 'init' to set up our UI and event notification system, let's keep it even simpler than that (we'll cover the basics of that in a future tutorial). Let's add the API calls to the 'config' method for now. Just to see how they work.

===wa_ipc.h===
The top secret, knows everything, key to the executive washroom file is called wa_ipc.h. This file defines constants for all of the Winamp 2 API methods that are made available for external developers. And they are fairly well documented (gasp). Yes, I know this sounds impossible, when do developers actually write documentation? Well trust me this file is very well documented so it does happen.

This header can be found in the SDK under the Winamp SDK\Winamp directory. Add these two lines to the top of gen_myplugin.cpp, beneath the existing includes:
<source lang="cpp">
#include "wa_ipc.h"
#include <stdio.h>
</source>

But wait! This isn't enough. There's always a catch. The compiler has no idea where to find wa_ipc.h. So we have to tell it. Navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp directory under the base directory where you installed the Winamp SDK. Now Visual studio should be able to find the header.

===Calling an API Method===
Hmmm, what should we do....How about we get the version of Winamp that is currently running? Sounds like a useful thing for a plug-in to do. Place the following code into the 'config' method, immediately under the MessageBox about the config event.

<source lang="cpp">
wchar_t msg[1024];

int version = SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSION);
int majVersion = WINAMP_VERSION_MAJOR(version);
int minVersion = WINAMP_VERSION_MINOR(version);

wsprintf(msg,L"The version of Winamp is: %x\n"
L"Major version: %x\nMinor version: %x\n",
version,
majVersion,
minVersion
);

MessageBox(plugin.hwndParent,msg,L"Winamp Version",MB_OK);
</source>

Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.) Start Winamp. After Winamp starts and you see the message about the 'init' being called, 'configure' the plugin and you should see the 'config' event message, press OK. If you've done everything correctly you should now see the version message box appear.

===Examining the Code===
The first line declares a buffer of 1024 wchar_t. This buffer is used to format output that we want to add to the MessageBox.

The second line uses Windows SendMessage API to send a message, WM_WA_IPC (second parameter), in this case to plugin.hwndParent (first parameter). WM_WA_IPC indicates a message that Winamp is supposed to handle rather than Windows itself. The third parameter is usually used to pass a parameter (known as a WPARAM in Windows) and is set to 0. The fourth parameter (known as an LPARAM in Windows) is a constant that identifies what we want Winamp to do for us, in this case 'get me the version of winamp'.

But 'Hold on Thar Partner' you might be saying. Where did that plugin.hwndParent come from? We didn't set it in our plug-in. Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it. Notice the method used to retrieve the plugin (winampGetGeneralPurposePlugin) actually returns a reference to the plugin? Cool huh, Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in. The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.

The next two lines use macros defined in WA_IPC.h to break apart the version into major and minor numbers. Another useful feature when you need to know the version of Winamp to determine whether a feature is supported.

The rest of the new lines format a wide string (wsprintf) so we can use it in MessageBox to print it to the screen.
===Examining the wa_ipc.h file===
How did I know what to use for WPARAM and LPARAM? Well the wa_ipc.h file of course. Go ahead and open it in Visual Studio. The first thing you'll notice is blocks of comments. Blocks of comments? OH YEAH. Let's just look at the comments for five minutes, I'll wait......Seriously, if you scroll down in this file you'll see the Winamp 2 API methods. Searching for IPC_GETVERSION will take you right to the description of how the method works.

Sometimes the method description will indicate that a method is only available at a certain level of Winamp, such as 'requires Winamp 5.0+', i.e. the reason we needed the IPC_GETVERSION.

You may also notice that some methods have both 'normal' and 'wide' versions. 'normal' versions take ANSI/ASCII parameters while 'wide' versions take UNICODE chars and strings.

===Adding another API===
Let's try another API call. Put the following after the previous MessageBox:
<source lang="cpp">
char *winampVersion;

winampVersion = (char *)SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSIONSTRING);
MessageBoxA(NULL,winampVersion,"Winamp Version 2",MB_OK);
</source>
The SendMessage in this code is requesting a string version of the Winamp executable. It will return a char * to a string such as '5.57 build 2514 Beta'. This is useful for displaying the version and build number, such as in the Help->About dialog.

The next line invokes the Windows MessageBoxA API to display a ANSI string. I meant to do that. No, no, I really did. I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers. This means that there may be some conversion required before using strings. Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings.

Replace the line with the call to MessageBoxA with the following:
<source lang="cpp">
wsprintf(msg,L"String Version: %S\n",winampVersion);
MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
</source>
See it works. Notice the '%S' in wsprintf. "%S" says the input value is an ANSI string and wsprintf can handle it correctly.

===Another API call===
Add the following after the previous MessageBox statement:
<source lang="cpp">
enqueueFileWithMetaStruct eFWMS = {0};
eFWMS.filename="c:\\test\\folder\\test.mp3";
eFWMS.title = "Test It Good";
eFWMS.length = 300;
SendMessage(plugin.hwndParent,WM_WA_IPC,(WPARAM)&eFWMS,IPC_ENQUEUEFILE);
</source>
You can use a real filename if you have one. The title and length fields are only used by Winamp in the Winamp playlist until the file is actually played, then Winamp will look inside the file for the real title and length.

This example shows how to use that WPARAM thingy (thingy is a technical term). In this method the WPARAM gives Winamp information to use along with the request, in this case the filename and path, a title and length. This method will Enqueue the file to be played at the bottom of the Winamp playlist.

Compile, copy, restart Winamp and configure your plugin. After four message boxes (less if you became fed up with them all and removed some), you will notice that the specified file has been added to the Winamp Playlist with the specified title and length. Note, that if the file does not actually exist, Winamp will simply skip over it when you try and play it.

===What's in a UI===
Now that I think I've gotten the point across let's get rid of those Message Boxes and create some real UI. The first thing we need to....hmmm, footsteps....gotta go....talk about this next time.

Basic Plugin Guide - Tutorial

2009-07-13T21:37:51Z

SMonty: /* One Last API call (for now) */

==Accessing information from Winamp==
Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit. While this is really cool, it lacks something. Let's fix that now.

===Keeping it simple===
In order to keep these explanations simple, I'd rather not add a lot of code to create a Windows UI. We will eventually create a UI, but first let's invoke some Winamp 2 API methods. Just to see how they work.

When we last left our hero....err plugin, we had created three methods 'init', 'config' and 'quit'. 'init' is invoked by Winamp when the plugin is first loaded. 'quit' is invoked by Winamp when the plugin is unloaded, i.e., when Winamp is closing. 'config' is invoked when someone configures the plugin. A user can configure a plugin by selecting Options->Preferences->Plug-ins->General Purpose, clicking on the plug-in in the right hand pane and then pressing the 'Configure selected plug-in' button. Note that I will refer to this as 'configuring the plugin' from now on as that much typing is annoying.

While we would normally add code to 'init' to set up our UI and event notification system, let's keep it even simpler than that (we'll cover the basics of that in a future tutorial). Let's add the API calls to the 'config' method for now. Just to see how they work.

===wa_ipc.h===
The top secret, knows everything, key to the executive washroom file is called wa_ipc.h. This file defines constants for all of the Winamp 2 API methods that are made available for external developers. And they are fairly well documented (gasp). Yes, I know this sounds impossible, when do developers actually write documentation? Well trust me this file is very well documented so it does happen.

This header can be found in the SDK under the Winamp SDK\Winamp directory. Add these two lines to the top of gen_myplugin.cpp:
<source lang="cpp">
#include "wa_ipc.h"
#include <stdio.h>
</source>

But wait! This isn't enough. There's always a catch. The compiler has no idea where to find wa_ipc.h. So we have to tell it. Navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp directory under the base directory where you installed the Winamp SDK. Now Visual studio should be able to find the header.

===Calling an API Method===
Hmmm, what should we do....How about we get the version of Winamp that is currently running? Sounds like a useful thing for a plug-in to do. Place the following code into the 'config' method, immediately under the MessageBox about the config event.

<source lang="cpp">
wchar_t msg[1024];

int version = SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSION);
int majVersion = WINAMP_VERSION_MAJOR(version);
int minVersion = WINAMP_VERSION_MINOR(version);

wsprintf(msg,L"The version of Winamp is: %x\n"
L"Major version: %x\nMinor version: %x\n",
version,
majVersion,
minVersion
);

MessageBox(plugin.hwndParent,msg,L"Winamp Version",MB_OK);
</source>

Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.) Start Winamp. After Winamp starts and you see the message about the 'init' being called, 'configure' the plugin and you should see the 'config' event message, press OK. If you've done everything correctly you should now see the version message box appear.

===Examining the Code===
The first line declares a buffer of 1024 wchar_t. This buffer is used to format output that we want to add to the MessageBox.

The second line uses Windows SendMessage API to send a message, WM_WA_IPC (second parameter), in this case to plugin.hwndParent (first parameter). WM_WA_IPC indicates a message that Winamp is supposed to handle rather than Windows itself. The third parameter is usually used to pass a parameter (known as a WPARAM in Windows) and is set to 0. The fourth parameter (known as an LPARAM in Windows) is a constant that identifies what we want Winamp to do for us, in this case 'get me the version of winamp'.

But 'Hold on Thar Partner' you might be saying. Where did that plugin.hwndParent come from? We didn't set it in our plug-in. Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it. Notice the method used to retrieve the plugin (winampGetGeneralPurposePlugin) actually returns a reference to the plugin? Cool huh, Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in. The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.

The next two lines use macros defined in WA_IPC.h to break apart the version into major and minor numbers. Another useful feature when you need to know the version of Winamp to determine whether a feature is supported.

The rest of the new lines format a wide string (wsprintf) so we can use it in MessageBox to print it to the screen.
===Examining the wa_ipc.h file===
How did I know what to use for WPARAM and LPARAM? Well the wa_ipc.h file of course. Go ahead and open it in Visual Studio. The first thing you'll notice is blocks of comments. Blocks of comments? OH YEAH. Let's just look at the comments for five minutes, I'll wait......Seriously, if you scroll down in this file you'll see the Winamp 2 API methods. Searching for IPC_GETVERSION will take you right to the description of how the method works.

Sometimes the method description will indicate that a method is only available at a certain level of Winamp, such as 'requires Winamp 5.0+', i.e. the reason we needed the IPC_GETVERSION.

You may also notice that some methods have both 'normal' and 'wide' versions. 'normal' versions take ANSI/ASCII parameters while 'wide' versions take UNICODE chars and strings.

===Adding another API===
Let's try another API call. Put the following after the previous MessageBox:
<source lang="cpp">
char *winampVersion;

winampVersion = (char *)SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSIONSTRING);
MessageBoxA(NULL,winampVersion,"Winamp Version 2",MB_OK);
</source>
The SendMessage in this code is requesting a string version of the Winamp executable. It will return a char * to a string such as '5.57 build 2514 Beta'. This is useful for displaying the version and build number, such as in the Help->About dialog.

The next line invokes the Windows MessageBoxA API to display a ANSI string. I meant to do that. No, no, I really did. I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers. This means that there may be some conversion required before using strings. Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings.

Replace the line with the call to MessageBoxA with the following:
<source lang="cpp">
wsprintf(msg,L"String Version: %S\n",winampVersion);
MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
</source>
See it works. Notice the '%S' in wsprintf. "%S" says the input value is an ANSI string and wsprintf can handle it correctly.

===Another API call===
Add the following after the previous MessageBox statement:
<source lang="cpp">
enqueueFileWithMetaStruct eFWMS = {0};
eFWMS.filename="c:\\test\\folder\\test.mp3";
eFWMS.title = "Test It Good";
eFWMS.length = 300;
SendMessage(plugin.hwndParent,WM_WA_IPC,(WPARAM)&eFWMS,IPC_ENQUUEFILE);
</source>
You can use a real filename if you have one. The title and length fields are only used by Winamp in the Winamp playlist until the file is actually played, then Winamp will look inside the file for the real title and length.

This example shows how to use that WPARAM thingy (thingy is a technical term). In this method the WPARAM gives Winamp information to use along with the request, in this case the filename and path, a title and length. This method will Enqueue the file to be played at the bottom of the Winamp playlist.

Compile, copy, restart Winamp and configure your plugin. After four message boxes (less if you became fed up with them all and removed some), you will notice that the specified file has been added to the Winamp Playlist with the specified title and length. Note, that if the file does not actually exist, Winamp will simply skip over it when you try and play it.

===What's in a UI===
Now that I think I've gotten the point across let's get rid of those Message Boxes and create some real UI. The first thing we need to....hmmm, footsteps....gotta go....talk about this next time.

Basic Plugin Guide - Tutorial

2009-07-13T21:10:49Z

SMonty: /* Adding another API */

==Accessing information from Winamp==
Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit. While this is really cool, it lacks something. Let's fix that now.

===Keeping it simple===
In order to keep these explanations simple, I'd rather not add a lot of code to create a Windows UI. We will eventually create a UI, but first let's invoke some Winamp 2 API methods. Just to see how they work.

When we last left our hero....err plugin, we had created three methods 'init', 'config' and 'quit'. 'init' is invoked by Winamp when the plugin is first loaded. 'quit' is invoked by Winamp when the plugin is unloaded, i.e., when Winamp is closing. 'config' is invoked when someone configures the plugin. A user can configure a plugin by selecting Options->Preferences->Plug-ins->General Purpose, clicking on the plug-in in the right hand pane and then pressing the 'Configure selected plug-in' button. Note that I will refer to this as 'configuring the plugin' from now on as that much typing is annoying.

While we would normally add code to 'init' to set up our UI and event notification system, let's keep it even simpler than that (we'll cover the basics of that in a future tutorial). Let's add the API calls to the 'config' method for now. Just to see how they work.

===wa_ipc.h===
The top secret, knows everything, key to the executive washroom file is called wa_ipc.h. This file defines constants for all of the Winamp 2 API methods that are made available for external developers. And they are fairly well documented (gasp). Yes, I know this sounds impossible, when do developers actually write documentation? Well trust me this file is very well documented so it does happen.

This header can be found in the SDK under the Winamp SDK\Winamp directory. Add these two lines to the top of gen_myplugin.cpp:
<source lang="cpp">
#include "wa_ipc.h"
#include <stdio.h>
</source>

But wait! This isn't enough. There's always a catch. The compiler has no idea where to find wa_ipc.h. So we have to tell it. Navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp directory under the base directory where you installed the Winamp SDK. Now Visual studio should be able to find the header.

===Calling an API Method===
Hmmm, what should we do....How about we get the version of Winamp that is currently running? Sounds like a useful thing for a plug-in to do. Place the following code into the 'config' method, immediately under the MessageBox about the config event.

<source lang="cpp">
wchar_t msg[1024];

int version = SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSION);
int majVersion = WINAMP_VERSION_MAJOR(version);
int minVersion = WINAMP_VERSION_MINOR(version);

wsprintf(msg,L"The version of Winamp is: %x\n"
L"Major version: %x\nMinor version: %x\n",
version,
majVersion,
minVersion
);

MessageBox(plugin.hwndParent,msg,L"Winamp Version",MB_OK);
</source>

Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.) Start Winamp. After Winamp starts and you see the message about the 'init' being called, 'configure' the plugin and you should see the 'config' event message, press OK. If you've done everything correctly you should now see the version message box appear.

===Examining the Code===
The first line declares a buffer of 1024 wchar_t. This buffer is used to format output that we want to add to the MessageBox.

The second line uses Windows SendMessage API to send a message, WM_WA_IPC (second parameter), in this case to plugin.hwndParent (first parameter). WM_WA_IPC indicates a message that Winamp is supposed to handle rather than Windows itself. The third parameter is usually used to pass a parameter (known as a WPARAM in Windows) and is set to 0. The fourth parameter (known as an LPARAM in Windows) is a constant that identifies what we want Winamp to do for us, in this case 'get me the version of winamp'.

But 'Hold on Thar Partner' you might be saying. Where did that plugin.hwndParent come from? We didn't set it in our plug-in. Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it. Notice the method used to retrieve the plugin (winampGetGeneralPurposePlugin) actually returns a reference to the plugin? Cool huh, Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in. The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.

The next two lines use macros defined in WA_IPC.h to break apart the version into major and minor numbers. Another useful feature when you need to know the version of Winamp to determine whether a feature is supported.

The rest of the new lines format a wide string (wsprintf) so we can use it in MessageBox to print it to the screen.
===Examining the wa_ipc.h file===
How did I know what to use for WPARAM and LPARAM? Well the wa_ipc.h file of course. Go ahead and open it in Visual Studio. The first thing you'll notice is blocks of comments. Blocks of comments? OH YEAH. Let's just look at the comments for five minutes, I'll wait......Seriously, if you scroll down in this file you'll see the Winamp 2 API methods. Searching for IPC_GETVERSION will take you right to the description of how the method works.

Sometimes the method description will indicate that a method is only available at a certain level of Winamp, such as 'requires Winamp 5.0+', i.e. the reason we needed the IPC_GETVERSION.

You may also notice that some methods have both 'normal' and 'wide' versions. 'normal' versions take ANSI/ASCII parameters while 'wide' versions take UNICODE chars and strings.

===Adding another API===
Let's try another API call. Put the following after the previous MessageBox:
<source lang="cpp">
char *winampVersion;

winampVersion = (char *)SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSIONSTRING);
MessageBoxA(NULL,winampVersion,"Winamp Version 2",MB_OK);
</source>
The SendMessage in this code is requesting a string version of the Winamp executable. It will return a char * to a string such as '5.57 build 2514 Beta'. This is useful for displaying the version and build number, such as in the Help->About dialog.

The next line invokes the Windows MessageBoxA API to display a ANSI string. I meant to do that. No, no, I really did. I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers. This means that there may be some conversion required before using strings. Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings.

Replace the line with the call to MessageBoxA with the following:
<source lang="cpp">
wsprintf(msg,L"String Version: %S\n",winampVersion);
MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
</source>
See it works. Notice the '%S' in wsprintf. "%S" says the input value is an ANSI string and wsprintf can handle it correctly.

===One Last API call (for now)===

Basic Plugin Guide - Tutorial

2009-07-13T21:10:18Z

SMonty: /* Examining the wa_ipc.h file */

==Accessing information from Winamp==
Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit. While this is really cool, it lacks something. Let's fix that now.

===Keeping it simple===
In order to keep these explanations simple, I'd rather not add a lot of code to create a Windows UI. We will eventually create a UI, but first let's invoke some Winamp 2 API methods. Just to see how they work.

When we last left our hero....err plugin, we had created three methods 'init', 'config' and 'quit'. 'init' is invoked by Winamp when the plugin is first loaded. 'quit' is invoked by Winamp when the plugin is unloaded, i.e., when Winamp is closing. 'config' is invoked when someone configures the plugin. A user can configure a plugin by selecting Options->Preferences->Plug-ins->General Purpose, clicking on the plug-in in the right hand pane and then pressing the 'Configure selected plug-in' button. Note that I will refer to this as 'configuring the plugin' from now on as that much typing is annoying.

While we would normally add code to 'init' to set up our UI and event notification system, let's keep it even simpler than that (we'll cover the basics of that in a future tutorial). Let's add the API calls to the 'config' method for now. Just to see how they work.

===wa_ipc.h===
The top secret, knows everything, key to the executive washroom file is called wa_ipc.h. This file defines constants for all of the Winamp 2 API methods that are made available for external developers. And they are fairly well documented (gasp). Yes, I know this sounds impossible, when do developers actually write documentation? Well trust me this file is very well documented so it does happen.

This header can be found in the SDK under the Winamp SDK\Winamp directory. Add these two lines to the top of gen_myplugin.cpp:
<source lang="cpp">
#include "wa_ipc.h"
#include <stdio.h>
</source>

But wait! This isn't enough. There's always a catch. The compiler has no idea where to find wa_ipc.h. So we have to tell it. Navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp directory under the base directory where you installed the Winamp SDK. Now Visual studio should be able to find the header.

===Calling an API Method===
Hmmm, what should we do....How about we get the version of Winamp that is currently running? Sounds like a useful thing for a plug-in to do. Place the following code into the 'config' method, immediately under the MessageBox about the config event.

<source lang="cpp">
wchar_t msg[1024];

int version = SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSION);
int majVersion = WINAMP_VERSION_MAJOR(version);
int minVersion = WINAMP_VERSION_MINOR(version);

wsprintf(msg,L"The version of Winamp is: %x\n"
L"Major version: %x\nMinor version: %x\n",
version,
majVersion,
minVersion
);

MessageBox(plugin.hwndParent,msg,L"Winamp Version",MB_OK);
</source>

Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.) Start Winamp. After Winamp starts and you see the message about the 'init' being called, 'configure' the plugin and you should see the 'config' event message, press OK. If you've done everything correctly you should now see the version message box appear.

===Examining the Code===
The first line declares a buffer of 1024 wchar_t. This buffer is used to format output that we want to add to the MessageBox.

The second line uses Windows SendMessage API to send a message, WM_WA_IPC (second parameter), in this case to plugin.hwndParent (first parameter). WM_WA_IPC indicates a message that Winamp is supposed to handle rather than Windows itself. The third parameter is usually used to pass a parameter (known as a WPARAM in Windows) and is set to 0. The fourth parameter (known as an LPARAM in Windows) is a constant that identifies what we want Winamp to do for us, in this case 'get me the version of winamp'.

But 'Hold on Thar Partner' you might be saying. Where did that plugin.hwndParent come from? We didn't set it in our plug-in. Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it. Notice the method used to retrieve the plugin (winampGetGeneralPurposePlugin) actually returns a reference to the plugin? Cool huh, Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in. The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.

The next two lines use macros defined in WA_IPC.h to break apart the version into major and minor numbers. Another useful feature when you need to know the version of Winamp to determine whether a feature is supported.

The rest of the new lines format a wide string (wsprintf) so we can use it in MessageBox to print it to the screen.
===Examining the wa_ipc.h file===
How did I know what to use for WPARAM and LPARAM? Well the wa_ipc.h file of course. Go ahead and open it in Visual Studio. The first thing you'll notice is blocks of comments. Blocks of comments? OH YEAH. Let's just look at the comments for five minutes, I'll wait......Seriously, if you scroll down in this file you'll see the Winamp 2 API methods. Searching for IPC_GETVERSION will take you right to the description of how the method works.

Sometimes the method description will indicate that a method is only available at a certain level of Winamp, such as 'requires Winamp 5.0+', i.e. the reason we needed the IPC_GETVERSION.

You may also notice that some methods have both 'normal' and 'wide' versions. 'normal' versions take ANSI/ASCII parameters while 'wide' versions take UNICODE chars and strings.

===Adding another API===
Let's try another API call. Put the following after the previous MessageBox:
<source lang="cpp">
char *winampVersion;

winampVersion = (char *)SendMessage(plugin.hwndParent,WM_WA_IPC,0,IPC_GETVERSIONSTRING);
MessageBoxA(NULL,winampVersion,"Winamp Version 2",MB_OK);
</source>
The SendMessage in this code is requesting a string version of the Winamp executable. It will return a char * to a string such as '5.57 build 2514 Beta'. This is useful for displaying the version and build number, such as in the Help->About dialog.

The next line invokes the Windows MessageBoxA API to display a ANSI string. I meant to do that. No, no, I really did. I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers. This means that there may be some conversion required before using strings. Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings.

Replace the line with the call to MessageBoxA with the following:
<source lang="cpp">
wsprintf(msg,L"String Version: %S\n",winampVersion);
MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
</source>
See it works. Notice the '%S' in wsprintf. "%S" says the input value is ANSI string and wsprintf can handle it correctly.

===One Last API call (for now)===

Basic Plugin Guide - Tutorial

2009-07-13T20:04:00Z

SMonty: /* Examining the Code */

Basic Plugin Guide - Tutorial

2009-07-13T19:46:02Z

SMonty: New page: ==Accessing information from Winamp== Our first page Beginner's Basic Plugin Guide showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, confi...

Beginner's Basic Plugin Guide

2009-07-13T18:18:24Z

SMonty: /* What's next? */

So you want to write a plugin for Winamp but don't know where to start? This is the page for you. We'll walk you through creating a very basic plugin that does '''nothing'''. You can then expand on the code to do whatever you want.

==Notes==
This guide assumes you're developing using Visual Studio in a Windows environment. It also assumes you have some familiarity with programming. For people that don't, try using google. We'll have to expand this guide in the future to give out more pointers.

== Basic credits ==
The following code has been created based on samples from [http://forums.winamp.com/showthread.php?s=&threadid=128915 several] [http://forums.winamp.com/showthread.php?s=&threadid=82651 forum] [http://forums.winamp.com/showthread.php?s=&threadid=103667 threads]. Many thanks go out to forum members Kaboon, kichik, baafie, burek021, and bananskib for their code examples and advice.

== What you need ==
To begin, you'll need a tool that lets you write code. Check out the [[Plug-in_Developer#Tools|Tools]] page. You can get a free copy of Visual Studio C++ Express [http://www.microsoft.com/Express/ here]. You'll probably also want a copy of Winamp itself, to test your plugin; you can get that on the Winamp site [http://www.winamp.com/player here].

# Download [http://www.microsoft.com/Express/ Visual C++ Express].
# Double-click the file (it's probably called something like 'vcsetup.exe') and run the installer.
# You're practically good to go!

== Creating a project ==
The first thing we need to do is create a place to store our code. In Visual Studio this is called a 'project'.

# Launch Visual Studio by clicking Start -> Programs -> Microsoft Visual C++ Express Edition -> Microsoft Visual C++ Express Edition
# When Visual Studio opens, select File -> New -> Project
# For creating Winamp plugins, we want to create code that compiles into a .dll, which Visual Studio 2008 refers to as a "Class Library". So in the 'New Project' window select Visual C++ -> CLR -> Class Library.
# Give your project a name (see below) and select a location.

'''Note:''' Winamp classifies plugins based on the first part of their .dll filename, so you will need to properly name the file if you want Winamp to recognize it (details: the Winamp client searches for and loads plugins based on the first part of their filenames. This saves time and space instead of loading all dlls and then detecting which ones are real plugins). Thus, to make our basic plugin we want to name the first part of the file 'gen_'. '''Be sure to start your plugin name with 'gen_' to make it work properly.'''

All of the examples in this guide will assume you named your plugin 'gen_myplugin', but you can call it whatever you like as long as it starts with 'gen_' (for generic plugin) and ends with '.dll'.

Once you click okay Visual Studio should create a bunch of boilerplate code for you, and throw some files in your project with names like "resource.h", "stdafx.h", "AssemblyInfo.cpp", and so on. The main files we want to work with are called 'gen_myplugin.h' and 'gen_myplugin.cpp'. If you double-click to view them you should see code that looks something like this:

<nowiki><contents of gen_myplugin.h></nowiki>
<source lang="cpp">
// gen_myplugin.h

#pragma once

using namespace System;

namespace gen_myplugin {

public ref class Class1
{
// TODO: Add your methods for this class here.
};
}
</source>
<nowiki><end contents of gen_myplugin.h></nowiki>

<nowiki><contents of gen_myplugin.cpp></nowiki>
<source lang="cpp">
// This is the main DLL file.

#include "stdafx.h"

#include "gen_myplugin.h"

</source>
<nowiki><end contents of gen_myplugin.cpp></nowiki>

We want to edit these files to make a basic plugin.

== Creating a basic plugin ==

=== Basic plugin code ===
To create your plugin, just copy/paste the following code into gen_myplugin.h and gen_myplugin.cpp.

<nowiki><basic gen_myplugin.h></nowiki>
<source lang="cpp">

#ifndef gen_myplugin_h
//---------------------------------------------------------------------------
#define gen_myplugin_h
#include <windows.h>

// plugin version (don't touch this)
#define GPPHDR_VER 0x10

// plugin name/title (change this to something you like)
#define PLUGIN_NAME "My first generic Winamp plugin!"

// main structure with plugin information, version, name...
typedef struct {
int version; // version of the plugin structure
char *description; // name/title of the plugin
int (*init)(); // function which will be executed on init event
void (*config)(); // function which will be executed on config event
void (*quit)(); // function which will be executed on quit event
HWND hwndParent; // hwnd of the Winamp client main window (stored by Winamp when dll is loaded)
HINSTANCE hDllInstance; // hinstance of this plugin DLL. (stored by Winamp when dll is loaded)
} winampGeneralPurposePlugin;

#endif
</source>
<nowiki><end basic gen_myplugin.h></nowiki>

<nowiki><basic gen_myplugin.cpp></nowiki>
<source lang="cpp">
/*

Winamp generic plugin template code.
This code should be just the basics needed to get a plugin up and running.
You can then expand the code to build your own plugin.

Updated details compiled June 2009 by culix, based on the excellent code examples
and advice of forum members Kaboon, kichik, baafie, burek021, and bananskib.
Thanks for the help everyone!

*/

#include "stdafx.h"
#include <windows.h>
#include "gen_myplugin.h"

// these are callback functions/events which will be called by Winamp
int init(void);
void config(void);
void quit(void);

// this structure contains plugin information, version, name...
// GPPHDR_VER is the version of the winampGeneralPurposePlugin (GPP) structure
winampGeneralPurposePlugin plugin = {
GPPHDR_VER, // version of the plugin, defined in "gen_myplugin.h"
PLUGIN_NAME, // name/title of the plugin, defined in "gen_myplugin.h"
init, // function name which will be executed on init event
config, // function name which will be executed on config event
quit, // function name which will be executed on quit event
0, // handle to Winamp main window, loaded by winamp when this dll is loaded
0 // hinstance to this dll, loaded by winamp when this dll is loaded
};

// event functions follow

int init() {
//A basic messagebox that tells you the 'init' event has been triggered.
//If everything works you should see this message when you start Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Init event triggered for gen_myplugin. Plugin installed successfully!", L"", MB_OK);
return 0;
}

void config() {
//A basic messagebox that tells you the 'config' event has been triggered.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Config event triggered for gen_myplugin.", L"", MB_OK);
}

void quit() {
//A basic messagebox that tells you the 'quit' event has been triggered.
//If everything works you should see this message when you quit Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(0, L"Quit event triggered for gen_myplugin.", L"", MB_OK);
}

// This is an export function called by winamp which returns this plugin info.
// We wrap the code in 'extern "C"' to ensure the export isn't mangled if used in a CPP file.
extern "C" __declspec(dllexport) winampGeneralPurposePlugin * winampGetGeneralPurposePlugin() {
return &plugin;
}
</source>
<nowiki><end basic gen_myplugin.cpp></nowiki>

=== winampGeneralPurposePlugin===
You might be wondering why the last two fields in the winampGeneralPurposePlugin structure are left empty. You might have noticed the reference that is returned as part of the winampGetGeneralPurposePlugin() method. This is the method that the Winamp.exe calls when loading these gen_*.dll files. As part of loading the plugin, the Winamp.exe will store the handle to its main window and the hinstance for the plugin dll into these two fields. Since these are references, these values become available for use by the plugin.
=== Edit dependencies ===

By default Visual Studio removes some files we need to compile our code. Let's add those back in:

# Right-click on your project (the folder called 'gen_myplugin' in the Solution Explorer window on the left) and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)', so the box is blank.
# Click 'Apply', then 'OK', and then save your project.

=== Compiling the code ===

Once you have pasted this code into your .h and .cpp files, save your changes and compile the project. You can do this by pressing F7, or selecting Build -> Build Solution. If everything works, you should see some messages in Visual Studio's 'Output' window, with the final line saying something like

"========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped =========="

If so, congratulations! You have built your first plugin :) If instead you get an error message, please see the [[Beginner's Basic Plugin Guide#Troubleshooting|Troubleshooting]] section below.

=== Testing the plugin ===

If your project builds successfully, it will output a file called 'gen_myplugin.dll' into a 'Debug' or 'Release' folder in the same location you created your project. Look for that file now. We want to copy this file to C:\Program Files\Winamp\Plugins\, which is the folder Winamp examines to find all of its plugins.

# Copy your plugin .dll file into C:\Program Files\Winamp\Plugins\
# Close and re-open Winamp. If your plugin is installed correctly, you should see a popup window with the Init message you typed inside gen_myplugin.cpp. If so, congrats! Your plugin works.
# You can check to see your plugin name by clicking Options -> Preferences -> Plugins -> General purpose. Your plugin name should appear in that window.
# Click on your plugin to hilight it and then select the 'Configure Selected Plugin' button. This should cause the 'config' message to appear.
# If you exit Winamp, you should now see the Quit message pop up as the program exits.

== What's next? ==

So what's next? More guides still need to be written. Eventually there may be a guide for each type of plugin: [[Input_Plugin|Input]], [[Output_Plugin|Output]], [[Visualization_Plugin|Visualization]], [[DSP_Plugin|Audio Effect/DSP]], [[General_Purpose_Plugin|General Purpose]], [[Media_Library_Plugin|Media Library]] and [[Portable_Plugin|Portables]].

If you're looking to write a plugin, you may want to start by reading through the [[SDK_Contents]] and trying to find a code example that's similar to what you want to do.

Taking this page as a start of a tutorial on plugins, let's move on to actually calling the Winamp 2 API methods from within our newly created plugin. [[Basic Plugin Guide - Tutorial #2]]

----

== Troubleshooting ==
* '''I get an error message that looks like:'''

<pre>
1>gen_myplugin.obj : error LNK2028: unresolved token (0A00001D) "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)

1>gen_myplugin.obj : error LNK2019: unresolved external symbol "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)
</pre>

:'''Answer:''' By default Visual Studio Express 2008 doesn't include some files you need in the linker. For example, with our basic code we include windows.h, which is part of user32.dll. However, there is usually a '$(NoInherit)' command in our linker options that tell us not to include user32.dll. To fix this, try the following:

# Right-click on your project and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)'.
# Save and recompile

For more information see [http://stackoverflow.com/questions/739952/c-cli-linker-gives-unresolved-token-for-win32-function here] and [http://stackoverflow.com/questions/721387/i-get-lnk2028-when-trying-to-wrap-native-c-class-using-managed-c here].

* '''* I get an error like'''
<pre>
"1>.\gen_myplugin.cpp(25) : error C2146: syntax error : missing ';' before identifier 'plugin'"
</pre>

:'''Answer:''' This could be a namespace error. On this line

<source lang="cpp">
winampGeneralPurposePlugin plugin = {
</source>

we are creating a variable called 'plugin'. The variable's type, rather than being an integer ('int'), floating point number ('float'), or some other type, is of type 'winampGeneralPurposePlugin', which is a type we have created. This type is created in the header file with the code

<source lang="cpp">
typedef struct {
int version;
char *description;
int (*init)();
void (*config)();
void (*quit)();
HWND hwndParent;
HINSTANCE hDllInstance;
} winampGeneralPurposePlugin;
</source>

If you used Visual Studio's auto-generated code, you might have a line that looks like this:

<source lang="cpp">
namespace myplugin {
</source>

this line is telling Visual Studio to put everything inside the 'myplugin' namespace (read up on namespaces [http://en.wikipedia.org/wiki/Namespace here]). We get rid of the default boilerplate code, including the namespace, to make everything work.

Alternatively, you can change the declaration of the 'plugin' variable to say

<source lang="cpp">
myplugin::winampGeneralPurposePlugin plugin = {
</source>

This tells Visual Studio where to look for the winampGeneralPurposePlugin type (i.e., to look inside the 'myplugin' namespace). If you are new to programming or plugin creation, however, you probably don't need (or want) to mess with namespaces.

* '''I get an error like'''

<pre>
1>.\gen_myplugin.cpp(42) : error C2664: 'MessageBox' : cannot convert parameter 2 from 'const char [5]' to 'LPCTSTR'
1> Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or function-style cast
</pre>

:'''Answer:''' You need to change the string you pass to the MessageBox function to be of the right type. See the MSDN FAQ entry [http://social.msdn.microsoft.com/Forums/en-US/vclanguage/thread/c1b08c0a-a803-41c3-ac8c-84eba3be1ddb here]. You can most likely fix this by putting a capital 'L' in front of the string.

e.g. change <source lang="cpp">MessageBox(plugin.hwndParent, "Somestring", "", MB_OK);</source> to <source lang="cpp">MessageBox(plugin.hwndParent, L"Somestring", L"", MB_OK);</source>

TODO: What's the right way of doing this for plugins?
<pre> The answer here is to leave the Visual Studio option alone (set to use UNICODE)
and use the 'L' on the front of the strings. While you will find some parts of
Winamp still use ANSI strings, it is still meant to be an International application
and that means UNICODE.</pre>

* '''My plugin isn't working / My plugin doesn't show up in the Preferences menu.'''

:'''Answer:'''Did you name your plugin with the correct prefix, such as 'gen_myplugin'? If not it may not show up in the window.

TODO: How about other names/plugins? What's the real answer?
<pre> There are two commonly used methods to create plugins. The first is what is known as
Winamp 2, which we will get into shortly. Winamp 2 requires that plugins be prepended
with an identifier to their purpose, i.e., in_, out_, gen_, ml_, etc.

The second method is known as Wasabi, which is actually a framework used to share
information between application components. Wasabi files do not need a prefix.
</pre>
[[Category:Articles]]

Beginner's Basic Plugin Guide

2009-07-13T18:13:57Z

SMonty: /* Troubleshooting */

So you want to write a plugin for Winamp but don't know where to start? This is the page for you. We'll walk you through creating a very basic plugin that does '''nothing'''. You can then expand on the code to do whatever you want.

==Notes==
This guide assumes you're developing using Visual Studio in a Windows environment. It also assumes you have some familiarity with programming. For people that don't, try using google. We'll have to expand this guide in the future to give out more pointers.

== Basic credits ==
The following code has been created based on samples from [http://forums.winamp.com/showthread.php?s=&threadid=128915 several] [http://forums.winamp.com/showthread.php?s=&threadid=82651 forum] [http://forums.winamp.com/showthread.php?s=&threadid=103667 threads]. Many thanks go out to forum members Kaboon, kichik, baafie, burek021, and bananskib for their code examples and advice.

== What you need ==
To begin, you'll need a tool that lets you write code. Check out the [[Plug-in_Developer#Tools|Tools]] page. You can get a free copy of Visual Studio C++ Express [http://www.microsoft.com/Express/ here]. You'll probably also want a copy of Winamp itself, to test your plugin; you can get that on the Winamp site [http://www.winamp.com/player here].

# Download [http://www.microsoft.com/Express/ Visual C++ Express].
# Double-click the file (it's probably called something like 'vcsetup.exe') and run the installer.
# You're practically good to go!

== Creating a project ==
The first thing we need to do is create a place to store our code. In Visual Studio this is called a 'project'.

# Launch Visual Studio by clicking Start -> Programs -> Microsoft Visual C++ Express Edition -> Microsoft Visual C++ Express Edition
# When Visual Studio opens, select File -> New -> Project
# For creating Winamp plugins, we want to create code that compiles into a .dll, which Visual Studio 2008 refers to as a "Class Library". So in the 'New Project' window select Visual C++ -> CLR -> Class Library.
# Give your project a name (see below) and select a location.

'''Note:''' Winamp classifies plugins based on the first part of their .dll filename, so you will need to properly name the file if you want Winamp to recognize it (details: the Winamp client searches for and loads plugins based on the first part of their filenames. This saves time and space instead of loading all dlls and then detecting which ones are real plugins). Thus, to make our basic plugin we want to name the first part of the file 'gen_'. '''Be sure to start your plugin name with 'gen_' to make it work properly.'''

All of the examples in this guide will assume you named your plugin 'gen_myplugin', but you can call it whatever you like as long as it starts with 'gen_' (for generic plugin) and ends with '.dll'.

Once you click okay Visual Studio should create a bunch of boilerplate code for you, and throw some files in your project with names like "resource.h", "stdafx.h", "AssemblyInfo.cpp", and so on. The main files we want to work with are called 'gen_myplugin.h' and 'gen_myplugin.cpp'. If you double-click to view them you should see code that looks something like this:

<nowiki><contents of gen_myplugin.h></nowiki>
<source lang="cpp">
// gen_myplugin.h

#pragma once

using namespace System;

namespace gen_myplugin {

public ref class Class1
{
// TODO: Add your methods for this class here.
};
}
</source>
<nowiki><end contents of gen_myplugin.h></nowiki>

<nowiki><contents of gen_myplugin.cpp></nowiki>
<source lang="cpp">
// This is the main DLL file.

#include "stdafx.h"

#include "gen_myplugin.h"

</source>
<nowiki><end contents of gen_myplugin.cpp></nowiki>

We want to edit these files to make a basic plugin.

== Creating a basic plugin ==

=== Basic plugin code ===
To create your plugin, just copy/paste the following code into gen_myplugin.h and gen_myplugin.cpp.

<nowiki><basic gen_myplugin.h></nowiki>
<source lang="cpp">

#ifndef gen_myplugin_h
//---------------------------------------------------------------------------
#define gen_myplugin_h
#include <windows.h>

// plugin version (don't touch this)
#define GPPHDR_VER 0x10

// plugin name/title (change this to something you like)
#define PLUGIN_NAME "My first generic Winamp plugin!"

// main structure with plugin information, version, name...
typedef struct {
int version; // version of the plugin structure
char *description; // name/title of the plugin
int (*init)(); // function which will be executed on init event
void (*config)(); // function which will be executed on config event
void (*quit)(); // function which will be executed on quit event
HWND hwndParent; // hwnd of the Winamp client main window (stored by Winamp when dll is loaded)
HINSTANCE hDllInstance; // hinstance of this plugin DLL. (stored by Winamp when dll is loaded)
} winampGeneralPurposePlugin;

#endif
</source>
<nowiki><end basic gen_myplugin.h></nowiki>

<nowiki><basic gen_myplugin.cpp></nowiki>
<source lang="cpp">
/*

Winamp generic plugin template code.
This code should be just the basics needed to get a plugin up and running.
You can then expand the code to build your own plugin.

Updated details compiled June 2009 by culix, based on the excellent code examples
and advice of forum members Kaboon, kichik, baafie, burek021, and bananskib.
Thanks for the help everyone!

*/

#include "stdafx.h"
#include <windows.h>
#include "gen_myplugin.h"

// these are callback functions/events which will be called by Winamp
int init(void);
void config(void);
void quit(void);

// this structure contains plugin information, version, name...
// GPPHDR_VER is the version of the winampGeneralPurposePlugin (GPP) structure
winampGeneralPurposePlugin plugin = {
GPPHDR_VER, // version of the plugin, defined in "gen_myplugin.h"
PLUGIN_NAME, // name/title of the plugin, defined in "gen_myplugin.h"
init, // function name which will be executed on init event
config, // function name which will be executed on config event
quit, // function name which will be executed on quit event
0, // handle to Winamp main window, loaded by winamp when this dll is loaded
0 // hinstance to this dll, loaded by winamp when this dll is loaded
};

// event functions follow

int init() {
//A basic messagebox that tells you the 'init' event has been triggered.
//If everything works you should see this message when you start Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Init event triggered for gen_myplugin. Plugin installed successfully!", L"", MB_OK);
return 0;
}

void config() {
//A basic messagebox that tells you the 'config' event has been triggered.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Config event triggered for gen_myplugin.", L"", MB_OK);
}

void quit() {
//A basic messagebox that tells you the 'quit' event has been triggered.
//If everything works you should see this message when you quit Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(0, L"Quit event triggered for gen_myplugin.", L"", MB_OK);
}

// This is an export function called by winamp which returns this plugin info.
// We wrap the code in 'extern "C"' to ensure the export isn't mangled if used in a CPP file.
extern "C" __declspec(dllexport) winampGeneralPurposePlugin * winampGetGeneralPurposePlugin() {
return &plugin;
}
</source>
<nowiki><end basic gen_myplugin.cpp></nowiki>

=== winampGeneralPurposePlugin===
You might be wondering why the last two fields in the winampGeneralPurposePlugin structure are left empty. You might have noticed the reference that is returned as part of the winampGetGeneralPurposePlugin() method. This is the method that the Winamp.exe calls when loading these gen_*.dll files. As part of loading the plugin, the Winamp.exe will store the handle to its main window and the hinstance for the plugin dll into these two fields. Since these are references, these values become available for use by the plugin.
=== Edit dependencies ===

By default Visual Studio removes some files we need to compile our code. Let's add those back in:

# Right-click on your project (the folder called 'gen_myplugin' in the Solution Explorer window on the left) and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)', so the box is blank.
# Click 'Apply', then 'OK', and then save your project.

=== Compiling the code ===

Once you have pasted this code into your .h and .cpp files, save your changes and compile the project. You can do this by pressing F7, or selecting Build -> Build Solution. If everything works, you should see some messages in Visual Studio's 'Output' window, with the final line saying something like

"========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped =========="

If so, congratulations! You have built your first plugin :) If instead you get an error message, please see the [[Beginner's Basic Plugin Guide#Troubleshooting|Troubleshooting]] section below.

=== Testing the plugin ===

If your project builds successfully, it will output a file called 'gen_myplugin.dll' into a 'Debug' or 'Release' folder in the same location you created your project. Look for that file now. We want to copy this file to C:\Program Files\Winamp\Plugins\, which is the folder Winamp examines to find all of its plugins.

# Copy your plugin .dll file into C:\Program Files\Winamp\Plugins\
# Close and re-open Winamp. If your plugin is installed correctly, you should see a popup window with the Init message you typed inside gen_myplugin.cpp. If so, congrats! Your plugin works.
# You can check to see your plugin name by clicking Options -> Preferences -> Plugins -> General purpose. Your plugin name should appear in that window.
# Click on your plugin to hilight it and then select the 'Configure Selected Plugin' button. This should cause the 'config' message to appear.
# If you exit Winamp, you should now see the Quit message pop up as the program exits.

== What's next? ==

So what's next? We don't know. More guides still need to be written. Eventually there may be a guide for each type of plugin: [[Input_Plugin|Input]], [[Output_Plugin|Output]], [[Visualization_Plugin|Visualization]], [[DSP_Plugin|Audio Effect/DSP]], [[General_Purpose_Plugin|General Purpose]], [[Media_Library_Plugin|Media Library]] and [[Portable_Plugin|Portables]].

If you're looking to write a plugin, you may want to start by reading through the [[SDK_Contents]] and trying to find a code example that's similar to what you want to do.

----

== Troubleshooting ==
* '''I get an error message that looks like:'''

<pre>
1>gen_myplugin.obj : error LNK2028: unresolved token (0A00001D) "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)

1>gen_myplugin.obj : error LNK2019: unresolved external symbol "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)
</pre>

:'''Answer:''' By default Visual Studio Express 2008 doesn't include some files you need in the linker. For example, with our basic code we include windows.h, which is part of user32.dll. However, there is usually a '$(NoInherit)' command in our linker options that tell us not to include user32.dll. To fix this, try the following:

# Right-click on your project and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)'.
# Save and recompile

For more information see [http://stackoverflow.com/questions/739952/c-cli-linker-gives-unresolved-token-for-win32-function here] and [http://stackoverflow.com/questions/721387/i-get-lnk2028-when-trying-to-wrap-native-c-class-using-managed-c here].

* '''* I get an error like'''
<pre>
"1>.\gen_myplugin.cpp(25) : error C2146: syntax error : missing ';' before identifier 'plugin'"
</pre>

:'''Answer:''' This could be a namespace error. On this line

<source lang="cpp">
winampGeneralPurposePlugin plugin = {
</source>

we are creating a variable called 'plugin'. The variable's type, rather than being an integer ('int'), floating point number ('float'), or some other type, is of type 'winampGeneralPurposePlugin', which is a type we have created. This type is created in the header file with the code

<source lang="cpp">
typedef struct {
int version;
char *description;
int (*init)();
void (*config)();
void (*quit)();
HWND hwndParent;
HINSTANCE hDllInstance;
} winampGeneralPurposePlugin;
</source>

If you used Visual Studio's auto-generated code, you might have a line that looks like this:

<source lang="cpp">
namespace myplugin {
</source>

this line is telling Visual Studio to put everything inside the 'myplugin' namespace (read up on namespaces [http://en.wikipedia.org/wiki/Namespace here]). We get rid of the default boilerplate code, including the namespace, to make everything work.

Alternatively, you can change the declaration of the 'plugin' variable to say

<source lang="cpp">
myplugin::winampGeneralPurposePlugin plugin = {
</source>

This tells Visual Studio where to look for the winampGeneralPurposePlugin type (i.e., to look inside the 'myplugin' namespace). If you are new to programming or plugin creation, however, you probably don't need (or want) to mess with namespaces.

* '''I get an error like'''

<pre>
1>.\gen_myplugin.cpp(42) : error C2664: 'MessageBox' : cannot convert parameter 2 from 'const char [5]' to 'LPCTSTR'
1> Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or function-style cast
</pre>

:'''Answer:''' You need to change the string you pass to the MessageBox function to be of the right type. See the MSDN FAQ entry [http://social.msdn.microsoft.com/Forums/en-US/vclanguage/thread/c1b08c0a-a803-41c3-ac8c-84eba3be1ddb here]. You can most likely fix this by putting a capital 'L' in front of the string.

e.g. change <source lang="cpp">MessageBox(plugin.hwndParent, "Somestring", "", MB_OK);</source> to <source lang="cpp">MessageBox(plugin.hwndParent, L"Somestring", L"", MB_OK);</source>

TODO: What's the right way of doing this for plugins?
<pre> The answer here is to leave the Visual Studio option alone (set to use UNICODE)
and use the 'L' on the front of the strings. While you will find some parts of
Winamp still use ANSI strings, it is still meant to be an International application
and that means UNICODE.</pre>

* '''My plugin isn't working / My plugin doesn't show up in the Preferences menu.'''

:'''Answer:'''Did you name your plugin with the correct prefix, such as 'gen_myplugin'? If not it may not show up in the window.

TODO: How about other names/plugins? What's the real answer?
<pre> There are two commonly used methods to create plugins. The first is what is known as
Winamp 2, which we will get into shortly. Winamp 2 requires that plugins be prepended
with an identifier to their purpose, i.e., in_, out_, gen_, ml_, etc.

The second method is known as Wasabi, which is actually a framework used to share
information between application components. Wasabi files do not need a prefix.
</pre>
[[Category:Articles]]

Talk:Beginner's Basic Plugin Guide

2009-07-02T18:10:41Z

SMonty: /* Questions and TODO */

Talk:Beginner's Basic Plugin Guide

2009-07-02T17:51:54Z

SMonty: /* Questions and TODO */

Talk:Beginner's Basic Plugin Guide

2009-07-02T17:51:08Z

SMonty: /* Questions and TODO */

Talk:Beginner's Basic Plugin Guide

2009-07-02T17:35:06Z

SMonty: /* Questions and TODO */

Beginner's Basic Plugin Guide

2009-07-02T16:58:09Z

SMonty: /* Troubleshooting */

So you want to write a plugin for Winamp but don't know where to start? This is the page for you. We'll walk you through creating a very basic plugin that does '''nothing'''. You can then expand on the code to do whatever you want.

==Notes==
This guide assumes you're developing using Visual Studio in a Windows environment. It also assumes you have some familiarity with programming. For people that don't, try using google. We'll have to expand this guide in the future to give out more pointers.

== Basic credits ==
The following code has been created based on samples from [http://forums.winamp.com/showthread.php?s=&threadid=128915 several] [http://forums.winamp.com/showthread.php?s=&threadid=82651 forum] [http://forums.winamp.com/showthread.php?s=&threadid=103667 threads]. Many thanks go out to forum members Kaboon, kichik, baafie, burek021, and bananskib for their code examples and advice.

== What you need ==
To begin, you'll need a tool that lets you write code. Check out the [[Plug-in_Developer#Tools|Tools]] page. You can get a free copy of Visual Studio C++ Express [http://www.microsoft.com/Express/ here]. You'll probably also want a copy of Winamp itself, to test your plugin; you can get that on the Winamp site [http://www.winamp.com/player here].

# Download [http://www.microsoft.com/Express/ Visual C++ Express].
# Double-click the file (it's probably called something like 'vcsetup.exe') and run the installer.
# You're practically good to go!

== Creating a project ==
The first thing we need to do is create a place to store our code. In Visual Studio this is called a 'project'.

# Launch Visual Studio by clicking Start -> Programs -> Microsoft Visual C++ Express Edition -> Microsoft Visual C++ Express Edition
# When Visual Studio opens, select File -> New -> Project
# For creating Winamp plugins, we want to create code that compiles into a .dll, which Visual Studio 2008 refers to as a "Class Library". So in the 'New Project' window select Visual C++ -> CLR -> Class Library.
# Give your project a name (see below) and select a location.

'''Note:''' Winamp classifies plugins based on the first part of their .dll filename, so you will need to properly name the file if you want Winamp to recognize it (details: the Winamp client searches for and loads plugins based on the first part of their filenames. This saves time and space instead of loading all dlls and then detecting which ones are real plugins). Thus, to make our basic plugin we want to name the first part of the file 'gen_'. '''Be sure to start your plugin name with 'gen_' to make it work properly.'''

All of the examples in this guide will assume you named your plugin 'gen_myplugin', but you can call it whatever you like as long as it starts with 'gen_' (for generic plugin) and ends with '.dll'.

Once you click okay Visual Studio should create a bunch of boilerplate code for you, and throw some files in your project with names like "resource.h", "stdafx.h", "AssemblyInfo.cpp", and so on. The main files we want to work with are called 'gen_myplugin.h' and 'gen_myplugin.cpp'. If you double-click to view them you should see code that looks something like this:

<nowiki><contents of gen_myplugin.h></nowiki>
<source lang="cpp">
// gen_myplugin.h

#pragma once

using namespace System;

namespace gen_myplugin {

public ref class Class1
{
// TODO: Add your methods for this class here.
};
}
</source>
<nowiki><end contents of gen_myplugin.h></nowiki>

<nowiki><contents of gen_myplugin.cpp></nowiki>
<source lang="cpp">
// This is the main DLL file.

#include "stdafx.h"

#include "gen_myplugin.h"

</source>
<nowiki><end contents of gen_myplugin.cpp></nowiki>

We want to edit these files to make a basic plugin.

== Creating a basic plugin ==

=== Basic plugin code ===
To create your plugin, just copy/paste the following code into gen_myplugin.h and gen_myplugin.cpp.

<nowiki><basic gen_myplugin.h></nowiki>
<source lang="cpp">

#ifndef gen_myplugin_h
//---------------------------------------------------------------------------
#define gen_myplugin_h
#include <windows.h>

// plugin version (don't touch this)
#define GPPHDR_VER 0x10

// plugin name/title (change this to something you like)
#define PLUGIN_NAME "My first generic Winamp plugin!"

// main structure with plugin information, version, name...
typedef struct {
int version; // version of the plugin structure
char *description; // name/title of the plugin
int (*init)(); // function which will be executed on init event
void (*config)(); // function which will be executed on config event
void (*quit)(); // function which will be executed on quit event
HWND hwndParent; // hwnd of the Winamp client main window (stored by Winamp when dll is loaded)
HINSTANCE hDllInstance; // hinstance of this plugin DLL. (stored by Winamp when dll is loaded)
} winampGeneralPurposePlugin;

#endif
</source>
<nowiki><end basic gen_myplugin.h></nowiki>

<nowiki><basic gen_myplugin.cpp></nowiki>
<source lang="cpp">
/*

Winamp generic plugin template code.
This code should be just the basics needed to get a plugin up and running.
You can then expand the code to build your own plugin.

Updated details compiled June 2009 by culix, based on the excellent code examples
and advice of forum members Kaboon, kichik, baafie, burek021, and bananskib.
Thanks for the help everyone!

*/

#include "stdafx.h"
#include <windows.h>
#include "gen_myplugin.h"

// these are callback functions/events which will be called by Winamp
int init(void);
void config(void);
void quit(void);

// this structure contains plugin information, version, name...
// GPPHDR_VER is the version of the winampGeneralPurposePlugin (GPP) structure
winampGeneralPurposePlugin plugin = {
GPPHDR_VER, // version of the plugin, defined in "gen_myplugin.h"
PLUGIN_NAME, // name/title of the plugin, defined in "gen_myplugin.h"
init, // function name which will be executed on init event
config, // function name which will be executed on config event
quit, // function name which will be executed on quit event
0, // handle to Winamp main window, loaded by winamp when this dll is loaded
0 // hinstance to this dll, loaded by winamp when this dll is loaded
};

// event functions follow

int init() {
//A basic messagebox that tells you the 'init' event has been triggered.
//If everything works you should see this message when you start Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Init event triggered for gen_myplugin. Plugin installed successfully!", L"", MB_OK);
return 0;
}

void config() {
//A basic messagebox that tells you the 'config' event has been triggered.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Config event triggered for gen_myplugin.", L"", MB_OK);
}

void quit() {
//A basic messagebox that tells you the 'quit' event has been triggered.
//If everything works you should see this message when you quit Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(0, L"Quit event triggered for gen_myplugin.", L"", MB_OK);
}

// This is an export function called by winamp which returns this plugin info.
// We wrap the code in 'extern "C"' to ensure the export isn't mangled if used in a CPP file.
extern "C" __declspec(dllexport) winampGeneralPurposePlugin * winampGetGeneralPurposePlugin() {
return &plugin;
}
</source>
<nowiki><end basic gen_myplugin.cpp></nowiki>

=== winampGeneralPurposePlugin===
You might be wondering why the last two fields in the winampGeneralPurposePlugin structure are left empty. You might have noticed the reference that is returned as part of the winampGetGeneralPurposePlugin() method. This is the method that the Winamp.exe calls when loading these gen_*.dll files. As part of loading the plugin, the Winamp.exe will store the handle to its main window and the hinstance for the plugin dll into these two fields. Since these are references, these values become available for use by the plugin.
=== Edit dependencies ===

By default Visual Studio removes some files we need to compile our code. Let's add those back in:

# Right-click on your project (the folder called 'gen_myplugin' in the Solution Explorer window on the left) and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)', so the box is blank.
# Click 'Apply', then 'OK', and then save your project.

=== Compiling the code ===

Once you have pasted this code into your .h and .cpp files, save your changes and compile the project. You can do this by pressing F7, or selecting Build -> Build Solution. If everything works, you should see some messages in Visual Studio's 'Output' window, with the final line saying something like

"========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped =========="

If so, congratulations! You have built your first plugin :) If instead you get an error message, please see the [[Beginner's Basic Plugin Guide#Troubleshooting|Troubleshooting]] section below.

=== Testing the plugin ===

If your project builds successfully, it will output a file called 'gen_myplugin.dll' into a 'Debug' or 'Release' folder in the same location you created your project. Look for that file now. We want to copy this file to C:\Program Files\Winamp\Plugins\, which is the folder Winamp examines to find all of its plugins.

# Copy your plugin .dll file into C:\Program Files\Winamp\Plugins\
# Close and re-open Winamp. If your plugin is installed correctly, you should see a popup window with the Init message you typed inside gen_myplugin.cpp. If so, congrats! Your plugin works.
# You can check to see your plugin name by clicking Options -> Preferences -> Plugins -> General purpose. Your plugin name should appear in that window.
# Click on your plugin to hilight it and then select the 'Configure Selected Plugin' button. This should cause the 'config' message to appear.
# If you exit Winamp, you should now see the Quit message pop up as the program exits.

== What's next? ==

So what's next? We don't know. More guides still need to be written. Eventually there may be a guide for each type of plugin: [[Input_Plugin|Input]], [[Output_Plugin|Output]], [[Visualization_Plugin|Visualization]], [[DSP_Plugin|Audio Effect/DSP]], [[General_Purpose_Plugin|General Purpose]], [[Media_Library_Plugin|Media Library]] and [[Portable_Plugin|Portables]].

If you're looking to write a plugin, you may want to start by reading through the [[SDK_Contents]] and trying to find a code example that's similar to what you want to do.

----

== Troubleshooting ==
* '''I get an error message that looks like:'''

<pre>
1>gen_myplugin.obj : error LNK2028: unresolved token (0A00001D) "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)

1>gen_myplugin.obj : error LNK2019: unresolved external symbol "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)
</pre>

:'''Answer:''' By default Visual Studio Express 2008 doesn't include some files you need in the linker. For example, with our basic code we include windows.h, which is part of user32.dll. However, there is usually a '$(NoInherit)' command in our linker options that tell us not to include user32.dll. To fix this, try the following:

# Right-click on your project and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)'.
# Save and recompile

For more information see [http://stackoverflow.com/questions/739952/c-cli-linker-gives-unresolved-token-for-win32-function here] and [http://stackoverflow.com/questions/721387/i-get-lnk2028-when-trying-to-wrap-native-c-class-using-managed-c here].

* '''* I get an error like'''
<pre>
"1>.\gen_myplugin.cpp(25) : error C2146: syntax error : missing ';' before identifier 'plugin'"
</pre>

:'''Answer:''' This could be a namespace error. On this line

<source lang="cpp">
winampGeneralPurposePlugin plugin = {
</source>

we are creating a variable called 'plugin'. The variable's type, rather than being an integer ('int'), floating point number ('float'), or some other type, is of type 'winampGeneralPurposePlugin', which is a type we have created. This type is created in the header file with the code

<source lang="cpp">
typedef struct {
int version;
char *description;
int (*init)();
void (*config)();
void (*quit)();
HWND hwndParent;
HINSTANCE hDllInstance;
} winampGeneralPurposePlugin;
</source>

If you used Visual Studio's auto-generated code, you might have a line that looks like this:

<source lang="cpp">
namespace myplugin {
</source>

this line is telling Visual Studio to put everything inside the 'myplugin' namespace (read up on namespaces [http://en.wikipedia.org/wiki/Namespace here]). We get rid of the default boilerplate code, including the namespace, to make everything work.

Alternatively, you can change the declaration of the 'plugin' variable to say

<source lang="cpp">
myplugin::winampGeneralPurposePlugin plugin = {
</source>

This tells Visual Studio where to look for the winampGeneralPurposePlugin type (i.e., to look inside the 'myplugin' namespace). If you are new to programming or plugin creation, however, you probably don't need (or want) to mess with namespaces.

* '''I get an error like'''

<pre>
1>.\gen_myplugin.cpp(42) : error C2664: 'MessageBox' : cannot convert parameter 2 from 'const char [5]' to 'LPCTSTR'
1> Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or function-style cast
</pre>

:'''Answer:''' You need to change the string you pass to the MessageBox function to be of the right type. See the MSDN FAQ entry [http://social.msdn.microsoft.com/Forums/en-US/vclanguage/thread/c1b08c0a-a803-41c3-ac8c-84eba3be1ddb here]. You can most likely fix this by putting a capital 'L' in front of the string.

e.g. change <source lang="cpp">MessageBox(plugin.hwndParent, "Somestring", "", MB_OK);</source> to <source lang="cpp">MessageBox(plugin.hwndParent, L"Somestring", L"", MB_OK);</source>

TODO: What's the right way of doing this for plugins?

* '''My plugin isn't working / My plugin doesn't show up in the Preferences menu.'''

:'''Answer:'''Did you name your plugin with the correct prefix, such as 'gen_myplugin'? If not it may not show up in the window.

TODO: How about other names/plugins? What's the real answer?

[[Category:Articles]]

Beginner's Basic Plugin Guide

2009-07-01T21:33:09Z

SMonty: /* Troubleshooting */

So you want to write a plugin for Winamp but don't know where to start? This is the page for you. We'll walk you through creating a very basic plugin that does '''nothing'''. You can then expand on the code to do whatever you want.

==Notes==
This guide assumes you're developing using Visual Studio in a Windows environment. It also assumes you have some familiarity with programming. For people that don't, try using google. We'll have to expand this guide in the future to give out more pointers.

== Basic credits ==
The following code has been created based on samples from [http://forums.winamp.com/showthread.php?s=&threadid=128915 several] [http://forums.winamp.com/showthread.php?s=&threadid=82651 forum] [http://forums.winamp.com/showthread.php?s=&threadid=103667 threads]. Many thanks go out to forum members Kaboon, kichik, baafie, burek021, and bananskib for their code examples and advice.

== What you need ==
To begin, you'll need a tool that lets you write code. Check out the [[Plug-in_Developer#Tools|Tools]] page. You can get a free copy of Visual Studio C++ Express [http://www.microsoft.com/Express/ here]. You'll probably also want a copy of Winamp itself, to test your plugin; you can get that on the Winamp site [http://www.winamp.com/player here].

# Download [http://www.microsoft.com/Express/ Visual C++ Express].
# Double-click the file (it's probably called something like 'vcsetup.exe') and run the installer.
# You're practically good to go!

== Creating a project ==
The first thing we need to do is create a place to store our code. In Visual Studio this is called a 'project'.

# Launch Visual Studio by clicking Start -> Programs -> Microsoft Visual C++ Express Edition -> Microsoft Visual C++ Express Edition
# When Visual Studio opens, select File -> New -> Project
# For creating Winamp plugins, we want to create code that compiles into a .dll, which Visual Studio 2008 refers to as a "Class Library". So in the 'New Project' window select Visual C++ -> CLR -> Class Library.
# Give your project a name (see below) and select a location.

'''Note:''' Winamp classifies plugins based on the first part of their .dll filename, so you will need to properly name the file if you want Winamp to recognize it (details: the Winamp client searches for and loads plugins based on the first part of their filenames. This saves time and space instead of loading all dlls and then detecting which ones are real plugins). Thus, to make our basic plugin we want to name the first part of the file 'gen_'. '''Be sure to start your plugin name with 'gen_' to make it work properly.'''

All of the examples in this guide will assume you named your plugin 'gen_myplugin', but you can call it whatever you like as long as it starts with 'gen_' (for generic plugin) and ends with '.dll'.

Once you click okay Visual Studio should create a bunch of boilerplate code for you, and throw some files in your project with names like "resource.h", "stdafx.h", "AssemblyInfo.cpp", and so on. The main files we want to work with are called 'gen_myplugin.h' and 'gen_myplugin.cpp'. If you double-click to view them you should see code that looks something like this:

<nowiki><contents of gen_myplugin.h></nowiki>
<source lang="cpp">
// gen_myplugin.h

#pragma once

using namespace System;

namespace gen_myplugin {

public ref class Class1
{
// TODO: Add your methods for this class here.
};
}
</source>
<nowiki><end contents of gen_myplugin.h></nowiki>

<nowiki><contents of gen_myplugin.cpp></nowiki>
<source lang="cpp">
// This is the main DLL file.

#include "stdafx.h"

#include "gen_myplugin.h"

</source>
<nowiki><end contents of gen_myplugin.cpp></nowiki>

We want to edit these files to make a basic plugin.

== Creating a basic plugin ==

=== Basic plugin code ===
To create your plugin, just copy/paste the following code into gen_myplugin.h and gen_myplugin.cpp.

<nowiki><basic gen_myplugin.h></nowiki>
<source lang="cpp">

#ifndef gen_myplugin_h
//---------------------------------------------------------------------------
#define gen_myplugin_h
#include <windows.h>

// plugin version (don't touch this)
#define GPPHDR_VER 0x10

// plugin name/title (change this to something you like)
#define PLUGIN_NAME "My first generic Winamp plugin!"

// main structure with plugin information, version, name...
typedef struct {
int version; // version of the plugin structure
char *description; // name/title of the plugin
int (*init)(); // function which will be executed on init event
void (*config)(); // function which will be executed on config event
void (*quit)(); // function which will be executed on quit event
HWND hwndParent; // hwnd of the Winamp client main window (stored by Winamp when dll is loaded)
HINSTANCE hDllInstance; // hinstance of this plugin DLL. (stored by Winamp when dll is loaded)
} winampGeneralPurposePlugin;

#endif
</source>
<nowiki><end basic gen_myplugin.h></nowiki>

<nowiki><basic gen_myplugin.cpp></nowiki>
<source lang="cpp">
/*

Winamp generic plugin template code.
This code should be just the basics needed to get a plugin up and running.
You can then expand the code to build your own plugin.

Updated details compiled June 2009 by culix, based on the excellent code examples
and advice of forum members Kaboon, kichik, baafie, burek021, and bananskib.
Thanks for the help everyone!

*/

#include "stdafx.h"
#include <windows.h>
#include "gen_myplugin.h"

// these are callback functions/events which will be called by Winamp
int init(void);
void config(void);
void quit(void);

// this structure contains plugin information, version, name...
// GPPHDR_VER is the version of the winampGeneralPurposePlugin (GPP) structure
winampGeneralPurposePlugin plugin = {
GPPHDR_VER, // version of the plugin, defined in "gen_myplugin.h"
PLUGIN_NAME, // name/title of the plugin, defined in "gen_myplugin.h"
init, // function name which will be executed on init event
config, // function name which will be executed on config event
quit, // function name which will be executed on quit event
0, // handle to Winamp main window, loaded by winamp when this dll is loaded
0 // hinstance to this dll, loaded by winamp when this dll is loaded
};

// event functions follow

int init() {
//A basic messagebox that tells you the 'init' event has been triggered.
//If everything works you should see this message when you start Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Init event triggered for gen_myplugin. Plugin installed successfully!", L"", MB_OK);
return 0;
}

void config() {
//A basic messagebox that tells you the 'config' event has been triggered.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Config event triggered for gen_myplugin.", L"", MB_OK);
}

void quit() {
//A basic messagebox that tells you the 'quit' event has been triggered.
//If everything works you should see this message when you quit Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(0, L"Quit event triggered for gen_myplugin.", L"", MB_OK);
}

// This is an export function called by winamp which returns this plugin info.
// We wrap the code in 'extern "C"' to ensure the export isn't mangled if used in a CPP file.
extern "C" __declspec(dllexport) winampGeneralPurposePlugin * winampGetGeneralPurposePlugin() {
return &plugin;
}
</source>
<nowiki><end basic gen_myplugin.cpp></nowiki>

=== winampGeneralPurposePlugin===
You might be wondering why the last two fields in the winampGeneralPurposePlugin structure are left empty. You might have noticed the reference that is returned as part of the winampGetGeneralPurposePlugin() method. This is the method that the Winamp.exe calls when loading these gen_*.dll files. As part of loading the plugin, the Winamp.exe will store the handle to its main window and the hinstance for the plugin dll into these two fields. Since these are references, these values become available for use by the plugin.
=== Edit dependencies ===

By default Visual Studio removes some files we need to compile our code. Let's add those back in:

# Right-click on your project (the folder called 'gen_myplugin' in the Solution Explorer window on the left) and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)', so the box is blank.
# Click 'Apply', then 'OK', and then save your project.

=== Compiling the code ===

Once you have pasted this code into your .h and .cpp files, save your changes and compile the project. You can do this by pressing F7, or selecting Build -> Build Solution. If everything works, you should see some messages in Visual Studio's 'Output' window, with the final line saying something like

"========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped =========="

If so, congratulations! You have built your first plugin :) If instead you get an error message, please see the [[Beginner's Basic Plugin Guide#Troubleshooting|Troubleshooting]] section below.

=== Testing the plugin ===

If your project builds successfully, it will output a file called 'gen_myplugin.dll' into a 'Debug' or 'Release' folder in the same location you created your project. Look for that file now. We want to copy this file to C:\Program Files\Winamp\Plugins\, which is the folder Winamp examines to find all of its plugins.

# Copy your plugin .dll file into C:\Program Files\Winamp\Plugins\
# Close and re-open Winamp. If your plugin is installed correctly, you should see a popup window with the Init message you typed inside gen_myplugin.cpp. If so, congrats! Your plugin works.
# You can check to see your plugin name by clicking Options -> Preferences -> Plugins -> General purpose. Your plugin name should appear in that window.
# Click on your plugin to hilight it and then select the 'Configure Selected Plugin' button. This should cause the 'config' message to appear.
# If you exit Winamp, you should now see the Quit message pop up as the program exits.

== What's next? ==

So what's next? We don't know. More guides still need to be written. Eventually there may be a guide for each type of plugin: [[Input_Plugin|Input]], [[Output_Plugin|Output]], [[Visualization_Plugin|Visualization]], [[DSP_Plugin|Audio Effect/DSP]], [[General_Purpose_Plugin|General Purpose]], [[Media_Library_Plugin|Media Library]] and [[Portable_Plugin|Portables]].

If you're looking to write a plugin, you may want to start by reading through the [[SDK_Contents]] and trying to find a code example that's similar to what you want to do.

----

== Troubleshooting ==
* '''I get an error message that looks like:'''

<pre>
1>gen_myplugin.obj : error LNK2028: unresolved token (0A00001D) "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)

1>gen_myplugin.obj : error LNK2019: unresolved external symbol "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)
</pre>

:'''Answer:''' By default Visual Studio Express 2008 doesn't include some files you need in the linker. For example, with our basic code we include windows.h, which is part of user32.dll. However, there is usually a '$(NoInherit)' command in our linker options that tell us not to include user32.dll. To fix this, try the following:

# Right-click on your project and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)'.
# Save and recompile

For more information see [http://stackoverflow.com/questions/739952/c-cli-linker-gives-unresolved-token-for-win32-function here] and [http://stackoverflow.com/questions/721387/i-get-lnk2028-when-trying-to-wrap-native-c-class-using-managed-c here].

* '''* I get an error like'''
<pre>
"1>.\gen_myplugin.cpp(25) : error C2146: syntax error : missing ';' before identifier 'plugin'"
</pre>

:'''Answer:''' This could be a namespace error. On this line

<source lang="cpp">
winampGeneralPurposePlugin plugin = {
</source>

we are creating a variable called 'plugin'. The variable's type, rather than being an integer ('int'), floating point number ('float'), or some other type, is of type 'winampGeneralPurposePlugin', which is a type we have created. This type is created in the header file with the code

<source lang="cpp">
typedef struct {
int version;
char *description;
int (*init)();
void (*config)();
void (*quit)();
HWND hwndParent;
HINSTANCE hDllInstance;
} winampGeneralPurposePlugin;
</source>

If you used Visual Studio's auto-generated code, you might have a line that looks like this:

<source lang="cpp">
namespace myplugin {
</source>

this line is telling Visual Studio to put everything inside the 'myplugin' namespace (read up on namespaces [http://en.wikipedia.org/wiki/Namespace here]). We get rid of the default boilerplate code, including the namespace, to make everything work.

Alternatively, you can change the declaration of the 'plugin' variable to say

<source lang="cpp">
myplugin::winampGeneralPurposePlugin plugin = {
</source>

This tells Visual Studio where to look for the winampGeneralPurposePlugin type (i.e., to look inside the 'myplugin' namespace). If you are new to programming or plugin creation, however, you probably don't need (or want) to mess with namespaces.

* '''I get an error like'''

<pre>
1>.\gen_myplugin.cpp(42) : error C2664: 'MessageBox' : cannot convert parameter 2 from 'const char [5]' to 'LPCTSTR'
1> Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or function-style cast
</pre>

:'''Answer:''' You need to change the string you pass to the MessageBox function to be of the right type. See the MSDN FAQ entry [http://social.msdn.microsoft.com/Forums/en-US/vclanguage/thread/c1b08c0a-a803-41c3-ac8c-84eba3be1ddb here]. You can most likely fix this by putting a capital 'L' in front of the string.

e.g. change <source lang="cpp">MessageBox(plugin.hwndParent, "Somestring", "", MB_OK);</source> to <source lang="cpp">MessageBox(plugin.hwndParent, L"Somestring", L"", MB_OK);</source>

TODO: What's the right way of doing this for plugins?

* '''My plugin isn't working / My plugin doesn't show up in the Preferences menu.'''

:'''Answer:'''Did you name your plugin with the correct prefix, such as 'gen_myplugin'? If not it may not show up in the window.

TODO: How about other names/plugins? What's the real answer?

The answer to this is complicated, as so much with Winamp. The prefix is actually used by Winamp.exe to find plugins and identify what type they are. There is another way to create plugins that does not require the prefix. This second way is called Wasabi. Wasabi is a way to 'share' code among components of a software system (i.e., Winamp). Wasabi dlls do not need the prefix. We'll get to Wasabi if we keep writing these kinds of tutorials. Is there something specific about the prefixes that leads you to believe that there is a 'real' answer? Maybe I can investigate further.

[[Category:Articles]]

Beginner's Basic Plugin Guide

2009-07-01T21:14:29Z

SMonty: /* Edit dependencies */

So you want to write a plugin for Winamp but don't know where to start? This is the page for you. We'll walk you through creating a very basic plugin that does '''nothing'''. You can then expand on the code to do whatever you want.

==Notes==
This guide assumes you're developing using Visual Studio in a Windows environment. It also assumes you have some familiarity with programming. For people that don't, try using google. We'll have to expand this guide in the future to give out more pointers.

== Basic credits ==
The following code has been created based on samples from [http://forums.winamp.com/showthread.php?s=&threadid=128915 several] [http://forums.winamp.com/showthread.php?s=&threadid=82651 forum] [http://forums.winamp.com/showthread.php?s=&threadid=103667 threads]. Many thanks go out to forum members Kaboon, kichik, baafie, burek021, and bananskib for their code examples and advice.

== What you need ==
To begin, you'll need a tool that lets you write code. Check out the [[Plug-in_Developer#Tools|Tools]] page. You can get a free copy of Visual Studio C++ Express [http://www.microsoft.com/Express/ here]. You'll probably also want a copy of Winamp itself, to test your plugin; you can get that on the Winamp site [http://www.winamp.com/player here].

# Download [http://www.microsoft.com/Express/ Visual C++ Express].
# Double-click the file (it's probably called something like 'vcsetup.exe') and run the installer.
# You're practically good to go!

== Creating a project ==
The first thing we need to do is create a place to store our code. In Visual Studio this is called a 'project'.

# Launch Visual Studio by clicking Start -> Programs -> Microsoft Visual C++ Express Edition -> Microsoft Visual C++ Express Edition
# When Visual Studio opens, select File -> New -> Project
# For creating Winamp plugins, we want to create code that compiles into a .dll, which Visual Studio 2008 refers to as a "Class Library". So in the 'New Project' window select Visual C++ -> CLR -> Class Library.
# Give your project a name (see below) and select a location.

'''Note:''' Winamp classifies plugins based on the first part of their .dll filename, so you will need to properly name the file if you want Winamp to recognize it (details: the Winamp client searches for and loads plugins based on the first part of their filenames. This saves time and space instead of loading all dlls and then detecting which ones are real plugins). Thus, to make our basic plugin we want to name the first part of the file 'gen_'. '''Be sure to start your plugin name with 'gen_' to make it work properly.'''

All of the examples in this guide will assume you named your plugin 'gen_myplugin', but you can call it whatever you like as long as it starts with 'gen_' (for generic plugin) and ends with '.dll'.

Once you click okay Visual Studio should create a bunch of boilerplate code for you, and throw some files in your project with names like "resource.h", "stdafx.h", "AssemblyInfo.cpp", and so on. The main files we want to work with are called 'gen_myplugin.h' and 'gen_myplugin.cpp'. If you double-click to view them you should see code that looks something like this:

<nowiki><contents of gen_myplugin.h></nowiki>
<source lang="cpp">
// gen_myplugin.h

#pragma once

using namespace System;

namespace gen_myplugin {

public ref class Class1
{
// TODO: Add your methods for this class here.
};
}
</source>
<nowiki><end contents of gen_myplugin.h></nowiki>

<nowiki><contents of gen_myplugin.cpp></nowiki>
<source lang="cpp">
// This is the main DLL file.

#include "stdafx.h"

#include "gen_myplugin.h"

</source>
<nowiki><end contents of gen_myplugin.cpp></nowiki>

We want to edit these files to make a basic plugin.

== Creating a basic plugin ==

=== Basic plugin code ===
To create your plugin, just copy/paste the following code into gen_myplugin.h and gen_myplugin.cpp.

<nowiki><basic gen_myplugin.h></nowiki>
<source lang="cpp">

#ifndef gen_myplugin_h
//---------------------------------------------------------------------------
#define gen_myplugin_h
#include <windows.h>

// plugin version (don't touch this)
#define GPPHDR_VER 0x10

// plugin name/title (change this to something you like)
#define PLUGIN_NAME "My first generic Winamp plugin!"

// main structure with plugin information, version, name...
typedef struct {
int version; // version of the plugin structure
char *description; // name/title of the plugin
int (*init)(); // function which will be executed on init event
void (*config)(); // function which will be executed on config event
void (*quit)(); // function which will be executed on quit event
HWND hwndParent; // hwnd of the Winamp client main window (stored by Winamp when dll is loaded)
HINSTANCE hDllInstance; // hinstance of this plugin DLL. (stored by Winamp when dll is loaded)
} winampGeneralPurposePlugin;

#endif
</source>
<nowiki><end basic gen_myplugin.h></nowiki>

<nowiki><basic gen_myplugin.cpp></nowiki>
<source lang="cpp">
/*

Winamp generic plugin template code.
This code should be just the basics needed to get a plugin up and running.
You can then expand the code to build your own plugin.

Updated details compiled June 2009 by culix, based on the excellent code examples
and advice of forum members Kaboon, kichik, baafie, burek021, and bananskib.
Thanks for the help everyone!

*/

#include "stdafx.h"
#include <windows.h>
#include "gen_myplugin.h"

// these are callback functions/events which will be called by Winamp
int init(void);
void config(void);
void quit(void);

// this structure contains plugin information, version, name...
// GPPHDR_VER is the version of the winampGeneralPurposePlugin (GPP) structure
winampGeneralPurposePlugin plugin = {
GPPHDR_VER, // version of the plugin, defined in "gen_myplugin.h"
PLUGIN_NAME, // name/title of the plugin, defined in "gen_myplugin.h"
init, // function name which will be executed on init event
config, // function name which will be executed on config event
quit, // function name which will be executed on quit event
0, // handle to Winamp main window, loaded by winamp when this dll is loaded
0 // hinstance to this dll, loaded by winamp when this dll is loaded
};

// event functions follow

int init() {
//A basic messagebox that tells you the 'init' event has been triggered.
//If everything works you should see this message when you start Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Init event triggered for gen_myplugin. Plugin installed successfully!", L"", MB_OK);
return 0;
}

void config() {
//A basic messagebox that tells you the 'config' event has been triggered.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Config event triggered for gen_myplugin.", L"", MB_OK);
}

void quit() {
//A basic messagebox that tells you the 'quit' event has been triggered.
//If everything works you should see this message when you quit Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(0, L"Quit event triggered for gen_myplugin.", L"", MB_OK);
}

// This is an export function called by winamp which returns this plugin info.
// We wrap the code in 'extern "C"' to ensure the export isn't mangled if used in a CPP file.
extern "C" __declspec(dllexport) winampGeneralPurposePlugin * winampGetGeneralPurposePlugin() {
return &plugin;
}
</source>
<nowiki><end basic gen_myplugin.cpp></nowiki>

=== winampGeneralPurposePlugin===
You might be wondering why the last two fields in the winampGeneralPurposePlugin structure are left empty. You might have noticed the reference that is returned as part of the winampGetGeneralPurposePlugin() method. This is the method that the Winamp.exe calls when loading these gen_*.dll files. As part of loading the plugin, the Winamp.exe will store the handle to its main window and the hinstance for the plugin dll into these two fields. Since these are references, these values become available for use by the plugin.
=== Edit dependencies ===

By default Visual Studio removes some files we need to compile our code. Let's add those back in:

# Right-click on your project (the folder called 'gen_myplugin' in the Solution Explorer window on the left) and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)', so the box is blank.
# Click 'Apply', then 'OK', and then save your project.

=== Compiling the code ===

Once you have pasted this code into your .h and .cpp files, save your changes and compile the project. You can do this by pressing F7, or selecting Build -> Build Solution. If everything works, you should see some messages in Visual Studio's 'Output' window, with the final line saying something like

"========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped =========="

If so, congratulations! You have built your first plugin :) If instead you get an error message, please see the [[Beginner's Basic Plugin Guide#Troubleshooting|Troubleshooting]] section below.

=== Testing the plugin ===

If your project builds successfully, it will output a file called 'gen_myplugin.dll' into a 'Debug' or 'Release' folder in the same location you created your project. Look for that file now. We want to copy this file to C:\Program Files\Winamp\Plugins\, which is the folder Winamp examines to find all of its plugins.

# Copy your plugin .dll file into C:\Program Files\Winamp\Plugins\
# Close and re-open Winamp. If your plugin is installed correctly, you should see a popup window with the Init message you typed inside gen_myplugin.cpp. If so, congrats! Your plugin works.
# You can check to see your plugin name by clicking Options -> Preferences -> Plugins -> General purpose. Your plugin name should appear in that window.
# Click on your plugin to hilight it and then select the 'Configure Selected Plugin' button. This should cause the 'config' message to appear.
# If you exit Winamp, you should now see the Quit message pop up as the program exits.

== What's next? ==

So what's next? We don't know. More guides still need to be written. Eventually there may be a guide for each type of plugin: [[Input_Plugin|Input]], [[Output_Plugin|Output]], [[Visualization_Plugin|Visualization]], [[DSP_Plugin|Audio Effect/DSP]], [[General_Purpose_Plugin|General Purpose]], [[Media_Library_Plugin|Media Library]] and [[Portable_Plugin|Portables]].

If you're looking to write a plugin, you may want to start by reading through the [[SDK_Contents]] and trying to find a code example that's similar to what you want to do.

----

== Troubleshooting ==
* '''I get an error message that looks like:'''

<pre>
1>winamp_imms.obj : error LNK2028: unresolved token (0A00001D) "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)

1>winamp_imms.obj : error LNK2019: unresolved external symbol "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)
</pre>

:'''Answer:''' By default Visual Studio Express 2008 doesn't include some files you need in the linker. For example, with our basic code we include windows.h, which is part of user32.dll. However, there is usually a '$(NoInherit)' command in our linker options that tell us not to include user32.dll. To fix this, try the following:

# Right-click on your project and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)'.
# Save and recompile

For more information see [http://stackoverflow.com/questions/739952/c-cli-linker-gives-unresolved-token-for-win32-function here] and [http://stackoverflow.com/questions/721387/i-get-lnk2028-when-trying-to-wrap-native-c-class-using-managed-c here].

* '''* I get an error like'''
<pre>
"1>.\winamp_imms.cpp(29) : error C2146: syntax error : missing ';' before identifier 'plugin'"
</pre>

:'''Answer:''' This could be a namespace error. On this line

<source lang="cpp">
winampGeneralPurposePlugin plugin = {
</source>

we are creating a variable called 'plugin'. The variable's type, rather than being an integer ('int'), floating point number ('float'), or some other type, is of type 'winampGeneralPurposePlugin', which is a type we have created. This type is created in the header file with the code

<source lang="cpp">
typedef struct {
int version;
char *description;
int (*init)();
void (*config)();
void (*quit)();
HWND hwndParent;
HINSTANCE hDllInstance;
} winampGeneralPurposePlugin;
</source>

If you used Visual Studio's auto-generated code, you might have a line that looks like this:

<source lang="cpp">
namespace myplugin {
</source>

this line is telling Visual Studio to put everything inside the 'myplugin' namespace (read up on namespaces [http://en.wikipedia.org/wiki/Namespace here]). We get rid of the default boilerplate code, including the namespace, to make everything work.

Alternatively, you can change the declaration of the 'plugin' variable to say

<source lang="cpp">
myplugin::winampGeneralPurposePlugin plugin = {
</source>

This tells Visual Studio where to look for the winampGeneralPurposePlugin type (i.e., to look inside the 'myplugin' namespace). If you are new to programming or plugin creation, however, you probably don't need (or want) to mess with namespaces.

* '''I get an error like'''

<pre>
1>.\winamp_imms.cpp(41) : error C2664: 'MessageBox' : cannot convert parameter 2 from 'const char [5]' to 'LPCTSTR'
1> Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or function-style cast
</pre>

:'''Answer:''' You need to change the string you pass to the MessageBox function to be of the right type. See the MSDN FAQ entry [http://social.msdn.microsoft.com/Forums/en-US/vclanguage/thread/c1b08c0a-a803-41c3-ac8c-84eba3be1ddb here]. You can most likely fix this by putting a capital 'L' in front of the string.

e.g. change <source lang="cpp">MessageBox(plugin.hwndParent, "Somestring", "", MB_OK);</source> to <source lang="cpp">MessageBox(plugin.hwndParent, L"Somestring", L"", MB_OK);</source>

TODO: What's the right way of doing this for plugins?

* '''My plugin isn't working / My plugin doesn't show up in the Preferences menu.'''

:'''Answer:'''Did you name your plugin with the correct prefix, such as 'gen_myplugin'? If not it may not show up in the window.

TODO: How about other names/plugins? What's the real answer?

[[Category:Articles]]

Beginner's Basic Plugin Guide

2009-07-01T21:08:23Z

SMonty: /* Basic plugin code */

So you want to write a plugin for Winamp but don't know where to start? This is the page for you. We'll walk you through creating a very basic plugin that does '''nothing'''. You can then expand on the code to do whatever you want.

==Notes==
This guide assumes you're developing using Visual Studio in a Windows environment. It also assumes you have some familiarity with programming. For people that don't, try using google. We'll have to expand this guide in the future to give out more pointers.

== Basic credits ==
The following code has been created based on samples from [http://forums.winamp.com/showthread.php?s=&threadid=128915 several] [http://forums.winamp.com/showthread.php?s=&threadid=82651 forum] [http://forums.winamp.com/showthread.php?s=&threadid=103667 threads]. Many thanks go out to forum members Kaboon, kichik, baafie, burek021, and bananskib for their code examples and advice.

== What you need ==
To begin, you'll need a tool that lets you write code. Check out the [[Plug-in_Developer#Tools|Tools]] page. You can get a free copy of Visual Studio C++ Express [http://www.microsoft.com/Express/ here]. You'll probably also want a copy of Winamp itself, to test your plugin; you can get that on the Winamp site [http://www.winamp.com/player here].

# Download [http://www.microsoft.com/Express/ Visual C++ Express].
# Double-click the file (it's probably called something like 'vcsetup.exe') and run the installer.
# You're practically good to go!

== Creating a project ==
The first thing we need to do is create a place to store our code. In Visual Studio this is called a 'project'.

# Launch Visual Studio by clicking Start -> Programs -> Microsoft Visual C++ Express Edition -> Microsoft Visual C++ Express Edition
# When Visual Studio opens, select File -> New -> Project
# For creating Winamp plugins, we want to create code that compiles into a .dll, which Visual Studio 2008 refers to as a "Class Library". So in the 'New Project' window select Visual C++ -> CLR -> Class Library.
# Give your project a name (see below) and select a location.

'''Note:''' Winamp classifies plugins based on the first part of their .dll filename, so you will need to properly name the file if you want Winamp to recognize it (details: the Winamp client searches for and loads plugins based on the first part of their filenames. This saves time and space instead of loading all dlls and then detecting which ones are real plugins). Thus, to make our basic plugin we want to name the first part of the file 'gen_'. '''Be sure to start your plugin name with 'gen_' to make it work properly.'''

All of the examples in this guide will assume you named your plugin 'gen_myplugin', but you can call it whatever you like as long as it starts with 'gen_' (for generic plugin) and ends with '.dll'.

Once you click okay Visual Studio should create a bunch of boilerplate code for you, and throw some files in your project with names like "resource.h", "stdafx.h", "AssemblyInfo.cpp", and so on. The main files we want to work with are called 'gen_myplugin.h' and 'gen_myplugin.cpp'. If you double-click to view them you should see code that looks something like this:

<nowiki><contents of gen_myplugin.h></nowiki>
<source lang="cpp">
// gen_myplugin.h

#pragma once

using namespace System;

namespace gen_myplugin {

public ref class Class1
{
// TODO: Add your methods for this class here.
};
}
</source>
<nowiki><end contents of gen_myplugin.h></nowiki>

<nowiki><contents of gen_myplugin.cpp></nowiki>
<source lang="cpp">
// This is the main DLL file.

#include "stdafx.h"

#include "gen_myplugin.h"

</source>
<nowiki><end contents of gen_myplugin.cpp></nowiki>

We want to edit these files to make a basic plugin.

== Creating a basic plugin ==

=== Basic plugin code ===
To create your plugin, just copy/paste the following code into gen_myplugin.h and gen_myplugin.cpp.

<nowiki><basic gen_myplugin.h></nowiki>
<source lang="cpp">

#ifndef gen_myplugin_h
//---------------------------------------------------------------------------
#define gen_myplugin_h
#include <windows.h>

// plugin version (don't touch this)
#define GPPHDR_VER 0x10

// plugin name/title (change this to something you like)
#define PLUGIN_NAME "My first generic Winamp plugin!"

// main structure with plugin information, version, name...
typedef struct {
int version; // version of the plugin structure
char *description; // name/title of the plugin
int (*init)(); // function which will be executed on init event
void (*config)(); // function which will be executed on config event
void (*quit)(); // function which will be executed on quit event
HWND hwndParent; // hwnd of the Winamp client main window (stored by Winamp when dll is loaded)
HINSTANCE hDllInstance; // hinstance of this plugin DLL. (stored by Winamp when dll is loaded)
} winampGeneralPurposePlugin;

#endif
</source>
<nowiki><end basic gen_myplugin.h></nowiki>

<nowiki><basic gen_myplugin.cpp></nowiki>
<source lang="cpp">
/*

Winamp generic plugin template code.
This code should be just the basics needed to get a plugin up and running.
You can then expand the code to build your own plugin.

Updated details compiled June 2009 by culix, based on the excellent code examples
and advice of forum members Kaboon, kichik, baafie, burek021, and bananskib.
Thanks for the help everyone!

*/

#include "stdafx.h"
#include <windows.h>
#include "gen_myplugin.h"

// these are callback functions/events which will be called by Winamp
int init(void);
void config(void);
void quit(void);

// this structure contains plugin information, version, name...
// GPPHDR_VER is the version of the winampGeneralPurposePlugin (GPP) structure
winampGeneralPurposePlugin plugin = {
GPPHDR_VER, // version of the plugin, defined in "gen_myplugin.h"
PLUGIN_NAME, // name/title of the plugin, defined in "gen_myplugin.h"
init, // function name which will be executed on init event
config, // function name which will be executed on config event
quit, // function name which will be executed on quit event
0, // handle to Winamp main window, loaded by winamp when this dll is loaded
0 // hinstance to this dll, loaded by winamp when this dll is loaded
};

// event functions follow

int init() {
//A basic messagebox that tells you the 'init' event has been triggered.
//If everything works you should see this message when you start Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Init event triggered for gen_myplugin. Plugin installed successfully!", L"", MB_OK);
return 0;
}

void config() {
//A basic messagebox that tells you the 'config' event has been triggered.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Config event triggered for gen_myplugin.", L"", MB_OK);
}

void quit() {
//A basic messagebox that tells you the 'quit' event has been triggered.
//If everything works you should see this message when you quit Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(0, L"Quit event triggered for gen_myplugin.", L"", MB_OK);
}

// This is an export function called by winamp which returns this plugin info.
// We wrap the code in 'extern "C"' to ensure the export isn't mangled if used in a CPP file.
extern "C" __declspec(dllexport) winampGeneralPurposePlugin * winampGetGeneralPurposePlugin() {
return &plugin;
}
</source>
<nowiki><end basic gen_myplugin.cpp></nowiki>

=== Edit dependencies ===

By default Visual Studio removes some files we need to compile our code. Let's add those back in:

# Right-click on your project (the folder called 'gen_myplugin' in the Solution Explorer window on the left) and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)', so the box is blank.
# Click 'Apply', then 'OK', and then save your project.

=== Compiling the code ===

Once you have pasted this code into your .h and .cpp files, save your changes and compile the project. You can do this by pressing F7, or selecting Build -> Build Solution. If everything works, you should see some messages in Visual Studio's 'Output' window, with the final line saying something like

"========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped =========="

If so, congratulations! You have built your first plugin :) If instead you get an error message, please see the [[Beginner's Basic Plugin Guide#Troubleshooting|Troubleshooting]] section below.

=== Testing the plugin ===

If your project builds successfully, it will output a file called 'gen_myplugin.dll' into a 'Debug' or 'Release' folder in the same location you created your project. Look for that file now. We want to copy this file to C:\Program Files\Winamp\Plugins\, which is the folder Winamp examines to find all of its plugins.

# Copy your plugin .dll file into C:\Program Files\Winamp\Plugins\
# Close and re-open Winamp. If your plugin is installed correctly, you should see a popup window with the Init message you typed inside gen_myplugin.cpp. If so, congrats! Your plugin works.
# You can check to see your plugin name by clicking Options -> Preferences -> Plugins -> General purpose. Your plugin name should appear in that window.
# Click on your plugin to hilight it and then select the 'Configure Selected Plugin' button. This should cause the 'config' message to appear.
# If you exit Winamp, you should now see the Quit message pop up as the program exits.

== What's next? ==

So what's next? We don't know. More guides still need to be written. Eventually there may be a guide for each type of plugin: [[Input_Plugin|Input]], [[Output_Plugin|Output]], [[Visualization_Plugin|Visualization]], [[DSP_Plugin|Audio Effect/DSP]], [[General_Purpose_Plugin|General Purpose]], [[Media_Library_Plugin|Media Library]] and [[Portable_Plugin|Portables]].

If you're looking to write a plugin, you may want to start by reading through the [[SDK_Contents]] and trying to find a code example that's similar to what you want to do.

----

== Troubleshooting ==
* '''I get an error message that looks like:'''

<pre>
1>winamp_imms.obj : error LNK2028: unresolved token (0A00001D) "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)

1>winamp_imms.obj : error LNK2019: unresolved external symbol "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)
</pre>

:'''Answer:''' By default Visual Studio Express 2008 doesn't include some files you need in the linker. For example, with our basic code we include windows.h, which is part of user32.dll. However, there is usually a '$(NoInherit)' command in our linker options that tell us not to include user32.dll. To fix this, try the following:

# Right-click on your project and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)'.
# Save and recompile

For more information see [http://stackoverflow.com/questions/739952/c-cli-linker-gives-unresolved-token-for-win32-function here] and [http://stackoverflow.com/questions/721387/i-get-lnk2028-when-trying-to-wrap-native-c-class-using-managed-c here].

* '''* I get an error like'''
<pre>
"1>.\winamp_imms.cpp(29) : error C2146: syntax error : missing ';' before identifier 'plugin'"
</pre>

:'''Answer:''' This could be a namespace error. On this line

<source lang="cpp">
winampGeneralPurposePlugin plugin = {
</source>

we are creating a variable called 'plugin'. The variable's type, rather than being an integer ('int'), floating point number ('float'), or some other type, is of type 'winampGeneralPurposePlugin', which is a type we have created. This type is created in the header file with the code

<source lang="cpp">
typedef struct {
int version;
char *description;
int (*init)();
void (*config)();
void (*quit)();
HWND hwndParent;
HINSTANCE hDllInstance;
} winampGeneralPurposePlugin;
</source>

If you used Visual Studio's auto-generated code, you might have a line that looks like this:

<source lang="cpp">
namespace myplugin {
</source>

this line is telling Visual Studio to put everything inside the 'myplugin' namespace (read up on namespaces [http://en.wikipedia.org/wiki/Namespace here]). We get rid of the default boilerplate code, including the namespace, to make everything work.

Alternatively, you can change the declaration of the 'plugin' variable to say

<source lang="cpp">
myplugin::winampGeneralPurposePlugin plugin = {
</source>

This tells Visual Studio where to look for the winampGeneralPurposePlugin type (i.e., to look inside the 'myplugin' namespace). If you are new to programming or plugin creation, however, you probably don't need (or want) to mess with namespaces.

* '''I get an error like'''

<pre>
1>.\winamp_imms.cpp(41) : error C2664: 'MessageBox' : cannot convert parameter 2 from 'const char [5]' to 'LPCTSTR'
1> Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or function-style cast
</pre>

:'''Answer:''' You need to change the string you pass to the MessageBox function to be of the right type. See the MSDN FAQ entry [http://social.msdn.microsoft.com/Forums/en-US/vclanguage/thread/c1b08c0a-a803-41c3-ac8c-84eba3be1ddb here]. You can most likely fix this by putting a capital 'L' in front of the string.

e.g. change <source lang="cpp">MessageBox(plugin.hwndParent, "Somestring", "", MB_OK);</source> to <source lang="cpp">MessageBox(plugin.hwndParent, L"Somestring", L"", MB_OK);</source>

TODO: What's the right way of doing this for plugins?

* '''My plugin isn't working / My plugin doesn't show up in the Preferences menu.'''

:'''Answer:'''Did you name your plugin with the correct prefix, such as 'gen_myplugin'? If not it may not show up in the window.

TODO: How about other names/plugins? What's the real answer?

[[Category:Articles]]

Beginner's Basic Plugin Guide

2009-07-01T21:05:42Z

SMonty: /* Basic plugin code */

So you want to write a plugin for Winamp but don't know where to start? This is the page for you. We'll walk you through creating a very basic plugin that does '''nothing'''. You can then expand on the code to do whatever you want.

==Notes==
This guide assumes you're developing using Visual Studio in a Windows environment. It also assumes you have some familiarity with programming. For people that don't, try using google. We'll have to expand this guide in the future to give out more pointers.

== Basic credits ==
The following code has been created based on samples from [http://forums.winamp.com/showthread.php?s=&threadid=128915 several] [http://forums.winamp.com/showthread.php?s=&threadid=82651 forum] [http://forums.winamp.com/showthread.php?s=&threadid=103667 threads]. Many thanks go out to forum members Kaboon, kichik, baafie, burek021, and bananskib for their code examples and advice.

== What you need ==
To begin, you'll need a tool that lets you write code. Check out the [[Plug-in_Developer#Tools|Tools]] page. You can get a free copy of Visual Studio C++ Express [http://www.microsoft.com/Express/ here]. You'll probably also want a copy of Winamp itself, to test your plugin; you can get that on the Winamp site [http://www.winamp.com/player here].

# Download [http://www.microsoft.com/Express/ Visual C++ Express].
# Double-click the file (it's probably called something like 'vcsetup.exe') and run the installer.
# You're practically good to go!

== Creating a project ==
The first thing we need to do is create a place to store our code. In Visual Studio this is called a 'project'.

# Launch Visual Studio by clicking Start -> Programs -> Microsoft Visual C++ Express Edition -> Microsoft Visual C++ Express Edition
# When Visual Studio opens, select File -> New -> Project
# For creating Winamp plugins, we want to create code that compiles into a .dll, which Visual Studio 2008 refers to as a "Class Library". So in the 'New Project' window select Visual C++ -> CLR -> Class Library.
# Give your project a name (see below) and select a location.

'''Note:''' Winamp classifies plugins based on the first part of their .dll filename, so you will need to properly name the file if you want Winamp to recognize it (details: the Winamp client searches for and loads plugins based on the first part of their filenames. This saves time and space instead of loading all dlls and then detecting which ones are real plugins). Thus, to make our basic plugin we want to name the first part of the file 'gen_'. '''Be sure to start your plugin name with 'gen_' to make it work properly.'''

All of the examples in this guide will assume you named your plugin 'gen_myplugin', but you can call it whatever you like as long as it starts with 'gen_' (for generic plugin) and ends with '.dll'.

Once you click okay Visual Studio should create a bunch of boilerplate code for you, and throw some files in your project with names like "resource.h", "stdafx.h", "AssemblyInfo.cpp", and so on. The main files we want to work with are called 'gen_myplugin.h' and 'gen_myplugin.cpp'. If you double-click to view them you should see code that looks something like this:

<nowiki><contents of gen_myplugin.h></nowiki>
<source lang="cpp">
// gen_myplugin.h

#pragma once

using namespace System;

namespace gen_myplugin {

public ref class Class1
{
// TODO: Add your methods for this class here.
};
}
</source>
<nowiki><end contents of gen_myplugin.h></nowiki>

<nowiki><contents of gen_myplugin.cpp></nowiki>
<source lang="cpp">
// This is the main DLL file.

#include "stdafx.h"

#include "gen_myplugin.h"

</source>
<nowiki><end contents of gen_myplugin.cpp></nowiki>

We want to edit these files to make a basic plugin.

== Creating a basic plugin ==

=== Basic plugin code ===
To create your plugin, just copy/paste the following code into gen_myplugin.h and gen_myplugin.cpp.

<nowiki><basic gen_myplugin.h></nowiki>
<source lang="cpp">

#ifndef gen_myplugin_h
//---------------------------------------------------------------------------
#define gen_myplugin_h
#include <windows.h>

// plugin version (don't touch this)
#define GPPHDR_VER 0x10

// plugin name/title (change this to something you like)
#define PLUGIN_NAME "My first generic Winamp plugin!"

// main structure with plugin information, version, name...
typedef struct {
int version; // version of the plugin structure
char *description; // name/title of the plugin
int (*init)(); // function which will be executed on init event
void (*config)(); // function which will be executed on config event
void (*quit)(); // function which will be executed on quit event
HWND hwndParent; // hwnd of the Winamp client main window (stored by Winamp when dll is loaded)
HINSTANCE hDllInstance; // hinstance of this plugin DLL. (stored by Winamp when dll is loaded)
} winampGeneralPurposePlugin;

#endif
</source>
<nowiki><end basic gen_myplugin.h></nowiki>

<nowiki><basic gen_myplugin.cpp></nowiki>
<source lang="cpp">
/*

Winamp generic plugin template code.
This code should be just the basics needed to get a plugin up and running.
You can then expand the code to build your own plugin.

Updated details compiled June 2009 by culix, based on the excellent code examples
and advice of forum members Kaboon, kichik, baafie, burek021, and bananskib.
Thanks for the help everyone!

*/

#include "stdafx.h"
#include <windows.h>
#include "gen_myplugin.h"

// these are callback functions/events which will be called by Winamp
int init(void);
void config(void);
void quit(void);

// this structure contains plugin information, version, name...
// GPPHDR_VER is the version of the winampGeneralPurposePlugin (GPP) structure
winampGeneralPurposePlugin plugin = {
GPPHDR_VER, // version of the plugin, defined in "gen_myplugin.h"
PLUGIN_NAME, // name/title of the plugin, defined in "gen_myplugin.h"
init, // function name which will be executed on init event
config, // function name which will be executed on config event
quit, // function name which will be executed on quit event
0,
0
};

// event functions follow

int init() {
//A basic messagebox that tells you the 'init' event has been triggered.
//If everything works you should see this message when you start Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Init event triggered for gen_myplugin. Plugin installed successfully!", L"", MB_OK);
return 0;
}

void config() {
//A basic messagebox that tells you the 'config' event has been triggered.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Config event triggered for gen_myplugin.", L"", MB_OK);
}

void quit() {
//A basic messagebox that tells you the 'quit' event has been triggered.
//If everything works you should see this message when you quit Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(0, L"Quit event triggered for gen_myplugin.", L"", MB_OK);
}

// This is an export function called by winamp which returns this plugin info.
// We wrap the code in 'extern "C"' to ensure the export isn't mangled if used in a CPP file.
extern "C" __declspec(dllexport) winampGeneralPurposePlugin * winampGetGeneralPurposePlugin() {
return &plugin;
}
</source>
<nowiki><end basic gen_myplugin.cpp></nowiki>

=== Edit dependencies ===

By default Visual Studio removes some files we need to compile our code. Let's add those back in:

# Right-click on your project (the folder called 'gen_myplugin' in the Solution Explorer window on the left) and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)', so the box is blank.
# Click 'Apply', then 'OK', and then save your project.

=== Compiling the code ===

Once you have pasted this code into your .h and .cpp files, save your changes and compile the project. You can do this by pressing F7, or selecting Build -> Build Solution. If everything works, you should see some messages in Visual Studio's 'Output' window, with the final line saying something like

"========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped =========="

If so, congratulations! You have built your first plugin :) If instead you get an error message, please see the [[Beginner's Basic Plugin Guide#Troubleshooting|Troubleshooting]] section below.

=== Testing the plugin ===

If your project builds successfully, it will output a file called 'gen_myplugin.dll' into a 'Debug' or 'Release' folder in the same location you created your project. Look for that file now. We want to copy this file to C:\Program Files\Winamp\Plugins\, which is the folder Winamp examines to find all of its plugins.

# Copy your plugin .dll file into C:\Program Files\Winamp\Plugins\
# Close and re-open Winamp. If your plugin is installed correctly, you should see a popup window with the Init message you typed inside gen_myplugin.cpp. If so, congrats! Your plugin works.
# You can check to see your plugin name by clicking Options -> Preferences -> Plugins -> General purpose. Your plugin name should appear in that window.
# Click on your plugin to hilight it and then select the 'Configure Selected Plugin' button. This should cause the 'config' message to appear.
# If you exit Winamp, you should now see the Quit message pop up as the program exits.

== What's next? ==

So what's next? We don't know. More guides still need to be written. Eventually there may be a guide for each type of plugin: [[Input_Plugin|Input]], [[Output_Plugin|Output]], [[Visualization_Plugin|Visualization]], [[DSP_Plugin|Audio Effect/DSP]], [[General_Purpose_Plugin|General Purpose]], [[Media_Library_Plugin|Media Library]] and [[Portable_Plugin|Portables]].

If you're looking to write a plugin, you may want to start by reading through the [[SDK_Contents]] and trying to find a code example that's similar to what you want to do.

----

== Troubleshooting ==
* '''I get an error message that looks like:'''

<pre>
1>winamp_imms.obj : error LNK2028: unresolved token (0A00001D) "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)

1>winamp_imms.obj : error LNK2019: unresolved external symbol "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)
</pre>

:'''Answer:''' By default Visual Studio Express 2008 doesn't include some files you need in the linker. For example, with our basic code we include windows.h, which is part of user32.dll. However, there is usually a '$(NoInherit)' command in our linker options that tell us not to include user32.dll. To fix this, try the following:

# Right-click on your project and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)'.
# Save and recompile

For more information see [http://stackoverflow.com/questions/739952/c-cli-linker-gives-unresolved-token-for-win32-function here] and [http://stackoverflow.com/questions/721387/i-get-lnk2028-when-trying-to-wrap-native-c-class-using-managed-c here].

* '''* I get an error like'''
<pre>
"1>.\winamp_imms.cpp(29) : error C2146: syntax error : missing ';' before identifier 'plugin'"
</pre>

:'''Answer:''' This could be a namespace error. On this line

<source lang="cpp">
winampGeneralPurposePlugin plugin = {
</source>

we are creating a variable called 'plugin'. The variable's type, rather than being an integer ('int'), floating point number ('float'), or some other type, is of type 'winampGeneralPurposePlugin', which is a type we have created. This type is created in the header file with the code

<source lang="cpp">
typedef struct {
int version;
char *description;
int (*init)();
void (*config)();
void (*quit)();
HWND hwndParent;
HINSTANCE hDllInstance;
} winampGeneralPurposePlugin;
</source>

If you used Visual Studio's auto-generated code, you might have a line that looks like this:

<source lang="cpp">
namespace myplugin {
</source>

this line is telling Visual Studio to put everything inside the 'myplugin' namespace (read up on namespaces [http://en.wikipedia.org/wiki/Namespace here]). We get rid of the default boilerplate code, including the namespace, to make everything work.

Alternatively, you can change the declaration of the 'plugin' variable to say

<source lang="cpp">
myplugin::winampGeneralPurposePlugin plugin = {
</source>

This tells Visual Studio where to look for the winampGeneralPurposePlugin type (i.e., to look inside the 'myplugin' namespace). If you are new to programming or plugin creation, however, you probably don't need (or want) to mess with namespaces.

* '''I get an error like'''

<pre>
1>.\winamp_imms.cpp(41) : error C2664: 'MessageBox' : cannot convert parameter 2 from 'const char [5]' to 'LPCTSTR'
1> Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or function-style cast
</pre>

:'''Answer:''' You need to change the string you pass to the MessageBox function to be of the right type. See the MSDN FAQ entry [http://social.msdn.microsoft.com/Forums/en-US/vclanguage/thread/c1b08c0a-a803-41c3-ac8c-84eba3be1ddb here]. You can most likely fix this by putting a capital 'L' in front of the string.

e.g. change <source lang="cpp">MessageBox(plugin.hwndParent, "Somestring", "", MB_OK);</source> to <source lang="cpp">MessageBox(plugin.hwndParent, L"Somestring", L"", MB_OK);</source>

TODO: What's the right way of doing this for plugins?

* '''My plugin isn't working / My plugin doesn't show up in the Preferences menu.'''

:'''Answer:'''Did you name your plugin with the correct prefix, such as 'gen_myplugin'? If not it may not show up in the window.

TODO: How about other names/plugins? What's the real answer?

[[Category:Articles]]

User talk:Culix

2009-07-01T20:48:08Z

SMonty: /* Going to do some more updating */ new section

See my comments at [[Template_talk:Deleteme]]. I don't visit this Wiki very often, so if you leave a reply on my talk page, it may be a while before I see it. —[[User:Hydrargyrum|Hydrargyrum]][[User_talk:Hydrargyrum|T]] [[Special:Emailuser/Hydrargyrum|@]] 18:43, 18 June 2009 (UTC)

== Going to do some more updating ==

Hi Culix,

I plan to make some more changes to your basic plugins wiki page. This is an outstanding start which I wanted to do for a while. You have encouraged me to actually do some of this. There is some interesting things about parts of the code that you have that I'd like to explain.

I'd like to turn these pages into a series of tutorials on plugins. The trick is that the gen_ plugins and ml_plugins are probably the most commonly used. We can go back and do some of the other types at some point but they tend to be more specialized.

I think the next step will be to expand your basic plugin to retrieve information from the Winamp core. I'll let you know and you can look at it. After that we'll talk about creating a dialog that can invoke methods in the plugin.

Thanks for starting the page.

User:SMonty

2009-07-01T20:41:05Z

SMonty:

Mystery developer. Has access to places only cats normally go. Working on software since stone tablets with holes punched in them were used for input. Sneaks into Winamp and AOL, past searchlights, guards and dogs, to learn how Winamp works. Can be contacted by projecting the silhouette of a Llama projected onto the clouds at night. If case of a clear night, you're on your own, I'm having a beer.

User:SMonty

2009-07-01T20:34:41Z

SMonty:

User:SMonty

2009-07-01T20:33:38Z

SMonty: New page: Mystery developer. Has access to places only cats normally go. Working on software since stone tablets with holes punched in them were used for input. Sneaks into Winamp and AOL to lear...

Mystery developer. Has access to places only cats normally go. Working on software since stone tablets with holes punched in them were used for input. Sneaks into Winamp and AOL to learn how Winamp works.

Complete JavaScript API technology framework

2009-07-01T16:14:38Z

SMonty: /* Add() */

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Online Service Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Main_Page#Glossary_of_Terms|Glossary]]
[[Category:Winamp]]

==Overview==
The purpose of the Winamp Online Service API is to allow Winamp Online Services to interact with the Winamp client in order to provide service developers with a way to create custom experiences for their users based on the power of Winamp. The overall idea is to include exceptional web sites within Winamp Online Services.

The Winamp Online Service API is made up of methods that can be called from scripts within web pages rendered by the Winamp client. The API can be invoked using any scripting language supported by the Microsoft Internet Explorer web browser (5.5 and above). For simplicity, examples in this document will use JavaScript.

==Setup==
The Winamp Online Services API is designed to allow web pages, hosted (displayed) within the embedded browser of the Winamp client, to access the functionality of the client. There are several steps necessary to allow this to take place.

#Make sure you have the latest version of the Winamp client that supports online services.
#Make sure you have the latest version of the ml_webdev plugin (ml_webdev.dll). The presence of this plugin will create a "Web Dev Test Platform" within the Medial Library pane.
#In order to change the starting web page for the online service, start the Winamp client and configure the plugin.
##Select Options->Preferences->Plug-ins->Media Library.
##Select "API 2 Test Platform" and press "Configure selected plugin".
##On the Web Dev Preferences dialog, set the URL field to the URL of the initial web page for the online service. For example, <nowiki>file://c:\myonlineservice\webdev.html</nowiki>
#Click on "Web Dev Test Platform" in the Media Library. You may have to right click and choose refresh to see the new web page.

You should now see the initial page of your online service in the Winamp embedded browser.

==window.external==
The Winamp JavaScript API can be accessed through the window.external object in the Document Object Model (DOM) exposed by the IE browser control embedded within the Winamp client. The API methods can only be accessed thru the Winamp client and are not available if the web page is displayed outside of the client.

The invocation of all methods follow this form
window.external.'''''API'''''.'''''Method'''''

Properties can also be accessed using a similar form:
window.external.'''''API'''''.'''''Property'''''

Where ''API'' is a singleton class that defines a group of related methods (i.e., functionality). For example, Transport (Stop, Play, Next, etc) which controls the "buttons" of the Winamp player.

''Method'' is a function you can call as part of a particular API. For example the following call will stop the Winamp client:
window.external.Transport.Stop();

''Property'' is an internal variable for the particular API that can be queried and in some cases set. For example the following will provide access to the Winamp client shuffle "button":
var shuffle = window.external.Transport.shuffle; // gets the current state
OR
window.external.Transport.shuffle = true; // turns on shuffle

See the documentation on each API below for a complete list of methods and properties.



== Transport API ==
The Transport API is used to control the Winamp client. "Transport controls" was the name given to the buttons on the front panel that controlled hardware devices. This name is used in Winamp for the same purpose. It is also used to access information about the currently playing song.

The Transport API can also be used to register for events involved with asset playback. See the section [[#Transport Events API|Transport Events API]].

===Methods===
====Prev()====
Transport.Prev() can be used to press the "Previous Track" button on the Winamp player. Invoking Prev() while an asset is already playing will cause the previous asset to begin playback immediately. Invoking Prev() while the player is stopped will cause the previous asset to play next time playback starts.

Prototype:
bool Prev();
Example:
var rc = window.external.Transport.Prev();
Return Value:
A boolean value indicating whether the request was successful.

====Play()====
Transport.Play() can be used to press the "Play" button on the Winamp player. Invoking Play() on an asset already playing will cause the asset to restart playback. Pressing Play() on a paused asset will cause it to begin playing from its current position.

Prototype:
bool Play();
Example:
var rc = window.external.Transport.Play();
Return Value:
A boolean value indicating whether the request was successful.

====Pause()====
Transport.Pause() can be used to press the "Pause" button on the Winamp player. Issuing Pause() again, or Play() will cause the asset to continue to play from the location where it was paused.

Prototype:
bool Pause();
Example:
var rc = window.external.Transport.Pause();
Return Value:
A boolean value indicating whether the request was successful.

====Stop()====
Transport.Stop() can be used to press the "Stop" button on the Winamp player.

Prototype:
bool Stop();
Example:
var rc = window.external.Transport.Stop();
Return Value:
A boolean value indicating whether the request was successful.
====Next()====
Transport.Next() can be used to press the "Next Track" button on the Winamp player. Invoking Next() while the player is stopped will cause the next asset to play next time playback starts.

Prototype:
bool Next();
Example:
var rc = window.external.Transport.Next();
Return Value:
A boolean value indicating whether the request was successful.

====GetMetadata()====
Transport.GetMetadata() can be used to fetch metadata for the currently playing asset. The "tag" parameter is specific to different asset encoding formats so a knowledge of the metadata field names is necessary to request specific data about an asset. Some field names are common but others are specific to the encoding format of the asset.

Prototype:
string GetMetadata(tag);
where:
'''tag''' = (string) identifier for the metadata to be returned.
Example:
var metaStr = window.external.Transport.GetMetadata("artist");
Return Value:
A string value containing the requested metadata.

===Properties===
====bool shuffle====
Transport.shuffle provides access to the Winamp client shuffle "button".

Example:
var isShuffling = window.external.Transport.shuffle; // get shuffle state
window.external.Transport.shuffle = true; // turns on shuffle

====bool repeat====
Transport.repeat provides access to the Winamp client repeat "button".

Example:
var isRepeating = window.external.Transport.repeat; // get repeat state
window.external.Transport.repeat = false; // turns off repeat

====int position====
Transport.position provides access to the position being played within the current asset. Setting this value can change the location where playback occurs. position is in milliseconds.

Example:
var position = window.external.Transport.position; // get position in current track
window.external.Transport.position = 221559; // move playback of the current track
// to the specified position.

====bool playing (read only) ====
Transport.playing indicates whether the Winamp Player is currently playing.

Example:
var isPlaying = window.external.Transport.playing; // is player playing?

====bool paused (read only) ====
Transport.paused indicates whether the Winamp Player has been paused.

Example:
var isPaused = window.external.Transport.paused; // is player paused?

====int length (read only)====
Transport.length provides access to the length in seconds of the track currently playing.

Example:
var length = window.external.Transport.length; // get length of current track in secs

====string url (read only)====
Transport.url provides access to the URL (or filename) of the track currently playing.

Example:
var url = window.external.Transport.url; // get url of current track

====string title (read only)====
Transport.title provides access to the title of the track currently playing.

Example:
var title = window.external.Transport.title; // get title of current track

==Transport Events API==
The Event mechanism of the Transport API allows javascript programmers to specify a callback method that will be invoked whenever certain Transport events take place. An Event object is passed back to the method from which properties can be accessed that provide more information about the event.

===RegisterForEvents()===
The RegisterForEvents() method can be used to specify a JavaScript function that is to be called when any Transport Events occur. An event object is passed that indicates the type of event.

Prototype:
boolean RegisterForEvents(handler);

Example:
var rc = window.external.Transport.RegisterForEvents(EventHandler);

Return value:
boolean value indicating whether the request was successful.

===UnregisterFromEvents()===
The UnregisterFromEvents() method is used to stop receiving notifications about Transport events.

Note: The original handler used in RegisterForEvents() must be passed back into UnregisterFromEvents().

Prototype:
boolean UnregisterFromEvents(handler);

Example:
var rc = window.external.Transport.UnregisterFromEvents(EventHandler);

Return value:
boolean value indicating whether the request was successful.

===Events===
The Transport API Event mechanism requires a JavaScript callback method that accepts a single parameter, a reference to a function. This function will be invoked with an "event" object that will indicate the type of event that occurred as well as contain properties containing more information about the event.

====OnStop====
The OnStop event is triggered when the Winamp client is stopped.

=====properties=====
integer event.position = contains the position within the file where the "Stop" was issued. position is the number of milliseconds from the start of the asset.

====OnPlay====
The OnPlay event is triggered when the Winamp client begins playback. If the client is paused and then restarted by "pressing Play", the OnPause event is triggered rather than an OnPlay event.

=====properties=====
string event.filename = contains the filename/URL of the asset starting playback.

====OnPause====
The OnPause event is triggered when the Winamp client is paused or unpaused. If the client is started after being paused, by "pressing Play", the OnPause event is triggered rather than an OnPlay event.

=====properties=====
boolean event.paused = true (the player was paused), false (the player was unpaused)

====OnEndOfFile====
The OnEndOfFile event is triggered when the player reaches the end of a track.

=====properties=====
None

===Callback function===
The callback function is invoked whenever a Transport event is detected. The callback function is specified in both the RegisterForEvents() and UnregisterFromEvents() methods. The method takes a single parameter, which is loaded with an object identifying the event that occurred.

Example:
function EventHandler(event){
{
if (event.event == "OnStop"){
alert("OnStop: position=" + event.position);
}
else if (event.event == "OnEndOfFile"){
alert("OnEndOfFile");
}
else if (event.event == "OnPause"){
alert("OnPause: paused=" + event.paused);
}
else if (event.event == "OnPlay"){
alert("OnPlay: filename=" + event.filename);
}
else {
alert("Unrecognized Event received");
}
}

== PlayQueue API ==
Provides access to the play queue ("Winamp Playlist"). If you need access to the currently playing song, use the Transport API instead.

Note that the Play Queue is the list of assets that are scheduled to be played by the Winamp client. This is not necessarily the same as a user playlist. Once placed in the play queue, assets can be rearrainged or deleted from the play queue without affecting a user playlist. Individual assets can be placed in the play queue without being contained within a user playlist. Additionally, after adding a playlist to the play queue, changes to the playlist will not affect the assets in the play queue.

===Methods===
====Play()====
The PlayQueue.Play() method stops playback, clears the play queue, enqueues the asset specified by the URL and starts playback. If the URL cannot be found, playback will stop, the play queue will be cleared, the URL (or title and length) will appear in the queue but playback will not be started.

Prototype:
bool Play(URL);
bool Play(URL, title);
bool Play(URL, title, length);
where:
'''URL''' = (string) identifies the location of the asset, for a file that is
local or on an attached network drive this would be the fully
qualified path and filename. For files served from a web server,
it would be the http URL.
'''title''' = (string) used as the title when initially placed in
the play queue.
'''length''' = (integer) used as the length when initially place
in the play queue

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:
var rc = window.external.PlayQueue.Play("c:\\Winamp\\01 - Hello.mp3",
"My Cool Title",1024);
Return Value:
A boolean value indicating whether the request was successful.

====Enqueue()====
PlayQueue.Enqueue() is used to add an asset to the play queue. The selected asset is added to the bottom of the queue and current playback is not interrupted.

Prototype:
bool Enqueue(URL);
bool Enqueue(URL, title);
bool Enqueue(URL, title, length);
'''URL''' = (string) identifies the location of the asset, for a file that is
local or on an attached network drive this would be the fully
qualified path and filename. For files served from a web server,
it would be the http URL.
'''title''' = (string) used as the title when initially placed in
the play queue.
'''length''' = (integer) used as the length when initially place
in the play queue

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:
var rc = window.external.PlayQueue.Enqueue("c:\\Winamp\\01 - Hello.mp3",
"My Cool Title",1024);
Return Value:
A boolean value indicating whether the request was successful.

====Insert()====
The PlayQueue.Insert() method can add an asset to the play queue at a specific index.

Prototype:
bool Insert(position, URL);
bool Insert(position, URL, title);
bool Insert(position, URL, title, length);
where:
'''position''' = (integer) a zero based number indicating the location within
the play queue to insert the new asset.
Note: Position is "zero based" so the first entry in the
queue is at position 0.
'''url''' = (string) the URL of the asset to be added
'''title''' = (string) the title to be displayed in the Play Queue.
'''length''' = (integer) the length of the asset to be displayed in
the play queue.

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:
var rc = window.external.PlayQueue.Insert(1, "c:\\mySongs\\mySong.mp3",300);
Return Value:
A boolean value indicating whether the request was successful.

====ClearQueue()====
The PlayQueue.ClearQueue() method removes all assets from the play queue. This does not stop the current playback. ClearQueue is commonly used to prepare the Play Queue for the addition of new assets.

Prototype:
bool ClearQueue()
Example:
var rc = window.external.PlayQueue.ClearQueue();

Return Value:
A boolean value indicating whether the request was successful.

====GetMetadata()====
PlayQueue.GetMetadata() can be used to obtain asset metadata about an asset in the play queue.

Prototype:
String GetMetadata(position, metadatatag);
where:
'''position''' - (integer) is the position of the asset within the playlist.
Note: Position is "zero based" so the first entry in the
queue is at position 0.
'''metadatatag''' - (string) is a tag describing which metadata is requested.

Example:
var mdata = window.external.PlayQueue.GetMetadata(2,"artist");
Return Value:
A String that contains the metadata requested for the asset located at the specified position in the play queue

====GetTitle()====
PlayQueue.GetTitle() retrieves the title of the asset at the specified position within the play queue.

Prototype:
String GetTitle(position);
where:
'''position''' - (integer) is the position of the asset within the playlist.
Note: Position is "zero based" so the first entry in the
queue is at position "0".
Example:
var title = window.external.PlayQueue.GetTitle(1);
Return value:
A String containing the Title of the asset at the requested position in the play queue

====GetURL()====
PlayQueue.GetURL() is used to obtain the URL from the asset at the specified position in the play queue

Prototype:
String GetURL(position);
where:
'''position''' - (integer) is the position of the asset within the playlist.
Note: Position is "zero based" so the first entry in the
queue is at position "0".
Example:
var url = window.external.PlayQueue.GetURL(1);
Return value:
A String containing the URL of the asset at the rquested position in the play queue.

===Properties===
====int length (read only)====
PlayQueue.length contains the length of the current play queue

====int cursor====
PlayQueue.cursor provides access to the position of the currently playing asset within the play queue. This cursor is 0 based, meaning that the first asset in the Play Queue has a cursor value of 0. Valid values range from 0 to the length of the play queue minus one.

If this value is changed before playback is started, the next asset to play will be the one assigned to this property. However, if a song is already playing and this property is changed, the current asset will continue to play even though this property has been updated. At the point that the current asset playback completes, the player will increment the cursor position and play the next asset in the queue rather than the one to which cursor was set. So, for example, to specify the next asset to play while an asset is currently playing, set the cursor property to the position of the asset to play minus one.

== Playlists API ==
The Playlists API is used to process user playlists.

===Methods===
====GetPlaylists()====

Prototype:
Array GetPlaylists();
Example:
var playlists = window.external.Playlists.GetPlaylists();
Return Value:
A array-like object that can be used to examine all user playlists.

Each element of the array represents a user playlist and contains the following properties
*filename - filename of the playlist
*title - name of the playlist
*playlistId - a unique identifier for the playlist, so you can retrieve it later. Also used with OpenPlaylist/SavePlaylist
*length - total length (time) in seconds. Cached data - not guaranteed to be accurate
*numitems - number of items in the playlist. Cached data - not guaranteed to be accurate

====OpenPlaylist()====
Playlists.OpenPlaylist() returns a Playlist object for the specified playlist ID. You must use
Playlists.GetPlaylists() before issuing this request.

Prototype:
Playlist OpenPlaylist(playlistId);
where:
'''playlistId''' - (string) the Id of the playlist to be opened.
Example:
var playlist1 = window.external.Playlists.OpenPlaylist(playlistId);
Return Value:
The Playlist object with the specified playistId.

====SavePlaylist()====
Playlists.SavePlaylist() saves the specified playlist object with the specified ID.

Prototype:
bool SavePlaylist(playlistId, playlist_to_save);
where:
'''playlistId''' (string) is the id of the playlist to be saved.
'''playlist_to_save''' (Playlist) is the Playlist object to be saved.
Example:
var rc = window.external.Playlists.SavePlaylist(playlistId, pl);
Return Value:
A boolean value indicating whether the request was successful.

=== Playlist Object ===
Playlist objects can be created/returned by the OpenPlaylist() method as well as various other APIs.

====Methods====
=====GetItemFilename()=====
The GetItemFilename() method retrieves the filename/URL of the item at the specified index into the playlist.

Prototype:
String GetItemFilename(position);
where:
'''position''' = (number) position of the item in the playlist for which the filename
should be returned.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var filename = playlst.GetItemFilename(0);

Return value:
A string containing the filename/URL of a particular item in the playlist

=====GetItemTitle()=====
The GetItemTitle() method returns the title of the asset at the requested index.

Prototype:
String GetItemTitle(position);
where:
'''position''' = (number) position of the item in the playlist for which the title
should be returned.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var title = playlst.GetItemTitle(0);

Return value:
The song title of the given item in the playlist

=====GetItemLength()=====
The GetItemLength() method retrieves the play length of the asset at the requested index.

Number GetItemLength(position);
where:
'''position''' = (number) position of the item in the playlist for which the length
should be returned.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var itemLength = playlst.GetItemLength(0);

Return value:
A number specifying the play length of the asset, in milliseconds.

=====Reverse()=====
The Reverse() method reverses the order of the assets within a playlist, i.e., the first becomes last and the second becomes second to last, etc.

Prototype:
Reverse();

Example:
var rc = playlst.Reverse();

=====Swap()=====
The Swap() method exchanges the assets at the two specified positions.

Prototype:
Swap(Number position1, Number position2)
where:
'''position1''' = (number) the index of the first item to be swapped.
'''position2''' = (number) the index of the second item to be swapped.
Note: position1 and position2 are "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.Swap(0,1);

=====Randomize()=====
The Randomize() method re-arranges the order of the playlist, placing the assets in random positions.

Prototype:
Randomize();

Example:
var rc = playlst.Randomize();

=====Remove()=====
The Remove() method removes an asset from the playlist. Subsequent assets are moved to lower number positions in the array.

Prototype:
Remove(position);
where:
'''position''' = (number) the position of the asset to be removed.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.Remove(0);

=====SortByTitle()=====
The SortByTitle() method re-arrainges the order of the playlist so that it is alphabetical order by title.

Prototype:
SortByTitle();

Example:
var rc = playlst.SortByTitle();

=====SortByFilename()=====
The SortByFilename() method re-arrainges the order of the playlist so that it is alphabetical order by filename.

Prototype:
SortByFilename();

Example:
var rc = playlst.SortByFilename();

=====SetItemFilename()=====
Sets the filename of the asset at the specified location in the playlist.

playlistObj.SetItemFilename(position, filename);
where:
'''position''' = (number) position of the entry in the playlist to alter the filename
'''filename''' = (string) the new filename
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.SetFilename(0, "c:\\\\myfavorites\\myfavsong.mp3");

=====SetItemTitle()=====
Sets the title of the asset at the specified location in the playlist.

Prototype:
SetItemTitle(position, title);
where:
'''position''' = (number) position of the entry in the playlist to alter the filename
'''title''' = (string) the new title
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.SetItemTitle(0, "My Favorite Title");

=====SetItemLength()=====
Sets the length of the asset at the specified location in the playlist.

SetItemLength(position, length);
where:
'''position''' = (number) position of the entry in the playlist to alter the filename
'''length''' = (number) the new length
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.SetItemLength(0, 1000);

=====InsertURL()=====
Inserts the specified asset in front of the asset at the specified position. That and subsequent items are "pushed" to a higher position in the array.

InsertURL(position, url);
InsertURL(position, url, title);
InsertURL(position, url, title, length);
where:
'''position''' = (number) position within the playlist before which to insert the asset
'''url''' = (string) the URL of the asset to be inserted
'''title''' = (string) title of the asset to be inserted
'''length''' = (number) length (milliseconds) of the asset to be inserted
Note: Position is "zero based" so the first entry in the
playlist is at position 0.
Note: title and length are user specified and do not have to match
the actual values of the asset. When the asset is played, the
values will be replaced in the Play Queue when the URL is opened
for playback but will othewise retain the above values in the
playlist.

Return value:
A boolean value indicating whether the request was successful.

=====AppendURL()=====
The Playlist.AppendURL() method appends an asset URL to the playlist.

Playlist.AppendURL(url);
Playlist.AppendURL(url, title);
Playlist.AppendURL(url, title, length);
where:
'''url''' = (string) the URL to the asset to be appended
'''title''' = (string) title of the asset to be appended
'''length''' = (number) length (milliseconds) of the asset to be appended
Note: title and length are user specified and do not have to match
the actual values of the asset. When the asset is played, the
values will be replaced in the Play Queue when the URL is opened
for playback but will othewise retain the above values in the
playlist.

Return value:
A boolean value indicating whether the request was successful.

=====Clear()=====
The Playlist.Clear() method will remove all assets from the playlist.

Playlist.Clear();

Return value:
A boolean value indicating whether the request was successful

====Properties====
=====int numitems (read only)=====
The Playlist.numitems property contains the number of assets within the playlist.


== Bookmarks API ==
The Bookmarks API provides methods to manage bookmarks.
===Methods===
====Add()====

Prototype:
boolean Add(url, title);
where:
'''url''' = (string) The url of the asset to be bookmarked.
'''title''' = (string) A suitable title to be used within the bookmark.

Example:
var rc = window.external.Bookmarks.Add("c:\myfavs\songstocodeby.mp3",
"Songs To Code By");

Return value:
A boolean value indicating whether the request was successful.

== Podcasts API ==
The Podcasts API provides methods to manage Podcasts.

===Methods===
====Subscribe()====
The Podcasts.Subscribe() method is used to add a channel to the list of podcast subscriptions, automatically subscribe to the podcast and begin downloading of the available episodes. Once downloaded the episodes can be selected for playback.

Prototype:
bool Subscribe(url);
where:
'''url''' = (string) the Podcast URL to subscribe to.

Example:
var rc = window.external.PodCasts.Subscribe(<nowiki>"http://services.winamp.com/rss/news"</nowiki>);

Return value:
boolean value that indicates whether the request was successful.

== Config API ==
The Config API provides a means by which properties can be saved. Properties added using the Config API are persistent across Winamp launches.

===Adding and Retrieving Properties===
Adding a property is accomplished by identifying a property and assigning it a value. Once assigned, the value can be retrieved like any other objects properties.

Example:
window.external.Config.myProperty = "Test";
var myProp = window.external.Config.myProperty; // myProp is set to "Test"

===Storing and Retrieving advanced data types===
Internally, all properties are stored as strings. If you need to store datatypes more advanced than String, Number, or Boolean, it is recommended that you create a JSON string out of your data type.

== Security API ==
===Methods===
====GetActionAuthorization()====
The Security.GetActionAuthorization() method can be used to determine whether a user has previously allowed or denied the functioning of a particular API's methods. Group strings match API names.

Prototype:
number Security.GetActionAuthorization(group);
where:
group = (string) Name of API to check for permission.

Example:
var rc = window.external.Security.GetActionAuthorization("Transport");

Return Data:
*-1 = Either the user has not specified whether to allow/deny use of this API or the action usage is unrestricted.
*0 = The user has previously specified to deny use of this API/method.
*1 = The user has previously specified to allow use of this API/method.


== MediaCore API ==
===Methods===
==== IsRegisteredExtension() ====
MediaCore.IsRegisteredExtension() method can be used to determine if the Winamp client is able to playback a specific format. The file extension of the asset usually indicates the format. This method is important since Winamp support for different formats is contained within plugins which may or may not exist for use.

Prototype:
boolean IsRegisteredExtension(ext);
where:
'''ext''' = (string) identifies the format to be queried for support in the form of a
character string of the extension (a starting period is optional).

Example:
var canPlay = window.external.MediaCore.IsRegisteredExtension("mp3");

Return value:
Boolean value indicating whether the format is supported.

==== GetMetadata() ====
MediaCore.GetMetadata() method can be used to obtain metadata about an asset. This method differs from Transport.GetMetadata() in that the asset does not have to be currently playing. It differs from PlayQueue.GetMetadata() in that it doesn't have to be present in the play queue.

Prototype:
string GetMetadata(url, tag);
where:
'''url''' = (string) containing the URL for which metadata is to be retrieved.
'''tag''' = (string) the specific piece of metadata to be returned.

Example:
var art = window.external.MediaCore.GetMetadata(
"c:\\my favs\\myfavorite.mp3","artist");

Return value:
A string containing the metadata requested.

==== AddMetadataHook() ====
MediaCore.AddMetadataHook() method can be used to add or override metadata for an asset. For example, some assets such as those that are streamed may not contain metadata. This method allows the online service to add metadata for the specified asset. Subsequent GetMetadata() methods will return this information. Online services can override the metadata present within an asset using this method. This method can be used by services that define or can obtain their own metadata for the assets they provide rather than rely on what might or might not be present in the asset itself.

Prototype:
string AddMetadataHook(url, tag, value);
where:
'''url''' = (string) containing the URL for which metadata is to be added.
'''tag''' = (string) the specific metadata key for which a value will be added.
'''value''' - (string) the value of the metadata key being added.

Example:
var rc = window.external.MediaCore.AddMetadataHook(
"c:\\my favs\\myfavorite.mp3","artist","myself");

Return value:
A boolean value that indicates whether the request was successful.

==== RemoveMetadataHook() ====
MediaCore.RemoveMetadataHook() method can be used to remove metadata added through the AddMetadataHook() method. Subsequent GetMetadata() requests will return whatever metadata was available previously, if any.

Prototype:
string RemoveMetadataHook(url, tag);
string RemoveMetadataHook(url);
where:
'''url''' = (string) containing the URL for which metadata is to be removed.
'''tag''' = (string) the specific metadata key for which a value will be removed.

If only the url parameter is provided, all metadata added with AddMetadataHook() for the specified url will be removed.

Example:
var rc = window.external.MediaCore.RemoveMetadataHook(
"c:\\my favs\\myfavorite.mp3","artist");

Return value:
A boolean value that indicates whether the request was successful.

== History API ==
The History branch of the Media Library pane is actually a database containing information about previously played assets. The History API allows a service to search and retrieve information from this database. By specifying a query string, Winamp will return an array of objects that match the values specified in the query.

===Methods===

==== Query() ====
Prototype:
results = History.Query(queryString);
where:
'''queryString''' = a properly formed string to match data to be returned.

Example:
var results = window.external.History.Query("LASTPLAYED<[now]");

Return value:
An "array-like" object that contains the results of the query.

Each entry of the array contains the following properties:
* String filename
* String title
* Number length
* Number playcount
* Date lastplay

'''Query String format:'''
<field> <comparison> [value] [<logic operator> <field> <comparison> [value] [...]]

'''Fields:'''
{| border="1"
|-
! Keyword
! Description
|-
| LASTPLAY
| Date and time when this asset was last played.
|-
| FILENAME
| Full filename (including path)
|-
| LENGTH
| Length, in seconds (or hh:mm:ss)
|-
| TITLE
| Title
|-
| PLAYCOUNT
| Number of times the asset has been played.
|}

'''Comparison Operators:'''
{| border="1"
|-
! Operator
! Description
|-
| '='
| String or integer equals value
|-
| '!='
| String or integer does not equal value
|-
| '<'
| String or integer is less than value
|-
| '>'
| String or integer is greater than value
|-
| '<='
| String or integer is less than or equal to value
|-
| '>='
| String or integer is greater than or equal to value
|-
| HAS
| String contains value
|-
| NOTHAS
| String does not contain value
|-
| LIKE
| String is similar to value ("the" and whitespace are ignored)
|-
| BEGINS
| String begins with value
|-
| BEGINSLIKE
| String begins like value
|-
| ENDS
| String ends with value
|-
| ISEMPTY
| (no comparison value required) TRUE if <field> is empty
|-
| ISNOTEMPTY
| (no comparison value required) TRUE if <field> is not empty
|}

'''Values can be:'''
*"strings with spaces" or strings_without_spaces
*integers can be "32" or just 32
*integers for LENGTH can be a plain integer (seconds), or mm:ss or hh:mm:ss
*date/timestamps should be [datetime data], which can be either an absolute or relative time. i.e.: [3 weeks ago], [18:15], [05/30/2003], [yesterday noon], [3 days ago 5 pm], [now], [5 mn before may 30th], etc.



== Application API ==
===Methods===

====LaunchURL()====
The Application.LaunchURL() method launches a URL in the bento browser
or default browser. The default browser is launched if force_external = true or in skins that don't define a browser.

Prototype:
boolean LaunchURL(url, force_external);
where:
'''url''' = (string) The url to open in the browser
'''force_external''' = (boolean) will force the url to be displayed in a browser
outside of the Winamp client.

Example:

var rc = LaunchURL(<nowiki>"http://www.winamp.com"</nowiki>, true);

Return value:
A boolean value indicating whether the request was successful.

===Properties===
====int version (read only)====
The version property returns the version number of the browser control within the Winamp client as an integer, e.g. 555 for 5.55, 560 for 5.6
====string versionstring (read only)====
The versionstring property returns the version number of the browser control within the Winamp client as a string, e.g. "5.55" for 5.55
====string language (read only) ====
Language identifier from the currently installed language pack. Follows ISO 639-1 two letter language codes

====string languagepack (read only) ====
Language pack identifier from the currently installed language pack. follows the form
lc-CC
where lc is the two letter ISO 639-1 language code
and CC is the two letter ISO 3166 country code.

Note: do not count on the country code being the same as the user's current location.


== Skin API ==

The skin color API is a bit of a challenge. This API reflects some the idiosyncrasies of the underlying skinning system. "Classic" skins define a palette of 24 colors for the skin and an additional 6 colors for the playlist editor. "Modern" skins define these as well as any number of other colors retrievable by name (e.g. wasabi.tree.text for the text color on tree views). A website relying on any of these extra "named" colors should be careful to implement a fallback color based on the classic palette, as no named colors exist in classic skins!

===Methods===
====GetClassicColor()====
The Skin.GetClassicColor() method is used to retrieve color information regarding different Skin UI elements.

Prototype:
GetClassicColor(classiccolornumber);
where:
'''classiccolornumber''' = (integer) A number in the range 0-23 identifying the Skin's UI element
for which the color should be returned.

Example:
var wndBgColor = window.external.Skin.GetClassicColor(2);

Return value:
The HTML color constant used for the specified Skin UI element.

====Classic Color Numbers====
{| border="1"
|-
! Number
! Description
|-
| 0
| Item Background
|-
| 1
| Item Foreground
|-
| 2
| Window Background
|-
| 3
| Button Foreground
|-
| 4
| Window Foreground
|-
| 5
| Hilite
|-
| 6
| Selection
|-
| 7
| List Header Background
|-
| 8
| List Header Text
|-
| 9
| List Header Frame Top
|-
| 10
| List Header Frame Middle
|-
| 11
| List Header Frame Bottom
|-
| 12
| List Header Empty Background
|-
| 13
| Scrollbar Foreground
|-
| 14
| Scrollbar Background
|-
| 15
| Scrollbar Inverse Foreground
|-
| 16
| Scrollbar Inverse Background
|-
| 17
| Scrollbar Dead Area
|-
| 18
| Selection Bar Foreground
|-
| 19
| Selection Bar Background
|-
| 20
| Inactive Selection Bar Foreground
|-
| 21
| Inactive Selection Bar Background
|-
| 22
| Alternating Item Background
|-
| 23
| Alternating Item Foreground
|}

====GetPlaylistColor()====
The Skin.GetPlaylistColor() method is used to retrieve color information regarding different Playlist UI elements.

Prototype:
GetPlaylistColor(playlistcolornumber);
where:
'''playlistcolornumber''' = (integer) a number in the range 0-5 identifying the Playlist's UI
element for which the color should be returned.

Example:
var normalBgColor = window.external.Skin.GetPlaylistColor(2);

Return value:
The HTML color constant used for the specified Playlist UI element.

====Playlist Color Numbers====
{| border="1"
|-
! Number
! Description
|-
| 0
| Normal
|-
| 1
| Current
|-
| 2
| Normal Background
|-
| 3
| Selected Background
|-
| 4
| Video Window Status Bar Foreground
|-
| 5
| Video Window Status Bar Background
|}

====GetSkinColor()====
The Skin.GetSkinColor() method is used to retrieve color information regarding different Playlist UI elements.

Prototype:
GetSkinColor(skincolorname);
where:
'''skincolorname''' = (string) identifying the Skin's UI
element for which the color should be returned.

Example:
var buttonTextColor = window.external.Skin.GetSkinColor("wasabi.button.text");

Return value:
The HTML color constant used for the specified Playlist UI element.

====Skin Color Names====
{| border="1"
|-
! Name
! Description
|-
|"wasabi.list.item.selected.fg"
|Selected item text foreground color
|-
|"wasabi.list.column.separator"
|Color of line between columns
|-
|'''Item Lists, Lists with playable items'''
|
|-
|"wasabi.itemlist.outline.current"
|Currently playing outline color
|-
|"wasabi.itemlist.outline.focus"
|Focused item dashed outline color
|-
|"wasabi.itemlist.selborder"
|
|-
|'''Message box'''
|
|-
|"wasabi.msgBox.background"
|Messagebox background color
|-
|"wasabi.textBar.text"
|Text object & message box text color
|-
|"wasabi.textBar.background"
|Text object & message box text background color
|-
|'''Buttons'''
|
|-
|"wasabi.button.text"
|Buttons text color
|-
|"wasabi.button.hiliteText"
|Buttons hilite text color, used by tab windows
|-
|"wasabi.button.dimmedText"
|Buttons dimmed text color, when disabled
|-
|'''Popup menus'''
|
|-
|"wasabi.popup.text"
|Menu items text color
|-
|"wasabi.popup.hiliteText"
|Hilited item text color
|-
|"wasabi.popup.dimmedText"
|Disabled item text color
|-
|'''Components'''
|
|-
|"wasabi.component.title.foreground"
|Old title bar text color when using TTF
|-
|"wasabi.component.title.border"
|Old title bar text outline when using TTF
|-
|'''Labeled Windows'''
|
|-
|"wasabi.labelwnd.foreground"
|Text foreground color
|-
|"wasabi.labelwnd.background"
|Text drop shadow color
|-
|'''Edit Windows'''
|
|-
|"wasabi.edit.selection"
|Selected text
|-
|"wasabi.edit.text"
|Text
|-
|"wasabi.edit.background"
|Text background
|-
|
|
|-
| "wasabi.text.color"
|
|-
| "wasabi.text.color.inverse"
|
|}

===Properties===
====string name (test)====
The Skin.name property gives access to the name of skin currently in use. Changing this value will change the skin displayed for the player.

====string font (read only)====
The Skin.font property provides the font name currently used in the player.

====string fontsize (read only)====
The Skin.fontsize property provides the size of the font currently used in the player.

== Metadata tag names ==

When retrieving metadata through Winamp, a freeform string is passed. The popular file formats (MP3, WMA, FLAC, M4A) will respond uniformly to a common base of strings. However, each file format is idiosyncratic in how metadata is stored. Some file types will respond to additional strings which are not documented here.

Remember that the metadata is only as good as the tagging in the file itself. A poorly tagged track will return poor metadata.

Common metadata tags
bitrate
length
type
title
artist
albumartist
album
genre
year
disc
publisher
comment
track
composer
conductor

Complete JavaScript API technology framework

2009-07-01T16:10:53Z

SMonty: /* Enqueue() */

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Online Service Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Main_Page#Glossary_of_Terms|Glossary]]
[[Category:Winamp]]

==Overview==
The purpose of the Winamp Online Service API is to allow Winamp Online Services to interact with the Winamp client in order to provide service developers with a way to create custom experiences for their users based on the power of Winamp. The overall idea is to include exceptional web sites within Winamp Online Services.

The Winamp Online Service API is made up of methods that can be called from scripts within web pages rendered by the Winamp client. The API can be invoked using any scripting language supported by the Microsoft Internet Explorer web browser (5.5 and above). For simplicity, examples in this document will use JavaScript.

==Setup==
The Winamp Online Services API is designed to allow web pages, hosted (displayed) within the embedded browser of the Winamp client, to access the functionality of the client. There are several steps necessary to allow this to take place.

#Make sure you have the latest version of the Winamp client that supports online services.
#Make sure you have the latest version of the ml_webdev plugin (ml_webdev.dll). The presence of this plugin will create a "Web Dev Test Platform" within the Medial Library pane.
#In order to change the starting web page for the online service, start the Winamp client and configure the plugin.
##Select Options->Preferences->Plug-ins->Media Library.
##Select "API 2 Test Platform" and press "Configure selected plugin".
##On the Web Dev Preferences dialog, set the URL field to the URL of the initial web page for the online service. For example, <nowiki>file://c:\myonlineservice\webdev.html</nowiki>
#Click on "Web Dev Test Platform" in the Media Library. You may have to right click and choose refresh to see the new web page.

You should now see the initial page of your online service in the Winamp embedded browser.

==window.external==
The Winamp JavaScript API can be accessed through the window.external object in the Document Object Model (DOM) exposed by the IE browser control embedded within the Winamp client. The API methods can only be accessed thru the Winamp client and are not available if the web page is displayed outside of the client.

The invocation of all methods follow this form
window.external.'''''API'''''.'''''Method'''''

Properties can also be accessed using a similar form:
window.external.'''''API'''''.'''''Property'''''

Where ''API'' is a singleton class that defines a group of related methods (i.e., functionality). For example, Transport (Stop, Play, Next, etc) which controls the "buttons" of the Winamp player.

''Method'' is a function you can call as part of a particular API. For example the following call will stop the Winamp client:
window.external.Transport.Stop();

''Property'' is an internal variable for the particular API that can be queried and in some cases set. For example the following will provide access to the Winamp client shuffle "button":
var shuffle = window.external.Transport.shuffle; // gets the current state
OR
window.external.Transport.shuffle = true; // turns on shuffle

See the documentation on each API below for a complete list of methods and properties.



== Transport API ==
The Transport API is used to control the Winamp client. "Transport controls" was the name given to the buttons on the front panel that controlled hardware devices. This name is used in Winamp for the same purpose. It is also used to access information about the currently playing song.

The Transport API can also be used to register for events involved with asset playback. See the section [[#Transport Events API|Transport Events API]].

===Methods===
====Prev()====
Transport.Prev() can be used to press the "Previous Track" button on the Winamp player. Invoking Prev() while an asset is already playing will cause the previous asset to begin playback immediately. Invoking Prev() while the player is stopped will cause the previous asset to play next time playback starts.

Prototype:
bool Prev();
Example:
var rc = window.external.Transport.Prev();
Return Value:
A boolean value indicating whether the request was successful.

====Play()====
Transport.Play() can be used to press the "Play" button on the Winamp player. Invoking Play() on an asset already playing will cause the asset to restart playback. Pressing Play() on a paused asset will cause it to begin playing from its current position.

Prototype:
bool Play();
Example:
var rc = window.external.Transport.Play();
Return Value:
A boolean value indicating whether the request was successful.

====Pause()====
Transport.Pause() can be used to press the "Pause" button on the Winamp player. Issuing Pause() again, or Play() will cause the asset to continue to play from the location where it was paused.

Prototype:
bool Pause();
Example:
var rc = window.external.Transport.Pause();
Return Value:
A boolean value indicating whether the request was successful.

====Stop()====
Transport.Stop() can be used to press the "Stop" button on the Winamp player.

Prototype:
bool Stop();
Example:
var rc = window.external.Transport.Stop();
Return Value:
A boolean value indicating whether the request was successful.
====Next()====
Transport.Next() can be used to press the "Next Track" button on the Winamp player. Invoking Next() while the player is stopped will cause the next asset to play next time playback starts.

Prototype:
bool Next();
Example:
var rc = window.external.Transport.Next();
Return Value:
A boolean value indicating whether the request was successful.

====GetMetadata()====
Transport.GetMetadata() can be used to fetch metadata for the currently playing asset. The "tag" parameter is specific to different asset encoding formats so a knowledge of the metadata field names is necessary to request specific data about an asset. Some field names are common but others are specific to the encoding format of the asset.

Prototype:
string GetMetadata(tag);
where:
'''tag''' = (string) identifier for the metadata to be returned.
Example:
var metaStr = window.external.Transport.GetMetadata("artist");
Return Value:
A string value containing the requested metadata.

===Properties===
====bool shuffle====
Transport.shuffle provides access to the Winamp client shuffle "button".

Example:
var isShuffling = window.external.Transport.shuffle; // get shuffle state
window.external.Transport.shuffle = true; // turns on shuffle

====bool repeat====
Transport.repeat provides access to the Winamp client repeat "button".

Example:
var isRepeating = window.external.Transport.repeat; // get repeat state
window.external.Transport.repeat = false; // turns off repeat

====int position====
Transport.position provides access to the position being played within the current asset. Setting this value can change the location where playback occurs. position is in milliseconds.

Example:
var position = window.external.Transport.position; // get position in current track
window.external.Transport.position = 221559; // move playback of the current track
// to the specified position.

====bool playing (read only) ====
Transport.playing indicates whether the Winamp Player is currently playing.

Example:
var isPlaying = window.external.Transport.playing; // is player playing?

====bool paused (read only) ====
Transport.paused indicates whether the Winamp Player has been paused.

Example:
var isPaused = window.external.Transport.paused; // is player paused?

====int length (read only)====
Transport.length provides access to the length in seconds of the track currently playing.

Example:
var length = window.external.Transport.length; // get length of current track in secs

====string url (read only)====
Transport.url provides access to the URL (or filename) of the track currently playing.

Example:
var url = window.external.Transport.url; // get url of current track

====string title (read only)====
Transport.title provides access to the title of the track currently playing.

Example:
var title = window.external.Transport.title; // get title of current track

==Transport Events API==
The Event mechanism of the Transport API allows javascript programmers to specify a callback method that will be invoked whenever certain Transport events take place. An Event object is passed back to the method from which properties can be accessed that provide more information about the event.

===RegisterForEvents()===
The RegisterForEvents() method can be used to specify a JavaScript function that is to be called when any Transport Events occur. An event object is passed that indicates the type of event.

Prototype:
boolean RegisterForEvents(handler);

Example:
var rc = window.external.Transport.RegisterForEvents(EventHandler);

Return value:
boolean value indicating whether the request was successful.

===UnregisterFromEvents()===
The UnregisterFromEvents() method is used to stop receiving notifications about Transport events.

Note: The original handler used in RegisterForEvents() must be passed back into UnregisterFromEvents().

Prototype:
boolean UnregisterFromEvents(handler);

Example:
var rc = window.external.Transport.UnregisterFromEvents(EventHandler);

Return value:
boolean value indicating whether the request was successful.

===Events===
The Transport API Event mechanism requires a JavaScript callback method that accepts a single parameter, a reference to a function. This function will be invoked with an "event" object that will indicate the type of event that occurred as well as contain properties containing more information about the event.

====OnStop====
The OnStop event is triggered when the Winamp client is stopped.

=====properties=====
integer event.position = contains the position within the file where the "Stop" was issued. position is the number of milliseconds from the start of the asset.

====OnPlay====
The OnPlay event is triggered when the Winamp client begins playback. If the client is paused and then restarted by "pressing Play", the OnPause event is triggered rather than an OnPlay event.

=====properties=====
string event.filename = contains the filename/URL of the asset starting playback.

====OnPause====
The OnPause event is triggered when the Winamp client is paused or unpaused. If the client is started after being paused, by "pressing Play", the OnPause event is triggered rather than an OnPlay event.

=====properties=====
boolean event.paused = true (the player was paused), false (the player was unpaused)

====OnEndOfFile====
The OnEndOfFile event is triggered when the player reaches the end of a track.

=====properties=====
None

===Callback function===
The callback function is invoked whenever a Transport event is detected. The callback function is specified in both the RegisterForEvents() and UnregisterFromEvents() methods. The method takes a single parameter, which is loaded with an object identifying the event that occurred.

Example:
function EventHandler(event){
{
if (event.event == "OnStop"){
alert("OnStop: position=" + event.position);
}
else if (event.event == "OnEndOfFile"){
alert("OnEndOfFile");
}
else if (event.event == "OnPause"){
alert("OnPause: paused=" + event.paused);
}
else if (event.event == "OnPlay"){
alert("OnPlay: filename=" + event.filename);
}
else {
alert("Unrecognized Event received");
}
}

== PlayQueue API ==
Provides access to the play queue ("Winamp Playlist"). If you need access to the currently playing song, use the Transport API instead.

Note that the Play Queue is the list of assets that are scheduled to be played by the Winamp client. This is not necessarily the same as a user playlist. Once placed in the play queue, assets can be rearrainged or deleted from the play queue without affecting a user playlist. Individual assets can be placed in the play queue without being contained within a user playlist. Additionally, after adding a playlist to the play queue, changes to the playlist will not affect the assets in the play queue.

===Methods===
====Play()====
The PlayQueue.Play() method stops playback, clears the play queue, enqueues the asset specified by the URL and starts playback. If the URL cannot be found, playback will stop, the play queue will be cleared, the URL (or title and length) will appear in the queue but playback will not be started.

Prototype:
bool Play(URL);
bool Play(URL, title);
bool Play(URL, title, length);
where:
'''URL''' = (string) identifies the location of the asset, for a file that is
local or on an attached network drive this would be the fully
qualified path and filename. For files served from a web server,
it would be the http URL.
'''title''' = (string) used as the title when initially placed in
the play queue.
'''length''' = (integer) used as the length when initially place
in the play queue

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:
var rc = window.external.PlayQueue.Play("c:\\Winamp\\01 - Hello.mp3",
"My Cool Title",1024);
Return Value:
A boolean value indicating whether the request was successful.

====Enqueue()====
PlayQueue.Enqueue() is used to add an asset to the play queue. The selected asset is added to the bottom of the queue and current playback is not interrupted.

Prototype:
bool Enqueue(URL);
bool Enqueue(URL, title);
bool Enqueue(URL, title, length);
'''URL''' = (string) identifies the location of the asset, for a file that is
local or on an attached network drive this would be the fully
qualified path and filename. For files served from a web server,
it would be the http URL.
'''title''' = (string) used as the title when initially placed in
the play queue.
'''length''' = (integer) used as the length when initially place
in the play queue

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:
var rc = window.external.PlayQueue.Enqueue("c:\\Winamp\\01 - Hello.mp3",
"My Cool Title",1024);
Return Value:
A boolean value indicating whether the request was successful.

====Insert()====
The PlayQueue.Insert() method can add an asset to the play queue at a specific index.

Prototype:
bool Insert(position, URL);
bool Insert(position, URL, title);
bool Insert(position, URL, title, length);
where:
'''position''' = (integer) a zero based number indicating the location within
the play queue to insert the new asset.
Note: Position is "zero based" so the first entry in the
queue is at position 0.
'''url''' = (string) the URL of the asset to be added
'''title''' = (string) the title to be displayed in the Play Queue.
'''length''' = (integer) the length of the asset to be displayed in
the play queue.

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:
var rc = window.external.PlayQueue.Insert(1, "c:\\mySongs\\mySong.mp3",300);
Return Value:
A boolean value indicating whether the request was successful.

====ClearQueue()====
The PlayQueue.ClearQueue() method removes all assets from the play queue. This does not stop the current playback. ClearQueue is commonly used to prepare the Play Queue for the addition of new assets.

Prototype:
bool ClearQueue()
Example:
var rc = window.external.PlayQueue.ClearQueue();

Return Value:
A boolean value indicating whether the request was successful.

====GetMetadata()====
PlayQueue.GetMetadata() can be used to obtain asset metadata about an asset in the play queue.

Prototype:
String GetMetadata(position, metadatatag);
where:
'''position''' - (integer) is the position of the asset within the playlist.
Note: Position is "zero based" so the first entry in the
queue is at position 0.
'''metadatatag''' - (string) is a tag describing which metadata is requested.

Example:
var mdata = window.external.PlayQueue.GetMetadata(2,"artist");
Return Value:
A String that contains the metadata requested for the asset located at the specified position in the play queue

====GetTitle()====
PlayQueue.GetTitle() retrieves the title of the asset at the specified position within the play queue.

Prototype:
String GetTitle(position);
where:
'''position''' - (integer) is the position of the asset within the playlist.
Note: Position is "zero based" so the first entry in the
queue is at position "0".
Example:
var title = window.external.PlayQueue.GetTitle(1);
Return value:
A String containing the Title of the asset at the requested position in the play queue

====GetURL()====
PlayQueue.GetURL() is used to obtain the URL from the asset at the specified position in the play queue

Prototype:
String GetURL(position);
where:
'''position''' - (integer) is the position of the asset within the playlist.
Note: Position is "zero based" so the first entry in the
queue is at position "0".
Example:
var url = window.external.PlayQueue.GetURL(1);
Return value:
A String containing the URL of the asset at the rquested position in the play queue.

===Properties===
====int length (read only)====
PlayQueue.length contains the length of the current play queue

====int cursor====
PlayQueue.cursor provides access to the position of the currently playing asset within the play queue. This cursor is 0 based, meaning that the first asset in the Play Queue has a cursor value of 0. Valid values range from 0 to the length of the play queue minus one.

If this value is changed before playback is started, the next asset to play will be the one assigned to this property. However, if a song is already playing and this property is changed, the current asset will continue to play even though this property has been updated. At the point that the current asset playback completes, the player will increment the cursor position and play the next asset in the queue rather than the one to which cursor was set. So, for example, to specify the next asset to play while an asset is currently playing, set the cursor property to the position of the asset to play minus one.

== Playlists API ==
The Playlists API is used to process user playlists.

===Methods===
====GetPlaylists()====

Prototype:
Array GetPlaylists();
Example:
var playlists = window.external.Playlists.GetPlaylists();
Return Value:
A array-like object that can be used to examine all user playlists.

Each element of the array represents a user playlist and contains the following properties
*filename - filename of the playlist
*title - name of the playlist
*playlistId - a unique identifier for the playlist, so you can retrieve it later. Also used with OpenPlaylist/SavePlaylist
*length - total length (time) in seconds. Cached data - not guaranteed to be accurate
*numitems - number of items in the playlist. Cached data - not guaranteed to be accurate

====OpenPlaylist()====
Playlists.OpenPlaylist() returns a Playlist object for the specified playlist ID. You must use
Playlists.GetPlaylists() before issuing this request.

Prototype:
Playlist OpenPlaylist(playlistId);
where:
'''playlistId''' - (string) the Id of the playlist to be opened.
Example:
var playlist1 = window.external.Playlists.OpenPlaylist(playlistId);
Return Value:
The Playlist object with the specified playistId.

====SavePlaylist()====
Playlists.SavePlaylist() saves the specified playlist object with the specified ID.

Prototype:
bool SavePlaylist(playlistId, playlist_to_save);
where:
'''playlistId''' (string) is the id of the playlist to be saved.
'''playlist_to_save''' (Playlist) is the Playlist object to be saved.
Example:
var rc = window.external.Playlists.SavePlaylist(playlistId, pl);
Return Value:
A boolean value indicating whether the request was successful.

=== Playlist Object ===
Playlist objects can be created/returned by the OpenPlaylist() method as well as various other APIs.

====Methods====
=====GetItemFilename()=====
The GetItemFilename() method retrieves the filename/URL of the item at the specified index into the playlist.

Prototype:
String GetItemFilename(position);
where:
'''position''' = (number) position of the item in the playlist for which the filename
should be returned.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var filename = playlst.GetItemFilename(0);

Return value:
A string containing the filename/URL of a particular item in the playlist

=====GetItemTitle()=====
The GetItemTitle() method returns the title of the asset at the requested index.

Prototype:
String GetItemTitle(position);
where:
'''position''' = (number) position of the item in the playlist for which the title
should be returned.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var title = playlst.GetItemTitle(0);

Return value:
The song title of the given item in the playlist

=====GetItemLength()=====
The GetItemLength() method retrieves the play length of the asset at the requested index.

Number GetItemLength(position);
where:
'''position''' = (number) position of the item in the playlist for which the length
should be returned.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var itemLength = playlst.GetItemLength(0);

Return value:
A number specifying the play length of the asset, in milliseconds.

=====Reverse()=====
The Reverse() method reverses the order of the assets within a playlist, i.e., the first becomes last and the second becomes second to last, etc.

Prototype:
Reverse();

Example:
var rc = playlst.Reverse();

=====Swap()=====
The Swap() method exchanges the assets at the two specified positions.

Prototype:
Swap(Number position1, Number position2)
where:
'''position1''' = (number) the index of the first item to be swapped.
'''position2''' = (number) the index of the second item to be swapped.
Note: position1 and position2 are "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.Swap(0,1);

=====Randomize()=====
The Randomize() method re-arranges the order of the playlist, placing the assets in random positions.

Prototype:
Randomize();

Example:
var rc = playlst.Randomize();

=====Remove()=====
The Remove() method removes an asset from the playlist. Subsequent assets are moved to lower number positions in the array.

Prototype:
Remove(position);
where:
'''position''' = (number) the position of the asset to be removed.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.Remove(0);

=====SortByTitle()=====
The SortByTitle() method re-arrainges the order of the playlist so that it is alphabetical order by title.

Prototype:
SortByTitle();

Example:
var rc = playlst.SortByTitle();

=====SortByFilename()=====
The SortByFilename() method re-arrainges the order of the playlist so that it is alphabetical order by filename.

Prototype:
SortByFilename();

Example:
var rc = playlst.SortByFilename();

=====SetItemFilename()=====
Sets the filename of the asset at the specified location in the playlist.

playlistObj.SetItemFilename(position, filename);
where:
'''position''' = (number) position of the entry in the playlist to alter the filename
'''filename''' = (string) the new filename
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.SetFilename(0, "c:\\\\myfavorites\\myfavsong.mp3");

=====SetItemTitle()=====
Sets the title of the asset at the specified location in the playlist.

Prototype:
SetItemTitle(position, title);
where:
'''position''' = (number) position of the entry in the playlist to alter the filename
'''title''' = (string) the new title
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.SetItemTitle(0, "My Favorite Title");

=====SetItemLength()=====
Sets the length of the asset at the specified location in the playlist.

SetItemLength(position, length);
where:
'''position''' = (number) position of the entry in the playlist to alter the filename
'''length''' = (number) the new length
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.SetItemLength(0, 1000);

=====InsertURL()=====
Inserts the specified asset in front of the asset at the specified position. That and subsequent items are "pushed" to a higher position in the array.

InsertURL(position, url);
InsertURL(position, url, title);
InsertURL(position, url, title, length);
where:
'''position''' = (number) position within the playlist before which to insert the asset
'''url''' = (string) the URL of the asset to be inserted
'''title''' = (string) title of the asset to be inserted
'''length''' = (number) length (milliseconds) of the asset to be inserted
Note: Position is "zero based" so the first entry in the
playlist is at position 0.
Note: title and length are user specified and do not have to match
the actual values of the asset. When the asset is played, the
values will be replaced in the Play Queue when the URL is opened
for playback but will othewise retain the above values in the
playlist.

Return value:
A boolean value indicating whether the request was successful.

=====AppendURL()=====
The Playlist.AppendURL() method appends an asset URL to the playlist.

Playlist.AppendURL(url);
Playlist.AppendURL(url, title);
Playlist.AppendURL(url, title, length);
where:
'''url''' = (string) the URL to the asset to be appended
'''title''' = (string) title of the asset to be appended
'''length''' = (number) length (milliseconds) of the asset to be appended
Note: title and length are user specified and do not have to match
the actual values of the asset. When the asset is played, the
values will be replaced in the Play Queue when the URL is opened
for playback but will othewise retain the above values in the
playlist.

Return value:
A boolean value indicating whether the request was successful.

=====Clear()=====
The Playlist.Clear() method will remove all assets from the playlist.

Playlist.Clear();

Return value:
A boolean value indicating whether the request was successful

====Properties====
=====int numitems (read only)=====
The Playlist.numitems property contains the number of assets within the playlist.


== Bookmarks API ==
The Bookmarks API provides methods to manage bookmarks.
===Methods===
====Add()====

Prototype:
boolean Add(url, title);
where:
'''url''' = (string) The url of the asset to be bookmarked.
'''title''' = (string) A suitable title to be used within the bookmark.

Example:
var rc = window.external.Bookmark.Add("c:\myfavs\songstocodeby.mp3",
"Songs To Code By");

Return value:
A boolean value indicating whether the request was successful.

== Podcasts API ==
The Podcasts API provides methods to manage Podcasts.

===Methods===
====Subscribe()====
The Podcasts.Subscribe() method is used to add a channel to the list of podcast subscriptions, automatically subscribe to the podcast and begin downloading of the available episodes. Once downloaded the episodes can be selected for playback.

Prototype:
bool Subscribe(url);
where:
'''url''' = (string) the Podcast URL to subscribe to.

Example:
var rc = window.external.PodCasts.Subscribe(<nowiki>"http://services.winamp.com/rss/news"</nowiki>);

Return value:
boolean value that indicates whether the request was successful.

== Config API ==
The Config API provides a means by which properties can be saved. Properties added using the Config API are persistent across Winamp launches.

===Adding and Retrieving Properties===
Adding a property is accomplished by identifying a property and assigning it a value. Once assigned, the value can be retrieved like any other objects properties.

Example:
window.external.Config.myProperty = "Test";
var myProp = window.external.Config.myProperty; // myProp is set to "Test"

===Storing and Retrieving advanced data types===
Internally, all properties are stored as strings. If you need to store datatypes more advanced than String, Number, or Boolean, it is recommended that you create a JSON string out of your data type.

== Security API ==
===Methods===
====GetActionAuthorization()====
The Security.GetActionAuthorization() method can be used to determine whether a user has previously allowed or denied the functioning of a particular API's methods. Group strings match API names.

Prototype:
number Security.GetActionAuthorization(group);
where:
group = (string) Name of API to check for permission.

Example:
var rc = window.external.Security.GetActionAuthorization("Transport");

Return Data:
*-1 = Either the user has not specified whether to allow/deny use of this API or the action usage is unrestricted.
*0 = The user has previously specified to deny use of this API/method.
*1 = The user has previously specified to allow use of this API/method.


== MediaCore API ==
===Methods===
==== IsRegisteredExtension() ====
MediaCore.IsRegisteredExtension() method can be used to determine if the Winamp client is able to playback a specific format. The file extension of the asset usually indicates the format. This method is important since Winamp support for different formats is contained within plugins which may or may not exist for use.

Prototype:
boolean IsRegisteredExtension(ext);
where:
'''ext''' = (string) identifies the format to be queried for support in the form of a
character string of the extension (a starting period is optional).

Example:
var canPlay = window.external.MediaCore.IsRegisteredExtension("mp3");

Return value:
Boolean value indicating whether the format is supported.

==== GetMetadata() ====
MediaCore.GetMetadata() method can be used to obtain metadata about an asset. This method differs from Transport.GetMetadata() in that the asset does not have to be currently playing. It differs from PlayQueue.GetMetadata() in that it doesn't have to be present in the play queue.

Prototype:
string GetMetadata(url, tag);
where:
'''url''' = (string) containing the URL for which metadata is to be retrieved.
'''tag''' = (string) the specific piece of metadata to be returned.

Example:
var art = window.external.MediaCore.GetMetadata(
"c:\\my favs\\myfavorite.mp3","artist");

Return value:
A string containing the metadata requested.

==== AddMetadataHook() ====
MediaCore.AddMetadataHook() method can be used to add or override metadata for an asset. For example, some assets such as those that are streamed may not contain metadata. This method allows the online service to add metadata for the specified asset. Subsequent GetMetadata() methods will return this information. Online services can override the metadata present within an asset using this method. This method can be used by services that define or can obtain their own metadata for the assets they provide rather than rely on what might or might not be present in the asset itself.

Prototype:
string AddMetadataHook(url, tag, value);
where:
'''url''' = (string) containing the URL for which metadata is to be added.
'''tag''' = (string) the specific metadata key for which a value will be added.
'''value''' - (string) the value of the metadata key being added.

Example:
var rc = window.external.MediaCore.AddMetadataHook(
"c:\\my favs\\myfavorite.mp3","artist","myself");

Return value:
A boolean value that indicates whether the request was successful.

==== RemoveMetadataHook() ====
MediaCore.RemoveMetadataHook() method can be used to remove metadata added through the AddMetadataHook() method. Subsequent GetMetadata() requests will return whatever metadata was available previously, if any.

Prototype:
string RemoveMetadataHook(url, tag);
string RemoveMetadataHook(url);
where:
'''url''' = (string) containing the URL for which metadata is to be removed.
'''tag''' = (string) the specific metadata key for which a value will be removed.

If only the url parameter is provided, all metadata added with AddMetadataHook() for the specified url will be removed.

Example:
var rc = window.external.MediaCore.RemoveMetadataHook(
"c:\\my favs\\myfavorite.mp3","artist");

Return value:
A boolean value that indicates whether the request was successful.

== History API ==
The History branch of the Media Library pane is actually a database containing information about previously played assets. The History API allows a service to search and retrieve information from this database. By specifying a query string, Winamp will return an array of objects that match the values specified in the query.

===Methods===

==== Query() ====
Prototype:
results = History.Query(queryString);
where:
'''queryString''' = a properly formed string to match data to be returned.

Example:
var results = window.external.History.Query("LASTPLAYED<[now]");

Return value:
An "array-like" object that contains the results of the query.

Each entry of the array contains the following properties:
* String filename
* String title
* Number length
* Number playcount
* Date lastplay

'''Query String format:'''
<field> <comparison> [value] [<logic operator> <field> <comparison> [value] [...]]

'''Fields:'''
{| border="1"
|-
! Keyword
! Description
|-
| LASTPLAY
| Date and time when this asset was last played.
|-
| FILENAME
| Full filename (including path)
|-
| LENGTH
| Length, in seconds (or hh:mm:ss)
|-
| TITLE
| Title
|-
| PLAYCOUNT
| Number of times the asset has been played.
|}

'''Comparison Operators:'''
{| border="1"
|-
! Operator
! Description
|-
| '='
| String or integer equals value
|-
| '!='
| String or integer does not equal value
|-
| '<'
| String or integer is less than value
|-
| '>'
| String or integer is greater than value
|-
| '<='
| String or integer is less than or equal to value
|-
| '>='
| String or integer is greater than or equal to value
|-
| HAS
| String contains value
|-
| NOTHAS
| String does not contain value
|-
| LIKE
| String is similar to value ("the" and whitespace are ignored)
|-
| BEGINS
| String begins with value
|-
| BEGINSLIKE
| String begins like value
|-
| ENDS
| String ends with value
|-
| ISEMPTY
| (no comparison value required) TRUE if <field> is empty
|-
| ISNOTEMPTY
| (no comparison value required) TRUE if <field> is not empty
|}

'''Values can be:'''
*"strings with spaces" or strings_without_spaces
*integers can be "32" or just 32
*integers for LENGTH can be a plain integer (seconds), or mm:ss or hh:mm:ss
*date/timestamps should be [datetime data], which can be either an absolute or relative time. i.e.: [3 weeks ago], [18:15], [05/30/2003], [yesterday noon], [3 days ago 5 pm], [now], [5 mn before may 30th], etc.



== Application API ==
===Methods===

====LaunchURL()====
The Application.LaunchURL() method launches a URL in the bento browser
or default browser. The default browser is launched if force_external = true or in skins that don't define a browser.

Prototype:
boolean LaunchURL(url, force_external);
where:
'''url''' = (string) The url to open in the browser
'''force_external''' = (boolean) will force the url to be displayed in a browser
outside of the Winamp client.

Example:

var rc = LaunchURL(<nowiki>"http://www.winamp.com"</nowiki>, true);

Return value:
A boolean value indicating whether the request was successful.

===Properties===
====int version (read only)====
The version property returns the version number of the browser control within the Winamp client as an integer, e.g. 555 for 5.55, 560 for 5.6
====string versionstring (read only)====
The versionstring property returns the version number of the browser control within the Winamp client as a string, e.g. "5.55" for 5.55
====string language (read only) ====
Language identifier from the currently installed language pack. Follows ISO 639-1 two letter language codes

====string languagepack (read only) ====
Language pack identifier from the currently installed language pack. follows the form
lc-CC
where lc is the two letter ISO 639-1 language code
and CC is the two letter ISO 3166 country code.

Note: do not count on the country code being the same as the user's current location.


== Skin API ==

The skin color API is a bit of a challenge. This API reflects some the idiosyncrasies of the underlying skinning system. "Classic" skins define a palette of 24 colors for the skin and an additional 6 colors for the playlist editor. "Modern" skins define these as well as any number of other colors retrievable by name (e.g. wasabi.tree.text for the text color on tree views). A website relying on any of these extra "named" colors should be careful to implement a fallback color based on the classic palette, as no named colors exist in classic skins!

===Methods===
====GetClassicColor()====
The Skin.GetClassicColor() method is used to retrieve color information regarding different Skin UI elements.

Prototype:
GetClassicColor(classiccolornumber);
where:
'''classiccolornumber''' = (integer) A number in the range 0-23 identifying the Skin's UI element
for which the color should be returned.

Example:
var wndBgColor = window.external.Skin.GetClassicColor(2);

Return value:
The HTML color constant used for the specified Skin UI element.

====Classic Color Numbers====
{| border="1"
|-
! Number
! Description
|-
| 0
| Item Background
|-
| 1
| Item Foreground
|-
| 2
| Window Background
|-
| 3
| Button Foreground
|-
| 4
| Window Foreground
|-
| 5
| Hilite
|-
| 6
| Selection
|-
| 7
| List Header Background
|-
| 8
| List Header Text
|-
| 9
| List Header Frame Top
|-
| 10
| List Header Frame Middle
|-
| 11
| List Header Frame Bottom
|-
| 12
| List Header Empty Background
|-
| 13
| Scrollbar Foreground
|-
| 14
| Scrollbar Background
|-
| 15
| Scrollbar Inverse Foreground
|-
| 16
| Scrollbar Inverse Background
|-
| 17
| Scrollbar Dead Area
|-
| 18
| Selection Bar Foreground
|-
| 19
| Selection Bar Background
|-
| 20
| Inactive Selection Bar Foreground
|-
| 21
| Inactive Selection Bar Background
|-
| 22
| Alternating Item Background
|-
| 23
| Alternating Item Foreground
|}

====GetPlaylistColor()====
The Skin.GetPlaylistColor() method is used to retrieve color information regarding different Playlist UI elements.

Prototype:
GetPlaylistColor(playlistcolornumber);
where:
'''playlistcolornumber''' = (integer) a number in the range 0-5 identifying the Playlist's UI
element for which the color should be returned.

Example:
var normalBgColor = window.external.Skin.GetPlaylistColor(2);

Return value:
The HTML color constant used for the specified Playlist UI element.

====Playlist Color Numbers====
{| border="1"
|-
! Number
! Description
|-
| 0
| Normal
|-
| 1
| Current
|-
| 2
| Normal Background
|-
| 3
| Selected Background
|-
| 4
| Video Window Status Bar Foreground
|-
| 5
| Video Window Status Bar Background
|}

====GetSkinColor()====
The Skin.GetSkinColor() method is used to retrieve color information regarding different Playlist UI elements.

Prototype:
GetSkinColor(skincolorname);
where:
'''skincolorname''' = (string) identifying the Skin's UI
element for which the color should be returned.

Example:
var buttonTextColor = window.external.Skin.GetSkinColor("wasabi.button.text");

Return value:
The HTML color constant used for the specified Playlist UI element.

====Skin Color Names====
{| border="1"
|-
! Name
! Description
|-
|"wasabi.list.item.selected.fg"
|Selected item text foreground color
|-
|"wasabi.list.column.separator"
|Color of line between columns
|-
|'''Item Lists, Lists with playable items'''
|
|-
|"wasabi.itemlist.outline.current"
|Currently playing outline color
|-
|"wasabi.itemlist.outline.focus"
|Focused item dashed outline color
|-
|"wasabi.itemlist.selborder"
|
|-
|'''Message box'''
|
|-
|"wasabi.msgBox.background"
|Messagebox background color
|-
|"wasabi.textBar.text"
|Text object & message box text color
|-
|"wasabi.textBar.background"
|Text object & message box text background color
|-
|'''Buttons'''
|
|-
|"wasabi.button.text"
|Buttons text color
|-
|"wasabi.button.hiliteText"
|Buttons hilite text color, used by tab windows
|-
|"wasabi.button.dimmedText"
|Buttons dimmed text color, when disabled
|-
|'''Popup menus'''
|
|-
|"wasabi.popup.text"
|Menu items text color
|-
|"wasabi.popup.hiliteText"
|Hilited item text color
|-
|"wasabi.popup.dimmedText"
|Disabled item text color
|-
|'''Components'''
|
|-
|"wasabi.component.title.foreground"
|Old title bar text color when using TTF
|-
|"wasabi.component.title.border"
|Old title bar text outline when using TTF
|-
|'''Labeled Windows'''
|
|-
|"wasabi.labelwnd.foreground"
|Text foreground color
|-
|"wasabi.labelwnd.background"
|Text drop shadow color
|-
|'''Edit Windows'''
|
|-
|"wasabi.edit.selection"
|Selected text
|-
|"wasabi.edit.text"
|Text
|-
|"wasabi.edit.background"
|Text background
|-
|
|
|-
| "wasabi.text.color"
|
|-
| "wasabi.text.color.inverse"
|
|}

===Properties===
====string name (test)====
The Skin.name property gives access to the name of skin currently in use. Changing this value will change the skin displayed for the player.

====string font (read only)====
The Skin.font property provides the font name currently used in the player.

====string fontsize (read only)====
The Skin.fontsize property provides the size of the font currently used in the player.

== Metadata tag names ==

When retrieving metadata through Winamp, a freeform string is passed. The popular file formats (MP3, WMA, FLAC, M4A) will respond uniformly to a common base of strings. However, each file format is idiosyncratic in how metadata is stored. Some file types will respond to additional strings which are not documented here.

Remember that the metadata is only as good as the tagging in the file itself. A poorly tagged track will return poor metadata.

Common metadata tags
bitrate
length
type
title
artist
albumartist
album
genre
year
disc
publisher
comment
track
composer
conductor

Complete JavaScript API technology framework

2009-07-01T16:10:17Z

SMonty: /* Play() */

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Online Service Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Main_Page#Glossary_of_Terms|Glossary]]
[[Category:Winamp]]

==Overview==
The purpose of the Winamp Online Service API is to allow Winamp Online Services to interact with the Winamp client in order to provide service developers with a way to create custom experiences for their users based on the power of Winamp. The overall idea is to include exceptional web sites within Winamp Online Services.

The Winamp Online Service API is made up of methods that can be called from scripts within web pages rendered by the Winamp client. The API can be invoked using any scripting language supported by the Microsoft Internet Explorer web browser (5.5 and above). For simplicity, examples in this document will use JavaScript.

==Setup==
The Winamp Online Services API is designed to allow web pages, hosted (displayed) within the embedded browser of the Winamp client, to access the functionality of the client. There are several steps necessary to allow this to take place.

#Make sure you have the latest version of the Winamp client that supports online services.
#Make sure you have the latest version of the ml_webdev plugin (ml_webdev.dll). The presence of this plugin will create a "Web Dev Test Platform" within the Medial Library pane.
#In order to change the starting web page for the online service, start the Winamp client and configure the plugin.
##Select Options->Preferences->Plug-ins->Media Library.
##Select "API 2 Test Platform" and press "Configure selected plugin".
##On the Web Dev Preferences dialog, set the URL field to the URL of the initial web page for the online service. For example, <nowiki>file://c:\myonlineservice\webdev.html</nowiki>
#Click on "Web Dev Test Platform" in the Media Library. You may have to right click and choose refresh to see the new web page.

You should now see the initial page of your online service in the Winamp embedded browser.

==window.external==
The Winamp JavaScript API can be accessed through the window.external object in the Document Object Model (DOM) exposed by the IE browser control embedded within the Winamp client. The API methods can only be accessed thru the Winamp client and are not available if the web page is displayed outside of the client.

The invocation of all methods follow this form
window.external.'''''API'''''.'''''Method'''''

Properties can also be accessed using a similar form:
window.external.'''''API'''''.'''''Property'''''

Where ''API'' is a singleton class that defines a group of related methods (i.e., functionality). For example, Transport (Stop, Play, Next, etc) which controls the "buttons" of the Winamp player.

''Method'' is a function you can call as part of a particular API. For example the following call will stop the Winamp client:
window.external.Transport.Stop();

''Property'' is an internal variable for the particular API that can be queried and in some cases set. For example the following will provide access to the Winamp client shuffle "button":
var shuffle = window.external.Transport.shuffle; // gets the current state
OR
window.external.Transport.shuffle = true; // turns on shuffle

See the documentation on each API below for a complete list of methods and properties.



== Transport API ==
The Transport API is used to control the Winamp client. "Transport controls" was the name given to the buttons on the front panel that controlled hardware devices. This name is used in Winamp for the same purpose. It is also used to access information about the currently playing song.

The Transport API can also be used to register for events involved with asset playback. See the section [[#Transport Events API|Transport Events API]].

===Methods===
====Prev()====
Transport.Prev() can be used to press the "Previous Track" button on the Winamp player. Invoking Prev() while an asset is already playing will cause the previous asset to begin playback immediately. Invoking Prev() while the player is stopped will cause the previous asset to play next time playback starts.

Prototype:
bool Prev();
Example:
var rc = window.external.Transport.Prev();
Return Value:
A boolean value indicating whether the request was successful.

====Play()====
Transport.Play() can be used to press the "Play" button on the Winamp player. Invoking Play() on an asset already playing will cause the asset to restart playback. Pressing Play() on a paused asset will cause it to begin playing from its current position.

Prototype:
bool Play();
Example:
var rc = window.external.Transport.Play();
Return Value:
A boolean value indicating whether the request was successful.

====Pause()====
Transport.Pause() can be used to press the "Pause" button on the Winamp player. Issuing Pause() again, or Play() will cause the asset to continue to play from the location where it was paused.

Prototype:
bool Pause();
Example:
var rc = window.external.Transport.Pause();
Return Value:
A boolean value indicating whether the request was successful.

====Stop()====
Transport.Stop() can be used to press the "Stop" button on the Winamp player.

Prototype:
bool Stop();
Example:
var rc = window.external.Transport.Stop();
Return Value:
A boolean value indicating whether the request was successful.
====Next()====
Transport.Next() can be used to press the "Next Track" button on the Winamp player. Invoking Next() while the player is stopped will cause the next asset to play next time playback starts.

Prototype:
bool Next();
Example:
var rc = window.external.Transport.Next();
Return Value:
A boolean value indicating whether the request was successful.

====GetMetadata()====
Transport.GetMetadata() can be used to fetch metadata for the currently playing asset. The "tag" parameter is specific to different asset encoding formats so a knowledge of the metadata field names is necessary to request specific data about an asset. Some field names are common but others are specific to the encoding format of the asset.

Prototype:
string GetMetadata(tag);
where:
'''tag''' = (string) identifier for the metadata to be returned.
Example:
var metaStr = window.external.Transport.GetMetadata("artist");
Return Value:
A string value containing the requested metadata.

===Properties===
====bool shuffle====
Transport.shuffle provides access to the Winamp client shuffle "button".

Example:
var isShuffling = window.external.Transport.shuffle; // get shuffle state
window.external.Transport.shuffle = true; // turns on shuffle

====bool repeat====
Transport.repeat provides access to the Winamp client repeat "button".

Example:
var isRepeating = window.external.Transport.repeat; // get repeat state
window.external.Transport.repeat = false; // turns off repeat

====int position====
Transport.position provides access to the position being played within the current asset. Setting this value can change the location where playback occurs. position is in milliseconds.

Example:
var position = window.external.Transport.position; // get position in current track
window.external.Transport.position = 221559; // move playback of the current track
// to the specified position.

====bool playing (read only) ====
Transport.playing indicates whether the Winamp Player is currently playing.

Example:
var isPlaying = window.external.Transport.playing; // is player playing?

====bool paused (read only) ====
Transport.paused indicates whether the Winamp Player has been paused.

Example:
var isPaused = window.external.Transport.paused; // is player paused?

====int length (read only)====
Transport.length provides access to the length in seconds of the track currently playing.

Example:
var length = window.external.Transport.length; // get length of current track in secs

====string url (read only)====
Transport.url provides access to the URL (or filename) of the track currently playing.

Example:
var url = window.external.Transport.url; // get url of current track

====string title (read only)====
Transport.title provides access to the title of the track currently playing.

Example:
var title = window.external.Transport.title; // get title of current track

==Transport Events API==
The Event mechanism of the Transport API allows javascript programmers to specify a callback method that will be invoked whenever certain Transport events take place. An Event object is passed back to the method from which properties can be accessed that provide more information about the event.

===RegisterForEvents()===
The RegisterForEvents() method can be used to specify a JavaScript function that is to be called when any Transport Events occur. An event object is passed that indicates the type of event.

Prototype:
boolean RegisterForEvents(handler);

Example:
var rc = window.external.Transport.RegisterForEvents(EventHandler);

Return value:
boolean value indicating whether the request was successful.

===UnregisterFromEvents()===
The UnregisterFromEvents() method is used to stop receiving notifications about Transport events.

Note: The original handler used in RegisterForEvents() must be passed back into UnregisterFromEvents().

Prototype:
boolean UnregisterFromEvents(handler);

Example:
var rc = window.external.Transport.UnregisterFromEvents(EventHandler);

Return value:
boolean value indicating whether the request was successful.

===Events===
The Transport API Event mechanism requires a JavaScript callback method that accepts a single parameter, a reference to a function. This function will be invoked with an "event" object that will indicate the type of event that occurred as well as contain properties containing more information about the event.

====OnStop====
The OnStop event is triggered when the Winamp client is stopped.

=====properties=====
integer event.position = contains the position within the file where the "Stop" was issued. position is the number of milliseconds from the start of the asset.

====OnPlay====
The OnPlay event is triggered when the Winamp client begins playback. If the client is paused and then restarted by "pressing Play", the OnPause event is triggered rather than an OnPlay event.

=====properties=====
string event.filename = contains the filename/URL of the asset starting playback.

====OnPause====
The OnPause event is triggered when the Winamp client is paused or unpaused. If the client is started after being paused, by "pressing Play", the OnPause event is triggered rather than an OnPlay event.

=====properties=====
boolean event.paused = true (the player was paused), false (the player was unpaused)

====OnEndOfFile====
The OnEndOfFile event is triggered when the player reaches the end of a track.

=====properties=====
None

===Callback function===
The callback function is invoked whenever a Transport event is detected. The callback function is specified in both the RegisterForEvents() and UnregisterFromEvents() methods. The method takes a single parameter, which is loaded with an object identifying the event that occurred.

Example:
function EventHandler(event){
{
if (event.event == "OnStop"){
alert("OnStop: position=" + event.position);
}
else if (event.event == "OnEndOfFile"){
alert("OnEndOfFile");
}
else if (event.event == "OnPause"){
alert("OnPause: paused=" + event.paused);
}
else if (event.event == "OnPlay"){
alert("OnPlay: filename=" + event.filename);
}
else {
alert("Unrecognized Event received");
}
}

== PlayQueue API ==
Provides access to the play queue ("Winamp Playlist"). If you need access to the currently playing song, use the Transport API instead.

Note that the Play Queue is the list of assets that are scheduled to be played by the Winamp client. This is not necessarily the same as a user playlist. Once placed in the play queue, assets can be rearrainged or deleted from the play queue without affecting a user playlist. Individual assets can be placed in the play queue without being contained within a user playlist. Additionally, after adding a playlist to the play queue, changes to the playlist will not affect the assets in the play queue.

===Methods===
====Play()====
The PlayQueue.Play() method stops playback, clears the play queue, enqueues the asset specified by the URL and starts playback. If the URL cannot be found, playback will stop, the play queue will be cleared, the URL (or title and length) will appear in the queue but playback will not be started.

Prototype:
bool Play(URL);
bool Play(URL, title);
bool Play(URL, title, length);
where:
'''URL''' = (string) identifies the location of the asset, for a file that is
local or on an attached network drive this would be the fully
qualified path and filename. For files served from a web server,
it would be the http URL.
'''title''' = (string) used as the title when initially placed in
the play queue.
'''length''' = (integer) used as the length when initially place
in the play queue

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:
var rc = window.external.PlayQueue.Play("c:\\Winamp\\01 - Hello.mp3",
"My Cool Title",1024);
Return Value:
A boolean value indicating whether the request was successful.

====Enqueue()====
PlayQueue.Enqueue() is used to add an asset to the play queue. The selected asset is added to the bottom of the queue and current playback is not interrupted.

Prototype:
bool Enqueue(URL);
bool Enqueue(URL, title);
bool Enqueue(URL, title, length);
'''URL''' = (string) identifies the location of the asset, for a file that is
local or on an attached network drive this would be the fully
qualified path and filename. For files served from a web server,
it would be the http URL.
'''title''' = (string) used as the title when initially placed in
the play queue.
'''length''' = (integer) used as the length when initially place
in the play queue

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:
var rc = window.extern.PlayQueue.Enqueue("c:\\Winamp\\01 - Hello.mp3",
"My Cool Title",1024);
Return Value:
A boolean value indicating whether the request was successful.

====Insert()====
The PlayQueue.Insert() method can add an asset to the play queue at a specific index.

Prototype:
bool Insert(position, URL);
bool Insert(position, URL, title);
bool Insert(position, URL, title, length);
where:
'''position''' = (integer) a zero based number indicating the location within
the play queue to insert the new asset.
Note: Position is "zero based" so the first entry in the
queue is at position 0.
'''url''' = (string) the URL of the asset to be added
'''title''' = (string) the title to be displayed in the Play Queue.
'''length''' = (integer) the length of the asset to be displayed in
the play queue.

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:
var rc = window.external.PlayQueue.Insert(1, "c:\\mySongs\\mySong.mp3",300);
Return Value:
A boolean value indicating whether the request was successful.

====ClearQueue()====
The PlayQueue.ClearQueue() method removes all assets from the play queue. This does not stop the current playback. ClearQueue is commonly used to prepare the Play Queue for the addition of new assets.

Prototype:
bool ClearQueue()
Example:
var rc = window.external.PlayQueue.ClearQueue();

Return Value:
A boolean value indicating whether the request was successful.

====GetMetadata()====
PlayQueue.GetMetadata() can be used to obtain asset metadata about an asset in the play queue.

Prototype:
String GetMetadata(position, metadatatag);
where:
'''position''' - (integer) is the position of the asset within the playlist.
Note: Position is "zero based" so the first entry in the
queue is at position 0.
'''metadatatag''' - (string) is a tag describing which metadata is requested.

Example:
var mdata = window.external.PlayQueue.GetMetadata(2,"artist");
Return Value:
A String that contains the metadata requested for the asset located at the specified position in the play queue

====GetTitle()====
PlayQueue.GetTitle() retrieves the title of the asset at the specified position within the play queue.

Prototype:
String GetTitle(position);
where:
'''position''' - (integer) is the position of the asset within the playlist.
Note: Position is "zero based" so the first entry in the
queue is at position "0".
Example:
var title = window.external.PlayQueue.GetTitle(1);
Return value:
A String containing the Title of the asset at the requested position in the play queue

====GetURL()====
PlayQueue.GetURL() is used to obtain the URL from the asset at the specified position in the play queue

Prototype:
String GetURL(position);
where:
'''position''' - (integer) is the position of the asset within the playlist.
Note: Position is "zero based" so the first entry in the
queue is at position "0".
Example:
var url = window.external.PlayQueue.GetURL(1);
Return value:
A String containing the URL of the asset at the rquested position in the play queue.

===Properties===
====int length (read only)====
PlayQueue.length contains the length of the current play queue

====int cursor====
PlayQueue.cursor provides access to the position of the currently playing asset within the play queue. This cursor is 0 based, meaning that the first asset in the Play Queue has a cursor value of 0. Valid values range from 0 to the length of the play queue minus one.

If this value is changed before playback is started, the next asset to play will be the one assigned to this property. However, if a song is already playing and this property is changed, the current asset will continue to play even though this property has been updated. At the point that the current asset playback completes, the player will increment the cursor position and play the next asset in the queue rather than the one to which cursor was set. So, for example, to specify the next asset to play while an asset is currently playing, set the cursor property to the position of the asset to play minus one.

== Playlists API ==
The Playlists API is used to process user playlists.

===Methods===
====GetPlaylists()====

Prototype:
Array GetPlaylists();
Example:
var playlists = window.external.Playlists.GetPlaylists();
Return Value:
A array-like object that can be used to examine all user playlists.

Each element of the array represents a user playlist and contains the following properties
*filename - filename of the playlist
*title - name of the playlist
*playlistId - a unique identifier for the playlist, so you can retrieve it later. Also used with OpenPlaylist/SavePlaylist
*length - total length (time) in seconds. Cached data - not guaranteed to be accurate
*numitems - number of items in the playlist. Cached data - not guaranteed to be accurate

====OpenPlaylist()====
Playlists.OpenPlaylist() returns a Playlist object for the specified playlist ID. You must use
Playlists.GetPlaylists() before issuing this request.

Prototype:
Playlist OpenPlaylist(playlistId);
where:
'''playlistId''' - (string) the Id of the playlist to be opened.
Example:
var playlist1 = window.external.Playlists.OpenPlaylist(playlistId);
Return Value:
The Playlist object with the specified playistId.

====SavePlaylist()====
Playlists.SavePlaylist() saves the specified playlist object with the specified ID.

Prototype:
bool SavePlaylist(playlistId, playlist_to_save);
where:
'''playlistId''' (string) is the id of the playlist to be saved.
'''playlist_to_save''' (Playlist) is the Playlist object to be saved.
Example:
var rc = window.external.Playlists.SavePlaylist(playlistId, pl);
Return Value:
A boolean value indicating whether the request was successful.

=== Playlist Object ===
Playlist objects can be created/returned by the OpenPlaylist() method as well as various other APIs.

====Methods====
=====GetItemFilename()=====
The GetItemFilename() method retrieves the filename/URL of the item at the specified index into the playlist.

Prototype:
String GetItemFilename(position);
where:
'''position''' = (number) position of the item in the playlist for which the filename
should be returned.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var filename = playlst.GetItemFilename(0);

Return value:
A string containing the filename/URL of a particular item in the playlist

=====GetItemTitle()=====
The GetItemTitle() method returns the title of the asset at the requested index.

Prototype:
String GetItemTitle(position);
where:
'''position''' = (number) position of the item in the playlist for which the title
should be returned.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var title = playlst.GetItemTitle(0);

Return value:
The song title of the given item in the playlist

=====GetItemLength()=====
The GetItemLength() method retrieves the play length of the asset at the requested index.

Number GetItemLength(position);
where:
'''position''' = (number) position of the item in the playlist for which the length
should be returned.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var itemLength = playlst.GetItemLength(0);

Return value:
A number specifying the play length of the asset, in milliseconds.

=====Reverse()=====
The Reverse() method reverses the order of the assets within a playlist, i.e., the first becomes last and the second becomes second to last, etc.

Prototype:
Reverse();

Example:
var rc = playlst.Reverse();

=====Swap()=====
The Swap() method exchanges the assets at the two specified positions.

Prototype:
Swap(Number position1, Number position2)
where:
'''position1''' = (number) the index of the first item to be swapped.
'''position2''' = (number) the index of the second item to be swapped.
Note: position1 and position2 are "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.Swap(0,1);

=====Randomize()=====
The Randomize() method re-arranges the order of the playlist, placing the assets in random positions.

Prototype:
Randomize();

Example:
var rc = playlst.Randomize();

=====Remove()=====
The Remove() method removes an asset from the playlist. Subsequent assets are moved to lower number positions in the array.

Prototype:
Remove(position);
where:
'''position''' = (number) the position of the asset to be removed.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.Remove(0);

=====SortByTitle()=====
The SortByTitle() method re-arrainges the order of the playlist so that it is alphabetical order by title.

Prototype:
SortByTitle();

Example:
var rc = playlst.SortByTitle();

=====SortByFilename()=====
The SortByFilename() method re-arrainges the order of the playlist so that it is alphabetical order by filename.

Prototype:
SortByFilename();

Example:
var rc = playlst.SortByFilename();

=====SetItemFilename()=====
Sets the filename of the asset at the specified location in the playlist.

playlistObj.SetItemFilename(position, filename);
where:
'''position''' = (number) position of the entry in the playlist to alter the filename
'''filename''' = (string) the new filename
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.SetFilename(0, "c:\\\\myfavorites\\myfavsong.mp3");

=====SetItemTitle()=====
Sets the title of the asset at the specified location in the playlist.

Prototype:
SetItemTitle(position, title);
where:
'''position''' = (number) position of the entry in the playlist to alter the filename
'''title''' = (string) the new title
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.SetItemTitle(0, "My Favorite Title");

=====SetItemLength()=====
Sets the length of the asset at the specified location in the playlist.

SetItemLength(position, length);
where:
'''position''' = (number) position of the entry in the playlist to alter the filename
'''length''' = (number) the new length
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.SetItemLength(0, 1000);

=====InsertURL()=====
Inserts the specified asset in front of the asset at the specified position. That and subsequent items are "pushed" to a higher position in the array.

InsertURL(position, url);
InsertURL(position, url, title);
InsertURL(position, url, title, length);
where:
'''position''' = (number) position within the playlist before which to insert the asset
'''url''' = (string) the URL of the asset to be inserted
'''title''' = (string) title of the asset to be inserted
'''length''' = (number) length (milliseconds) of the asset to be inserted
Note: Position is "zero based" so the first entry in the
playlist is at position 0.
Note: title and length are user specified and do not have to match
the actual values of the asset. When the asset is played, the
values will be replaced in the Play Queue when the URL is opened
for playback but will othewise retain the above values in the
playlist.

Return value:
A boolean value indicating whether the request was successful.

=====AppendURL()=====
The Playlist.AppendURL() method appends an asset URL to the playlist.

Playlist.AppendURL(url);
Playlist.AppendURL(url, title);
Playlist.AppendURL(url, title, length);
where:
'''url''' = (string) the URL to the asset to be appended
'''title''' = (string) title of the asset to be appended
'''length''' = (number) length (milliseconds) of the asset to be appended
Note: title and length are user specified and do not have to match
the actual values of the asset. When the asset is played, the
values will be replaced in the Play Queue when the URL is opened
for playback but will othewise retain the above values in the
playlist.

Return value:
A boolean value indicating whether the request was successful.

=====Clear()=====
The Playlist.Clear() method will remove all assets from the playlist.

Playlist.Clear();

Return value:
A boolean value indicating whether the request was successful

====Properties====
=====int numitems (read only)=====
The Playlist.numitems property contains the number of assets within the playlist.


== Bookmarks API ==
The Bookmarks API provides methods to manage bookmarks.
===Methods===
====Add()====

Prototype:
boolean Add(url, title);
where:
'''url''' = (string) The url of the asset to be bookmarked.
'''title''' = (string) A suitable title to be used within the bookmark.

Example:
var rc = window.external.Bookmark.Add("c:\myfavs\songstocodeby.mp3",
"Songs To Code By");

Return value:
A boolean value indicating whether the request was successful.

== Podcasts API ==
The Podcasts API provides methods to manage Podcasts.

===Methods===
====Subscribe()====
The Podcasts.Subscribe() method is used to add a channel to the list of podcast subscriptions, automatically subscribe to the podcast and begin downloading of the available episodes. Once downloaded the episodes can be selected for playback.

Prototype:
bool Subscribe(url);
where:
'''url''' = (string) the Podcast URL to subscribe to.

Example:
var rc = window.external.PodCasts.Subscribe(<nowiki>"http://services.winamp.com/rss/news"</nowiki>);

Return value:
boolean value that indicates whether the request was successful.

== Config API ==
The Config API provides a means by which properties can be saved. Properties added using the Config API are persistent across Winamp launches.

===Adding and Retrieving Properties===
Adding a property is accomplished by identifying a property and assigning it a value. Once assigned, the value can be retrieved like any other objects properties.

Example:
window.external.Config.myProperty = "Test";
var myProp = window.external.Config.myProperty; // myProp is set to "Test"

===Storing and Retrieving advanced data types===
Internally, all properties are stored as strings. If you need to store datatypes more advanced than String, Number, or Boolean, it is recommended that you create a JSON string out of your data type.

== Security API ==
===Methods===
====GetActionAuthorization()====
The Security.GetActionAuthorization() method can be used to determine whether a user has previously allowed or denied the functioning of a particular API's methods. Group strings match API names.

Prototype:
number Security.GetActionAuthorization(group);
where:
group = (string) Name of API to check for permission.

Example:
var rc = window.external.Security.GetActionAuthorization("Transport");

Return Data:
*-1 = Either the user has not specified whether to allow/deny use of this API or the action usage is unrestricted.
*0 = The user has previously specified to deny use of this API/method.
*1 = The user has previously specified to allow use of this API/method.


== MediaCore API ==
===Methods===
==== IsRegisteredExtension() ====
MediaCore.IsRegisteredExtension() method can be used to determine if the Winamp client is able to playback a specific format. The file extension of the asset usually indicates the format. This method is important since Winamp support for different formats is contained within plugins which may or may not exist for use.

Prototype:
boolean IsRegisteredExtension(ext);
where:
'''ext''' = (string) identifies the format to be queried for support in the form of a
character string of the extension (a starting period is optional).

Example:
var canPlay = window.external.MediaCore.IsRegisteredExtension("mp3");

Return value:
Boolean value indicating whether the format is supported.

==== GetMetadata() ====
MediaCore.GetMetadata() method can be used to obtain metadata about an asset. This method differs from Transport.GetMetadata() in that the asset does not have to be currently playing. It differs from PlayQueue.GetMetadata() in that it doesn't have to be present in the play queue.

Prototype:
string GetMetadata(url, tag);
where:
'''url''' = (string) containing the URL for which metadata is to be retrieved.
'''tag''' = (string) the specific piece of metadata to be returned.

Example:
var art = window.external.MediaCore.GetMetadata(
"c:\\my favs\\myfavorite.mp3","artist");

Return value:
A string containing the metadata requested.

==== AddMetadataHook() ====
MediaCore.AddMetadataHook() method can be used to add or override metadata for an asset. For example, some assets such as those that are streamed may not contain metadata. This method allows the online service to add metadata for the specified asset. Subsequent GetMetadata() methods will return this information. Online services can override the metadata present within an asset using this method. This method can be used by services that define or can obtain their own metadata for the assets they provide rather than rely on what might or might not be present in the asset itself.

Prototype:
string AddMetadataHook(url, tag, value);
where:
'''url''' = (string) containing the URL for which metadata is to be added.
'''tag''' = (string) the specific metadata key for which a value will be added.
'''value''' - (string) the value of the metadata key being added.

Example:
var rc = window.external.MediaCore.AddMetadataHook(
"c:\\my favs\\myfavorite.mp3","artist","myself");

Return value:
A boolean value that indicates whether the request was successful.

==== RemoveMetadataHook() ====
MediaCore.RemoveMetadataHook() method can be used to remove metadata added through the AddMetadataHook() method. Subsequent GetMetadata() requests will return whatever metadata was available previously, if any.

Prototype:
string RemoveMetadataHook(url, tag);
string RemoveMetadataHook(url);
where:
'''url''' = (string) containing the URL for which metadata is to be removed.
'''tag''' = (string) the specific metadata key for which a value will be removed.

If only the url parameter is provided, all metadata added with AddMetadataHook() for the specified url will be removed.

Example:
var rc = window.external.MediaCore.RemoveMetadataHook(
"c:\\my favs\\myfavorite.mp3","artist");

Return value:
A boolean value that indicates whether the request was successful.

== History API ==
The History branch of the Media Library pane is actually a database containing information about previously played assets. The History API allows a service to search and retrieve information from this database. By specifying a query string, Winamp will return an array of objects that match the values specified in the query.

===Methods===

==== Query() ====
Prototype:
results = History.Query(queryString);
where:
'''queryString''' = a properly formed string to match data to be returned.

Example:
var results = window.external.History.Query("LASTPLAYED<[now]");

Return value:
An "array-like" object that contains the results of the query.

Each entry of the array contains the following properties:
* String filename
* String title
* Number length
* Number playcount
* Date lastplay

'''Query String format:'''
<field> <comparison> [value] [<logic operator> <field> <comparison> [value] [...]]

'''Fields:'''
{| border="1"
|-
! Keyword
! Description
|-
| LASTPLAY
| Date and time when this asset was last played.
|-
| FILENAME
| Full filename (including path)
|-
| LENGTH
| Length, in seconds (or hh:mm:ss)
|-
| TITLE
| Title
|-
| PLAYCOUNT
| Number of times the asset has been played.
|}

'''Comparison Operators:'''
{| border="1"
|-
! Operator
! Description
|-
| '='
| String or integer equals value
|-
| '!='
| String or integer does not equal value
|-
| '<'
| String or integer is less than value
|-
| '>'
| String or integer is greater than value
|-
| '<='
| String or integer is less than or equal to value
|-
| '>='
| String or integer is greater than or equal to value
|-
| HAS
| String contains value
|-
| NOTHAS
| String does not contain value
|-
| LIKE
| String is similar to value ("the" and whitespace are ignored)
|-
| BEGINS
| String begins with value
|-
| BEGINSLIKE
| String begins like value
|-
| ENDS
| String ends with value
|-
| ISEMPTY
| (no comparison value required) TRUE if <field> is empty
|-
| ISNOTEMPTY
| (no comparison value required) TRUE if <field> is not empty
|}

'''Values can be:'''
*"strings with spaces" or strings_without_spaces
*integers can be "32" or just 32
*integers for LENGTH can be a plain integer (seconds), or mm:ss or hh:mm:ss
*date/timestamps should be [datetime data], which can be either an absolute or relative time. i.e.: [3 weeks ago], [18:15], [05/30/2003], [yesterday noon], [3 days ago 5 pm], [now], [5 mn before may 30th], etc.



== Application API ==
===Methods===

====LaunchURL()====
The Application.LaunchURL() method launches a URL in the bento browser
or default browser. The default browser is launched if force_external = true or in skins that don't define a browser.

Prototype:
boolean LaunchURL(url, force_external);
where:
'''url''' = (string) The url to open in the browser
'''force_external''' = (boolean) will force the url to be displayed in a browser
outside of the Winamp client.

Example:

var rc = LaunchURL(<nowiki>"http://www.winamp.com"</nowiki>, true);

Return value:
A boolean value indicating whether the request was successful.

===Properties===
====int version (read only)====
The version property returns the version number of the browser control within the Winamp client as an integer, e.g. 555 for 5.55, 560 for 5.6
====string versionstring (read only)====
The versionstring property returns the version number of the browser control within the Winamp client as a string, e.g. "5.55" for 5.55
====string language (read only) ====
Language identifier from the currently installed language pack. Follows ISO 639-1 two letter language codes

====string languagepack (read only) ====
Language pack identifier from the currently installed language pack. follows the form
lc-CC
where lc is the two letter ISO 639-1 language code
and CC is the two letter ISO 3166 country code.

Note: do not count on the country code being the same as the user's current location.


== Skin API ==

The skin color API is a bit of a challenge. This API reflects some the idiosyncrasies of the underlying skinning system. "Classic" skins define a palette of 24 colors for the skin and an additional 6 colors for the playlist editor. "Modern" skins define these as well as any number of other colors retrievable by name (e.g. wasabi.tree.text for the text color on tree views). A website relying on any of these extra "named" colors should be careful to implement a fallback color based on the classic palette, as no named colors exist in classic skins!

===Methods===
====GetClassicColor()====
The Skin.GetClassicColor() method is used to retrieve color information regarding different Skin UI elements.

Prototype:
GetClassicColor(classiccolornumber);
where:
'''classiccolornumber''' = (integer) A number in the range 0-23 identifying the Skin's UI element
for which the color should be returned.

Example:
var wndBgColor = window.external.Skin.GetClassicColor(2);

Return value:
The HTML color constant used for the specified Skin UI element.

====Classic Color Numbers====
{| border="1"
|-
! Number
! Description
|-
| 0
| Item Background
|-
| 1
| Item Foreground
|-
| 2
| Window Background
|-
| 3
| Button Foreground
|-
| 4
| Window Foreground
|-
| 5
| Hilite
|-
| 6
| Selection
|-
| 7
| List Header Background
|-
| 8
| List Header Text
|-
| 9
| List Header Frame Top
|-
| 10
| List Header Frame Middle
|-
| 11
| List Header Frame Bottom
|-
| 12
| List Header Empty Background
|-
| 13
| Scrollbar Foreground
|-
| 14
| Scrollbar Background
|-
| 15
| Scrollbar Inverse Foreground
|-
| 16
| Scrollbar Inverse Background
|-
| 17
| Scrollbar Dead Area
|-
| 18
| Selection Bar Foreground
|-
| 19
| Selection Bar Background
|-
| 20
| Inactive Selection Bar Foreground
|-
| 21
| Inactive Selection Bar Background
|-
| 22
| Alternating Item Background
|-
| 23
| Alternating Item Foreground
|}

====GetPlaylistColor()====
The Skin.GetPlaylistColor() method is used to retrieve color information regarding different Playlist UI elements.

Prototype:
GetPlaylistColor(playlistcolornumber);
where:
'''playlistcolornumber''' = (integer) a number in the range 0-5 identifying the Playlist's UI
element for which the color should be returned.

Example:
var normalBgColor = window.external.Skin.GetPlaylistColor(2);

Return value:
The HTML color constant used for the specified Playlist UI element.

====Playlist Color Numbers====
{| border="1"
|-
! Number
! Description
|-
| 0
| Normal
|-
| 1
| Current
|-
| 2
| Normal Background
|-
| 3
| Selected Background
|-
| 4
| Video Window Status Bar Foreground
|-
| 5
| Video Window Status Bar Background
|}

====GetSkinColor()====
The Skin.GetSkinColor() method is used to retrieve color information regarding different Playlist UI elements.

Prototype:
GetSkinColor(skincolorname);
where:
'''skincolorname''' = (string) identifying the Skin's UI
element for which the color should be returned.

Example:
var buttonTextColor = window.external.Skin.GetSkinColor("wasabi.button.text");

Return value:
The HTML color constant used for the specified Playlist UI element.

====Skin Color Names====
{| border="1"
|-
! Name
! Description
|-
|"wasabi.list.item.selected.fg"
|Selected item text foreground color
|-
|"wasabi.list.column.separator"
|Color of line between columns
|-
|'''Item Lists, Lists with playable items'''
|
|-
|"wasabi.itemlist.outline.current"
|Currently playing outline color
|-
|"wasabi.itemlist.outline.focus"
|Focused item dashed outline color
|-
|"wasabi.itemlist.selborder"
|
|-
|'''Message box'''
|
|-
|"wasabi.msgBox.background"
|Messagebox background color
|-
|"wasabi.textBar.text"
|Text object & message box text color
|-
|"wasabi.textBar.background"
|Text object & message box text background color
|-
|'''Buttons'''
|
|-
|"wasabi.button.text"
|Buttons text color
|-
|"wasabi.button.hiliteText"
|Buttons hilite text color, used by tab windows
|-
|"wasabi.button.dimmedText"
|Buttons dimmed text color, when disabled
|-
|'''Popup menus'''
|
|-
|"wasabi.popup.text"
|Menu items text color
|-
|"wasabi.popup.hiliteText"
|Hilited item text color
|-
|"wasabi.popup.dimmedText"
|Disabled item text color
|-
|'''Components'''
|
|-
|"wasabi.component.title.foreground"
|Old title bar text color when using TTF
|-
|"wasabi.component.title.border"
|Old title bar text outline when using TTF
|-
|'''Labeled Windows'''
|
|-
|"wasabi.labelwnd.foreground"
|Text foreground color
|-
|"wasabi.labelwnd.background"
|Text drop shadow color
|-
|'''Edit Windows'''
|
|-
|"wasabi.edit.selection"
|Selected text
|-
|"wasabi.edit.text"
|Text
|-
|"wasabi.edit.background"
|Text background
|-
|
|
|-
| "wasabi.text.color"
|
|-
| "wasabi.text.color.inverse"
|
|}

===Properties===
====string name (test)====
The Skin.name property gives access to the name of skin currently in use. Changing this value will change the skin displayed for the player.

====string font (read only)====
The Skin.font property provides the font name currently used in the player.

====string fontsize (read only)====
The Skin.fontsize property provides the size of the font currently used in the player.

== Metadata tag names ==

When retrieving metadata through Winamp, a freeform string is passed. The popular file formats (MP3, WMA, FLAC, M4A) will respond uniformly to a common base of strings. However, each file format is idiosyncratic in how metadata is stored. Some file types will respond to additional strings which are not documented here.

Remember that the metadata is only as good as the tagging in the file itself. A poorly tagged track will return poor metadata.

Common metadata tags
bitrate
length
type
title
artist
albumartist
album
genre
year
disc
publisher
comment
track
composer
conductor

Beginner's Basic Plugin Guide

2009-06-25T21:05:03Z

SMonty: /* Testing the plugin */

So you want to write a plugin for Winamp but don't know where to start? This is the page for you. We'll walk you through creating a very basic plugin that does '''nothing'''. You can then expand on the code to do whatever you want.

==Notes==
This guide assumes you're developing using Visual Studio in a Windows environment. It also assumes you have some familiarity with programming. For people that don't, try using google. We'll have to expand this guide in the future to give out more pointers.

== Basic credits ==
The following code has been created based on samples from [http://forums.winamp.com/showthread.php?s=&threadid=128915 several] [http://forums.winamp.com/showthread.php?s=&threadid=82651 forum] [http://forums.winamp.com/showthread.php?s=&threadid=103667 threads]. Many thanks go out to forum members Kaboon, kichik, baafie, burek021, and bananskib for their code examples and advice.

== What you need ==
To begin, you'll need a tool that lets you write code. Check out the [[Plug-in_Developer#Tools|Tools]] page. You can get a free copy of Visual Studio C++ Express [http://www.microsoft.com/Express/ here]. You'll probably also want a copy of Winamp itself, to test your plugin; you can get that on the Winamp site [http://www.winamp.com/player here].

# Download [http://www.microsoft.com/Express/ Visual C++ Express].
# Double-click the file (it's probably called something like 'vcsetup.exe') and run the installer.
# You're practically good to go!

== Creating a project ==
The first thing we need to do is create a place to store our code. In Visual Studio this is called a 'project'.

# Launch Visual Studio by clicking Start -> Programs -> Microsoft Visual C++ Express Edition -> Microsoft Visual C++ Express Edition
# When Visual Studio opens, select File -> New -> Project
# For creating Winamp plugins, we want to create code that compiles into a .dll, which Visual Studio 2008 refers to as a "Class Library". So in the 'New Project' window select Visual C++ -> CLR -> Class Library.
# Give your project a name (see below) and select a location.

'''Note:''' Winamp classifies plugins based on the first part of their .dll filename, so you will need to properly name the file if you want Winamp to recognize it (TODO: can someone confirm this?! CONFIRMED, the Winamp client searches for and loads plugins based on the first part of their filenames. This saves time and space instead of loading all dlls and then detecting which ones are real plugins). Thus, to make our basic plugin we want to name the first part of the file 'gen_'. '''Be sure to start your plugin name with 'gen_' to make it work properly.'''

All of the examples in this guide will assume you named your plugin 'gen_myplugin', but you can call it whatever you like as long as it starts with 'gen_' (for generic plugin) and ends with '.dll'.

Once you click okay Visual Studio should create a bunch of boilerplate code for you, and throw some files in your project with names like "resource.h", "stdafx.h", "AssemblyInfo.cpp", and so on. The main files we want to work with are called 'gen_myplugin.h' and 'gen_myplugin.cpp'. If you double-click to view them you should see code that looks something like this:

<nowiki><contents of gen_myplugin.h></nowiki>
<source lang="cpp">
// gen_myplugin.h

#pragma once

using namespace System;

namespace gen_myplugin {

public ref class Class1
{
// TODO: Add your methods for this class here.
};
}
</source>
<nowiki><end contents of gen_myplugin.h></nowiki>

<nowiki><contents of gen_myplugin.cpp></nowiki>
<source lang="cpp">
// This is the main DLL file.

#include "stdafx.h"

#include "gen_myplugin.h"

</source>
<nowiki><end contents of gen_myplugin.cpp></nowiki>

We want to edit these files to make a basic plugin.

== Creating a basic plugin ==

=== Basic plugin code ===
To create your plugin, just copy/paste the following code into gen_myplugin.h and gen_myplugin.cpp.

<nowiki><basic gen_myplugin.h></nowiki>
<source lang="cpp">

#ifndef gen_myplugin_h
//---------------------------------------------------------------------------
#define gen_myplugin_h
#include <windows.h>

// plugin version (don't touch this)
#define GPPHDR_VER 0x10

// plugin name/title (change this to something you like)
#define GPPHDR_NAME "My first generic Winamp plugin!"

// main structure with plugin information, version, name...
typedef struct {
int version; // version of the plugin, defined in "gen_empty.h"
char *description; // name/title of the plugin, defined in "gen_empty.h"
int (*init)(); // function which will be executed on init event
void (*config)(); // function which will be executed on config event
void (*quit)(); // function which will be executed on quit event
HWND hwndParent; // (?)
HINSTANCE hDllInstance; // (?)
} winampGeneralPurposePlugin;

extern winampGeneralPurposePlugin *gen_plugins[256];
typedef winampGeneralPurposePlugin * (*winampGeneralPurposePluginGetter)();

#endif
</source>
<nowiki><end basic gen_myplugin.h></nowiki>

<nowiki><basic gen_myplugin.cpp></nowiki>
<source lang="cpp">
/*

Winamp generic plugin template code.
This code should be just the basics needed to get a plugin up and running.
You can then expand the code to build your own plugin.

Updated details compiled June 2009 by culix, based on the excellent code examples
and advice of forum members Kaboon, kichik, baafie, burek021, and bananskib.
Thanks for the help everyone!

*/

#include "stdafx.h"
#include <windows.h>
#include "gen_myplugin.h"

// these are callback functions/events which will be called by Winamp
int init(void);
void config(void);
void quit(void);

// this structure contains plugin information, version, name...
winampGeneralPurposePlugin plugin = {
GPPHDR_VER, // version of the plugin, defined in "gen_myplugin.h"
GPPHDR_NAME, // name/title of the plugin, defined in "gen_myplugin.h"
init, // function name which will be executed on init event
config, // function name which will be executed on config event
quit, // function name which will be executed on quit event
};

// event functions follow

int init() {
//A basic messagebox that tells you the 'init' event has been triggered.
//If everything works you should see this message when you start Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Init event triggered for gen_myplugin. Plugin installed successfully!", L"", MB_OK);
return 0;
}

void config() {
//A basic messagebox that tells you the 'config' event has been triggered.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Config event triggered for gen_myplugin.", L"", MB_OK);
}

void quit() {
//A basic messagebox that tells you the 'quit' event has been triggered.
//If everything works you should see this message when you quit Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(0, L"Quit event triggered for gen_myplugin.", L"", MB_OK);
}

// This is an export function called by winamp which returns this plugin info.
// We wrap the code in 'extern "C"' to ensure the export isn't mangled if used in a CPP file.
extern "C" __declspec(dllexport) winampGeneralPurposePlugin * winampGetGeneralPurposePlugin() {
return &plugin;
}
</source>
<nowiki><end basic gen_myplugin.cpp></nowiki>

=== Edit dependencies ===

By default Visual Studio removes some files we need to compile our code. Let's add those back in:

# Right-click on your project (the folder called 'gen_myplugin' in the Solution Explorer window on the left) and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)', so the box is blank.
# Click 'Apply', then 'OK', and then save your project.

=== Compiling the code ===

Once you have pasted this code into your .h and .cpp files, save your changes and compile the project. You can do this by pressing F7, or selecting Build -> Build Solution. If everything works, you should see some messages in Visual Studio's 'Output' window, with the final line saying something like

"========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped =========="

If so, congratulations! You have built your first plugin :) If instead you get an error message, please see the [[Beginner's Basic Plugin Guide#Troubleshooting|Troubleshooting]] section below.

=== Testing the plugin ===

If your project builds successfully, it will output a file called 'gen_myplugin.dll' into a 'Debug' or 'Release' folder in the same location you created your project. Look for that file now. We want to copy this file to C:\Program Files\Winamp\Plugins\, which is the folder Winamp examines to find all of its plugins.

# Copy your plugin .dll file into C:\Program Files\Winamp\Plugins\
# Close and re-open Winamp. If your plugin is installed correctly, you should see a popup window with the Init message you typed inside gen_myplugin.cpp. If so, congrats! Your plugin works.
# You can check to see your plugin name by clicking Options -> Preferences -> Plugins -> General purpose. Your plugin name should appear in that window.
# Click on your plugin to hilight it and then select the 'Configure Selected Plugin' button. This should cause the 'config' message to appear.
# If you exit Winamp, you should now see the Quit message pop up as the program exits.

== What's next? ==

So what's next? We don't know. More guides still need to be written. Eventually there may be a guide for each type of plugin: [[Input_Plugin|Input]], [[Output_Plugin|Output]], [[Visualization_Plugin|Visualization]], [[DSP_Plugin|Audio Effect/DSP]], [[General_Purpose_Plugin|General Purpose]], [[Media_Library_Plugin|Media Library]] and [[Portable_Plugin|Portables]].

If you're looking to write a plugin, you may want to start by reading through the [[SDK_Contents]] and trying to find a code example that's similar to what you want to do.

----

== Troubleshooting ==
* '''I get an error message that looks like:'''

<pre>
1>winamp_imms.obj : error LNK2028: unresolved token (0A00001D) "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)

1>winamp_imms.obj : error LNK2019: unresolved external symbol "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)
</pre>

:'''Answer:''' By default Visual Studio Express 2008 doesn't include some files you need in the linker. For example, with our basic code we include windows.h, which is part of user32.dll. However, there is usually a '$(NoInherit)' command in our linker options that tell us not to include user32.dll. To fix this, try the following:

# Right-click on your project and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)'.
# Save and recompile

For more information see [http://stackoverflow.com/questions/739952/c-cli-linker-gives-unresolved-token-for-win32-function here] and [http://stackoverflow.com/questions/721387/i-get-lnk2028-when-trying-to-wrap-native-c-class-using-managed-c here].

* '''* I get an error like'''
<pre>
"1>.\winamp_imms.cpp(29) : error C2146: syntax error : missing ';' before identifier 'plugin'"
</pre>

:'''Answer:''' This could be a namespace error. On this line

<source lang="cpp">
winampGeneralPurposePlugin plugin = {
</source>

we are creating a variable called 'plugin'. The variable's type, rather than being an integer ('int'), floating point number ('float'), or some other type, is of type 'winampGeneralPurposePlugin', which is a type we have created. This type is created in the header file with the code

<source lang="cpp">
typedef struct {
int version;
char *description;
int (*init)();
void (*config)();
void (*quit)();
HWND hwndParent;
HINSTANCE hDllInstance;
} winampGeneralPurposePlugin;
</source>

If you used Visual Studio's auto-generated code, you might have a line that looks like this:

<source lang="cpp">
namespace myplugin {
</source>

this line is telling Visual Studio to put everything inside the 'myplugin' namespace (read up on namespaces [http://en.wikipedia.org/wiki/Namespace here]). We get rid of the default boilerplate code, including the namespace, to make everything work.

Alternatively, you can change the declaration of the 'plugin' variable to say

<source lang="cpp">
myplugin::winampGeneralPurposePlugin plugin = {
</source>

This tells Visual Studio where to look for the winampGeneralPurposePlugin type (i.e., to look inside the 'myplugin' namespace). If you are new to programming or plugin creation, however, you probably don't need (or want) to mess with namespaces.

* '''I get an error like'''

<pre>
1>.\winamp_imms.cpp(41) : error C2664: 'MessageBox' : cannot convert parameter 2 from 'const char [5]' to 'LPCTSTR'
1> Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or function-style cast
</pre>

:'''Answer:''' You need to change the string you pass to the MessageBox function to be of the right type. See the MSDN FAQ entry [http://social.msdn.microsoft.com/Forums/en-US/vclanguage/thread/c1b08c0a-a803-41c3-ac8c-84eba3be1ddb here]. You can most likely fix this by putting a capital 'L' in front of the string.

e.g. change <source lang="cpp">MessageBox(plugin.hwndParent, "Somestring", "", MB_OK);</source> to <source lang="cpp">MessageBox(plugin.hwndParent, L"Somestring", L"", MB_OK);</source>

TODO: What's the right way of doing this for plugins?

* '''My plugin isn't working / My plugin doesn't show up in the Preferences menu.'''

:'''Answer:'''Did you name your plugin with the correct prefix, such as 'gen_myplugin'? If not it may not show up in the window.

TODO: How about other names/plugins? What's the real answer?

[[Category:Articles]]

Beginner's Basic Plugin Guide

2009-06-25T20:42:16Z

SMonty: /* Creating a project */

So you want to write a plugin for Winamp but don't know where to start? This is the page for you. We'll walk you through creating a very basic plugin that does '''nothing'''. You can then expand on the code to do whatever you want.

==Notes==
This guide assumes you're developing using Visual Studio in a Windows environment. It also assumes you have some familiarity with programming. For people that don't, try using google. We'll have to expand this guide in the future to give out more pointers.

== Basic credits ==
The following code has been created based on samples from [http://forums.winamp.com/showthread.php?s=&threadid=128915 several] [http://forums.winamp.com/showthread.php?s=&threadid=82651 forum] [http://forums.winamp.com/showthread.php?s=&threadid=103667 threads]. Many thanks go out to forum members Kaboon, kichik, baafie, burek021, and bananskib for their code examples and advice.

== What you need ==
To begin, you'll need a tool that lets you write code. Check out the [[Plug-in_Developer#Tools|Tools]] page. You can get a free copy of Visual Studio C++ Express [http://www.microsoft.com/Express/ here]. You'll probably also want a copy of Winamp itself, to test your plugin; you can get that on the Winamp site [http://www.winamp.com/player here].

# Download [http://www.microsoft.com/Express/ Visual C++ Express].
# Double-click the file (it's probably called something like 'vcsetup.exe') and run the installer.
# You're practically good to go!

== Creating a project ==
The first thing we need to do is create a place to store our code. In Visual Studio this is called a 'project'.

# Launch Visual Studio by clicking Start -> Programs -> Microsoft Visual C++ Express Edition -> Microsoft Visual C++ Express Edition
# When Visual Studio opens, select File -> New -> Project
# For creating Winamp plugins, we want to create code that compiles into a .dll, which Visual Studio 2008 refers to as a "Class Library". So in the 'New Project' window select Visual C++ -> CLR -> Class Library.
# Give your project a name (see below) and select a location.

'''Note:''' Winamp classifies plugins based on the first part of their .dll filename, so you will need to properly name the file if you want Winamp to recognize it (TODO: can someone confirm this?! CONFIRMED, the Winamp client searches for and loads plugins based on the first part of their filenames. This saves time and space instead of loading all dlls and then detecting which ones are real plugins). Thus, to make our basic plugin we want to name the first part of the file 'gen_'. '''Be sure to start your plugin name with 'gen_' to make it work properly.'''

All of the examples in this guide will assume you named your plugin 'gen_myplugin', but you can call it whatever you like as long as it starts with 'gen_' (for generic plugin) and ends with '.dll'.

Once you click okay Visual Studio should create a bunch of boilerplate code for you, and throw some files in your project with names like "resource.h", "stdafx.h", "AssemblyInfo.cpp", and so on. The main files we want to work with are called 'gen_myplugin.h' and 'gen_myplugin.cpp'. If you double-click to view them you should see code that looks something like this:

<nowiki><contents of gen_myplugin.h></nowiki>
<source lang="cpp">
// gen_myplugin.h

#pragma once

using namespace System;

namespace gen_myplugin {

public ref class Class1
{
// TODO: Add your methods for this class here.
};
}
</source>
<nowiki><end contents of gen_myplugin.h></nowiki>

<nowiki><contents of gen_myplugin.cpp></nowiki>
<source lang="cpp">
// This is the main DLL file.

#include "stdafx.h"

#include "gen_myplugin.h"

</source>
<nowiki><end contents of gen_myplugin.cpp></nowiki>

We want to edit these files to make a basic plugin.

== Creating a basic plugin ==

=== Basic plugin code ===
To create your plugin, just copy/paste the following code into gen_myplugin.h and gen_myplugin.cpp.

<nowiki><basic gen_myplugin.h></nowiki>
<source lang="cpp">

#ifndef gen_myplugin_h
//---------------------------------------------------------------------------
#define gen_myplugin_h
#include <windows.h>

// plugin version (don't touch this)
#define GPPHDR_VER 0x10

// plugin name/title (change this to something you like)
#define GPPHDR_NAME "My first generic Winamp plugin!"

// main structure with plugin information, version, name...
typedef struct {
int version; // version of the plugin, defined in "gen_empty.h"
char *description; // name/title of the plugin, defined in "gen_empty.h"
int (*init)(); // function which will be executed on init event
void (*config)(); // function which will be executed on config event
void (*quit)(); // function which will be executed on quit event
HWND hwndParent; // (?)
HINSTANCE hDllInstance; // (?)
} winampGeneralPurposePlugin;

extern winampGeneralPurposePlugin *gen_plugins[256];
typedef winampGeneralPurposePlugin * (*winampGeneralPurposePluginGetter)();

#endif
</source>
<nowiki><end basic gen_myplugin.h></nowiki>

<nowiki><basic gen_myplugin.cpp></nowiki>
<source lang="cpp">
/*

Winamp generic plugin template code.
This code should be just the basics needed to get a plugin up and running.
You can then expand the code to build your own plugin.

Updated details compiled June 2009 by culix, based on the excellent code examples
and advice of forum members Kaboon, kichik, baafie, burek021, and bananskib.
Thanks for the help everyone!

*/

#include "stdafx.h"
#include <windows.h>
#include "gen_myplugin.h"

// these are callback functions/events which will be called by Winamp
int init(void);
void config(void);
void quit(void);

// this structure contains plugin information, version, name...
winampGeneralPurposePlugin plugin = {
GPPHDR_VER, // version of the plugin, defined in "gen_myplugin.h"
GPPHDR_NAME, // name/title of the plugin, defined in "gen_myplugin.h"
init, // function name which will be executed on init event
config, // function name which will be executed on config event
quit, // function name which will be executed on quit event
};

// event functions follow

int init() {
//A basic messagebox that tells you the 'init' event has been triggered.
//If everything works you should see this message when you start Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Init event triggered for gen_myplugin. Plugin installed successfully!", L"", MB_OK);
return 0;
}

void config() {
//A basic messagebox that tells you the 'config' event has been triggered.
//You can change this later to do whatever you want (including nothing)
MessageBox(plugin.hwndParent, L"Config event triggered for gen_myplugin.", L"", MB_OK);
}

void quit() {
//A basic messagebox that tells you the 'quit' event has been triggered.
//If everything works you should see this message when you quit Winamp once your plugin has been installed.
//You can change this later to do whatever you want (including nothing)
MessageBox(0, L"Quit event triggered for gen_myplugin.", L"", MB_OK);
}

// This is an export function called by winamp which returns this plugin info.
// We wrap the code in 'extern "C"' to ensure the export isn't mangled if used in a CPP file.
extern "C" __declspec(dllexport) winampGeneralPurposePlugin * winampGetGeneralPurposePlugin() {
return &plugin;
}
</source>
<nowiki><end basic gen_myplugin.cpp></nowiki>

=== Edit dependencies ===

By default Visual Studio removes some files we need to compile our code. Let's add those back in:

# Right-click on your project (the folder called 'gen_myplugin' in the Solution Explorer window on the left) and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)', so the box is blank.
# Click 'Apply', then 'OK', and then save your project.

=== Compiling the code ===

Once you have pasted this code into your .h and .cpp files, save your changes and compile the project. You can do this by pressing F7, or selecting Build -> Build Solution. If everything works, you should see some messages in Visual Studio's 'Output' window, with the final line saying something like

"========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped =========="

If so, congratulations! You have built your first plugin :) If instead you get an error message, please see the [[Beginner's Basic Plugin Guide#Troubleshooting|Troubleshooting]] section below.

=== Testing the plugin ===

If your project builds successfully, it will output a file called 'gen_myplugin.dll' into a 'Debug' or 'Release' folder in the same location you created your project. Look for that file now. We want to copy this file to C:\Program Files\Winamp\Plugins\, which is the folder Winamp examines to find all of its plugins.

# Copy your plugin .dll file into C:\Program Files\Winamp\Plugins\
# Close and re-open Winamp. If your plugin is installed correctly, you should see a popup window with the Init message you typed inside gen_myplugin.cpp. If so, congrats! Your plugin works.
# You can check to see your plugin name by clicking Options -> Preferences -> Plugins -> General purpose. Your plugin name should appear in that window.

If you exit Winamp, you should now also see a Quit message pop up when the program exits.

== What's next? ==

So what's next? We don't know. More guides still need to be written. Eventually there may be a guide for each type of plugin: [[Input_Plugin|Input]], [[Output_Plugin|Output]], [[Visualization_Plugin|Visualization]], [[DSP_Plugin|Audio Effect/DSP]], [[General_Purpose_Plugin|General Purpose]], [[Media_Library_Plugin|Media Library]] and [[Portable_Plugin|Portables]].

If you're looking to write a plugin, you may want to start by reading through the [[SDK_Contents]] and trying to find a code example that's similar to what you want to do.

----

== Troubleshooting ==
* '''I get an error message that looks like:'''

<pre>
1>winamp_imms.obj : error LNK2028: unresolved token (0A00001D) "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)

1>winamp_imms.obj : error LNK2019: unresolved external symbol "extern "C" int __stdcall
MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function "extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)"
(?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)
</pre>

:'''Answer:''' By default Visual Studio Express 2008 doesn't include some files you need in the linker. For example, with our basic code we include windows.h, which is part of user32.dll. However, there is usually a '$(NoInherit)' command in our linker options that tell us not to include user32.dll. To fix this, try the following:

# Right-click on your project and select Properties
# Expand the options to select Configuration Properties -> Linker -> Input
# In the "Additional Dependancies" box, delete the text that says '$(NoInherit)'.
# Save and recompile

For more information see [http://stackoverflow.com/questions/739952/c-cli-linker-gives-unresolved-token-for-win32-function here] and [http://stackoverflow.com/questions/721387/i-get-lnk2028-when-trying-to-wrap-native-c-class-using-managed-c here].

* '''* I get an error like'''
<pre>
"1>.\winamp_imms.cpp(29) : error C2146: syntax error : missing ';' before identifier 'plugin'"
</pre>

:'''Answer:''' This could be a namespace error. On this line

<source lang="cpp">
winampGeneralPurposePlugin plugin = {
</source>

we are creating a variable called 'plugin'. The variable's type, rather than being an integer ('int'), floating point number ('float'), or some other type, is of type 'winampGeneralPurposePlugin', which is a type we have created. This type is created in the header file with the code

<source lang="cpp">
typedef struct {
int version;
char *description;
int (*init)();
void (*config)();
void (*quit)();
HWND hwndParent;
HINSTANCE hDllInstance;
} winampGeneralPurposePlugin;
</source>

If you used Visual Studio's auto-generated code, you might have a line that looks like this:

<source lang="cpp">
namespace myplugin {
</source>

this line is telling Visual Studio to put everything inside the 'myplugin' namespace (read up on namespaces [http://en.wikipedia.org/wiki/Namespace here]). We get rid of the default boilerplate code, including the namespace, to make everything work.

Alternatively, you can change the declaration of the 'plugin' variable to say

<source lang="cpp">
myplugin::winampGeneralPurposePlugin plugin = {
</source>

This tells Visual Studio where to look for the winampGeneralPurposePlugin type (i.e., to look inside the 'myplugin' namespace). If you are new to programming or plugin creation, however, you probably don't need (or want) to mess with namespaces.

* '''I get an error like'''

<pre>
1>.\winamp_imms.cpp(41) : error C2664: 'MessageBox' : cannot convert parameter 2 from 'const char [5]' to 'LPCTSTR'
1> Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or function-style cast
</pre>

:'''Answer:''' You need to change the string you pass to the MessageBox function to be of the right type. See the MSDN FAQ entry [http://social.msdn.microsoft.com/Forums/en-US/vclanguage/thread/c1b08c0a-a803-41c3-ac8c-84eba3be1ddb here]. You can most likely fix this by putting a capital 'L' in front of the string.

e.g. change <source lang="cpp">MessageBox(plugin.hwndParent, "Somestring", "", MB_OK);</source> to <source lang="cpp">MessageBox(plugin.hwndParent, L"Somestring", L"", MB_OK);</source>

TODO: What's the right way of doing this for plugins?

* '''My plugin isn't working / My plugin doesn't show up in the Preferences menu.'''

:'''Answer:'''Did you name your plugin with the correct prefix, such as 'gen_myplugin'? If not it may not show up in the window.

TODO: How about other names/plugins? What's the real answer?

[[Category:Articles]]

Online Service Security Prompts

2009-01-22T15:48:07Z

SMonty: New page: '''Breadcrumb''' -- Wiki Main : Skin Developer : Visual Developer : Plug-in Developer : Online Service Developer : Articles Page : [[Developers F...

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Online Service Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Category:Winamp]]
==Winamp Online Services Security==

Winamp Online Services is a powerful new way for web developers to create engaging content for millions of Winamp users. However, with great power comes great responsibility. Since online services have access to more information from the Winamp client than an ordinary web page, it is very important that we provide some mechanism to provide security for the users.

There are certain activities that online services can perform that are not considered a security risk For example, examining the current position of a song being played. However, for others a security dialog will be presented whenever a service tries to perform the action for the first time.

===Security Dialog Prompts===

Security prompts contain a description of the action being attempted, an indication as to what API the action belongs, allow and deny buttons as well as a checkbox.

Replies, either Allow or Deny, to security prompts are saved for each online service.

====Allow====
Allows the online service to perform the action. It will also automatically ALLOW other, related actions. The list below will identify which actions are related.

====Deny====
Does NOT allow the online service to perform the action. It will also automatically DENY other related actions.

====Use this response for all security requests for this service====
When this checkbox is checked, the choice (Allow or Deny) will be used as the response to all subsequent security prompts for this service. This is a quick way to indicate that a particular online service should be allowed or denied (depending on the button pressed) to perform all actions.

===Grouping APIs by Security Prompt===

The following APIs and methods will cause a security prompt to appear the first time each service attempts to invoke them. Security responses for each message will then be used automatically for the other api methods listed.:
====This service is trying to control playback====
*API: Transport
*Methods: Prev(), Play(), Stop(), Pause(), Next()
*Description: The online service is attempting to Play, Stop, Pause, Jump to the previous track, or Jump to the next track.

====This service is trying to monitor playback events====
*API: Transport
*Methods: RegisterForEvents()
*Description: The online service is requesting to be notified when playback events occur. The possible events are Play, Pause, Stop, End of File. Note these events will occur whether initiated from scripts or from the user clicking on the buttons themselves. Some events carry additional information:
**Play provides the filename/URL of the asset being played.
**Stop provides the current position where playback was halted. End of File indicates that the end of the asset has been reached.
**Pause provides a flag indicating whether the player was paused or unpaused.
**End of File happens at the end of an asset before the next one is played.

====This service is trying to get information about the currently playing song====
*API: Transport
*Methods: GetMetadata()
*Description: The online service is requesting "Metadata" information from the current asset. "Metadata" is additional information that MAY be part of the asset, such as author or title, that is not actually part of the song itself. The existence of metadata depends on the format of the data and whether it was added when the asset was digitized.

====This service is trying to access your active playlist====
*API: PlayQueue
*Methods: Play(), Enqueue(), Insert(), ClearQueue()
*Description: The online service is trying to alter the Play Queue. It may be trying to play a single asset, add assets to the queue or clear the queue.

====This service is trying to get information about an item in your Play Queue.====
*API: PlayQueue
*Methods: GetMetadata(), GetTitle(), GetURL()
*Description: The service is trying to gather information about an asset within the play queue.

====This service is trying to access the playlists in your media library====
*API: PlayLists
*Methods: GetPlaylists(), OpenPlaylist(), SavePlaylist()
*Description: The online service is trying to obtain a list of all Winamp playlists known to your Winamp client. It may also be trying to open a playlist to manipulate the assets within or it may be trying to save a modified playlist.

====This service is trying to access your bookmarks====
*API: Bookmarks:
*Methods: Add()
*Description: The online service is trying to create a bookmark in your Media Library Bookmarks.

====This service is trying to subscribe you to a podcast====
*API: Podcasts
*Methods: Add()
*Description: The online service is trying to subscribe to a podcast and add an entry in your Media Library Podcasts

====This service is trying to provide metadata to Winamp====
*API: MediaCore
*Methods: AddMetadataHook()
*Description: The online service is trying to add metadata for an asset. This might be useful if the online service can provide better metadata than comes as part of the asset itself.

====This service is trying to access information about media supported by Winamp.====
*API: MediaCore
*Methods: isRegisteredExtension()
*Description: The service is trying to determine if the Winamp client supports a certain encoding formation, for example "mp3".

====This service is trying to access information about media on your computer.====
*API: MediaCore
*Methods: GetMetadata()
*Description: The online service is attempting to get metadata from an asset.

====This service is trying to access your playback history====
*API: History
*Methods: Query()
*Description: The Winamp History is a collection of information about the assets you play, how many times they were played and when was the last time they were played. It is used to determine what the users favorite songs are.

====This service is trying to launch a website in the browser====
*API: Application
*Methods: LaunchURL()
*Description: The online service is trying to launch a new web site in the browser. The browser may be internal to Winamp, which means it could be an online service or it could be launched in an external browser where it does not benefit from the online services api calls.

====This service is trying to access information about Winamp====
*API: Application
*Properties: version, versionstring, language, languagepack
*Description: The online service is trying to gather information regarding the version of Winamp or the language pack that is being used by Winamp.

====This service is trying to access your skin settings====
*API: Skins
*Methods: GetClassicColor(), GetPlaylistColor(), GetSkinColor()
*Description: The online service is trying to obtain information regarding the current skin used by the Winamp client. This could be used to sychronize the colors of the service with that of the Winamp player.

Complete JavaScript API technology framework

2009-01-22T15:38:19Z

SMonty: New page: '''Breadcrumb''' -- Wiki Main : Skin Developer : Visual Developer : Plug-in Developer : Online Service Developer : Articles Page : [[Developers F...

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Online Service Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Main_Page#Glossary_of_Terms|Glossary]]
[[Category:Winamp]]

==Overview==
The purpose of the Winamp Online Service API is to allow Winamp Online Services to interact with the Winamp client in order to provide service developers with a way to create custom experiences for their users based on the power of Winamp. The overall idea is to include exceptional web sites within Winamp Online Services.

The Winamp Online Service API is made up of methods that can be called from scripts within web pages rendered by the Winamp client. The API can be invoked using any scripting language supported by the Microsoft Internet Explorer web browser (5.5 and above). For simplicity, examples in this document will use JavaScript.

==Setup==
The Winamp Online Services API is designed to allow web pages, hosted (displayed) within the embedded browser of the Winamp client, to access the functionality of the client. There are several steps necessary to allow this to take place.

#Make sure you have the latest version of the Winamp client that supports online services.
#Make sure you have the latest version of the ml_webdev plugin (ml_webdev.dll). The presence of this plugin will create a "Web Dev Test Platform" within the Medial Library pane.
#In order to change the starting web page for the online service, start the Winamp client and configure the plugin.
##Select Options->Preferences->Plug-ins->Media Library.
##Select "API 2 Test Platform" and press "Configure selected plugin".
##On the Web Dev Preferences dialog, set the URL field to the URL of the initial web page for the online service. For example, <nowiki>file://c:\myonlineservice\webdev.html</nowiki>
#Click on "Web Dev Test Platform" in the Media Library. You may have to right click and choose refresh to see the new web page.

You should now see the initial page of your online service in the Winamp embedded browser.

==window.external==
The Winamp JavaScript API can be accessed through the window.external object in the Document Object Model (DOM) exposed by the IE browser control embedded within the Winamp client. The API methods can only be accessed thru the Winamp client and are not available if the web page is displayed outside of the client.

The invocation of all methods follow this form
window.external.'''''API'''''.'''''Method'''''

Properties can also be accessed using a similar form:
window.external.'''''API'''''.'''''Property'''''

Where ''API'' is a singleton class that defines a group of related methods (i.e., functionality). For example, Transport (Stop, Play, Next, etc) which controls the "buttons" of the Winamp player.

''Method'' is a function you can call as part of a particular API. For example the following call will stop the Winamp client:
window.external.Transport.Stop();

''Property'' is an internal variable for the particular API that can be queried and in some cases set. For example the following will provide access to the Winamp client shuffle "button":
var shuffle = window.external.Transport.shuffle; // gets the current state
OR
window.external.Transport.shuffle = true; // turns on shuffle

See the documentation on each API below for a complete list of methods and properties.



== Transport API ==
The Transport API is used to control the Winamp client. "Transport controls" was the name given to the buttons on the front panel that controlled hardware devices. This name is used in Winamp for the same purpose. It is also used to access information about the currently playing song.

The Transport API can also be used to register for events involved with asset playback. See the section [[#Transport Events API|Transport Events API]].

===Methods===
====Prev()====
Transport.Prev() can be used to press the "Previous Track" button on the Winamp player. Invoking Prev() while an asset is already playing will cause the previous asset to begin playback immediately. Invoking Prev() while the player is stopped will cause the previous asset to play next time playback starts.

Prototype:
bool Prev();
Example:
var rc = window.external.Transport.Prev();
Return Value:
A boolean value indicating whether the request was successful.

====Play()====
Transport.Play() can be used to press the "Play" button on the Winamp player. Invoking Play() on an asset already playing will cause the asset to restart playback. Pressing Play() on a paused asset will cause it to begin playing from its current position.

Prototype:
bool Play();
Example:
var rc = window.external.Transport.Play();
Return Value:
A boolean value indicating whether the request was successful.

====Pause()====
Transport.Pause() can be used to press the "Pause" button on the Winamp player. Issuing Pause() again, or Play() will cause the asset to continue to play from the location where it was paused.

Prototype:
bool Pause();
Example:
var rc = window.external.Transport.Pause();
Return Value:
A boolean value indicating whether the request was successful.

====Stop()====
Transport.Stop() can be used to press the "Stop" button on the Winamp player.

Prototype:
bool Stop();
Example:
var rc = window.external.Transport.Stop();
Return Value:
A boolean value indicating whether the request was successful.
====Next()====
Transport.Next() can be used to press the "Next Track" button on the Winamp player. Invoking Next() while the player is stopped will cause the next asset to play next time playback starts.

Prototype:
bool Next();
Example:
var rc = window.external.Transport.Next();
Return Value:
A boolean value indicating whether the request was successful.

====GetMetadata()====
Transport.GetMetadata() can be used to fetch metadata for the currently playing asset. The "tag" parameter is specific to different asset encoding formats so a knowledge of the metadata field names is necessary to request specific data about an asset. Some field names are common but others are specific to the encoding format of the asset.

Prototype:
string GetMetadata(tag);
where:
'''tag''' = (string) identifier for the metadata to be returned.
Example:
var metaStr = window.external.Transport.GetMetadata("artist");
Return Value:
A string value containing the requested metadata.

===Properties===
====bool shuffle====
Transport.shuffle provides access to the Winamp client shuffle "button".

Example:
var isShuffling = window.external.Transport.shuffle; // get shuffle state
window.external.Transport.shuffle = true; // turns on shuffle

====bool repeat====
Transport.repeat provides access to the Winamp client repeat "button".

Example:
var isRepeating = window.external.Transport.repeat; // get repeat state
window.external.Transport.repeat = false; // turns off repeat

====int position====
Transport.position provides access to the position being played within the current asset. Setting this value can change the location where playback occurs. position is in milliseconds.

Example:
var position = window.external.Transport.position; // get position in current track
window.external.Transport.position = 221559; // move playback of the current track
// to the specified position.

====bool playing (read only) ====
Transport.playing indicates whether the Winamp Player is currently playing.

Example:
var isPlaying = window.external.Transport.playing; // is player playing?

====bool paused (read only) ====
Transport.paused indicates whether the Winamp Player has been paused.

Example:
var isPaused = window.external.Transport.paused; // is player paused?

====int length (read only)====
Transport.length provides access to the length in seconds of the track currently playing.

Example:
var length = window.external.Transport.length; // get length of current track in secs

====string url (read only)====
Transport.url provides access to the URL (or filename) of the track currently playing.

Example:
var url = window.external.Transport.url; // get url of current track

====string title (read only)====
Transport.title provides access to the title of the track currently playing.

Example:
var title = window.external.Transport.title; // get title of current track

==Transport Events API==
The Event mechanism of the Transport API allows javascript programmers to specify a callback method that will be invoked whenever certain Transport events take place. An Event object is passed back to the method from which properties can be accessed that provide more information about the event.

===RegisterForEvents()===
The RegisterForEvents() method can be used to specify a JavaScript function that is to be called when any Transport Events occur. An event object is passed that indicates the type of event.

Prototype:
boolean RegisterForEvents(handler);

Example:
var rc = window.external.Transport.RegisterForEvents(EventHandler);

Return value:
boolean value indicating whether the request was successful.

===UnregisterFromEvents()===
The UnregisterFromEvents() method is used to stop receiving notifications about Transport events.

Note: The original handler used in RegisterForEvents() must be passed back into UnregisterFromEvents().

Prototype:
boolean UnregisterFromEvents(handler);

Example:
var rc = window.external.Transport.UnregisterFromEvents(EventHandler);

Return value:
boolean value indicating whether the request was successful.

===Events===
The Transport API Event mechanism requires a JavaScript callback method that accepts a single parameter, a reference to a function. This function will be invoked with an "event" object that will indicate the type of event that occurred as well as contain properties containing more information about the event.

====OnStop====
The OnStop event is triggered when the Winamp client is stopped.

=====properties=====
integer event.position = contains the position within the file where the "Stop" was issued. position is the number of milliseconds from the start of the asset.

====OnPlay====
The OnPlay event is triggered when the Winamp client begins playback. If the client is paused and then restarted by "pressing Play", the OnPause event is triggered rather than an OnPlay event.

=====properties=====
string event.filename = contains the filename/URL of the asset starting playback.

====OnPause====
The OnPause event is triggered when the Winamp client is paused or unpaused. If the client is started after being paused, by "pressing Play", the OnPause event is triggered rather than an OnPlay event.

=====properties=====
boolean event.paused = true (the player was paused), false (the player was unpaused)

====OnEndOfFile====
The OnEndOfFile event is triggered when the player reaches the end of a track.

=====properties=====
None

===Callback function===
The callback function is invoked whenever a Transport event is detected. The callback function is specified in both the RegisterForEvents() and UnregisterFromEvents() methods. The method takes a single parameter, which is loaded with an object identifying the event that occurred.

Example:
function EventHandler(event){
{
if (event.event == "OnStop"){
alert("OnStop: position=" + event.position);
}
else if (event.event == "OnEndOfFile"){
alert("OnEndOfFile");
}
else if (event.event == "OnPause"){
alert("OnPause: paused=" + event.paused);
}
else if (event.event == "OnPlay"){
alert("OnPlay: filename=" + event.filename);
}
else {
alert("Unrecognized Event received");
}
}

== PlayQueue API ==
Provides access to the play queue ("Winamp Playlist"). If you need access to the currently playing song, use the Transport API instead.

Note that the Play Queue is the list of assets that are scheduled to be played by the Winamp client. This is not necessarily the same as a user playlist. Once placed in the play queue, assets can be rearrainged or deleted from the play queue without affecting a user playlist. Individual assets can be placed in the play queue without being contained within a user playlist. Additionally, after adding a playlist to the play queue, changes to the playlist will not affect the assets in the play queue.

===Methods===
====Play()====
The PlayQueue.Play() method stops playback, clears the play queue, enqueues the asset specified by the URL and starts playback. If the URL cannot be found, playback will stop, the play queue will be cleared, the URL (or title and length) will appear in the queue but playback will not be started.

Prototype:
bool Play(URL);
bool Play(URL, title);
bool Play(URL, title, length);
where:
'''URL''' = (string) identifies the location of the asset, for a file that is
local or on an attached network drive this would be the fully
qualified path and filename. For files served from a web server,
it would be the http URL.
'''title''' = (string) used as the title when initially placed in
the play queue.
'''length''' = (integer) used as the length when initially place
in the play queue

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:
var rc = window.extern.PlayQueue.Play("c:\\Winamp\\01 - Hello.mp3",
"My Cool Title",1024);
Return Value:
A boolean value indicating whether the request was successful.

====Enqueue()====
PlayQueue.Enqueue() is used to add an asset to the play queue. The selected asset is added to the bottom of the queue and current playback is not interrupted.

Prototype:
bool Enqueue(URL);
bool Enqueue(URL, title);
bool Enqueue(URL, title, length);
'''URL''' = (string) identifies the location of the asset, for a file that is
local or on an attached network drive this would be the fully
qualified path and filename. For files served from a web server,
it would be the http URL.
'''title''' = (string) used as the title when initially placed in
the play queue.
'''length''' = (integer) used as the length when initially place
in the play queue

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:
var rc = window.extern.PlayQueue.Enqueue("c:\\Winamp\\01 - Hello.mp3",
"My Cool Title",1024);
Return Value:
A boolean value indicating whether the request was successful.

====Insert()====
The PlayQueue.Insert() method can add an asset to the play queue at a specific index.

Prototype:
bool Insert(position, URL);
bool Insert(position, URL, title);
bool Insert(position, URL, title, length);
where:
'''position''' = (integer) a zero based number indicating the location within
the play queue to insert the new asset.
Note: Position is "zero based" so the first entry in the
queue is at position 0.
'''url''' = (string) the URL of the asset to be added
'''title''' = (string) the title to be displayed in the Play Queue.
'''length''' = (integer) the length of the asset to be displayed in
the play queue.

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:
var rc = window.external.PlayQueue.Insert(1, "c:\\mySongs\\mySong.mp3",300);
Return Value:
A boolean value indicating whether the request was successful.

====ClearQueue()====
The PlayQueue.ClearQueue() method removes all assets from the play queue. This does not stop the current playback. ClearQueue is commonly used to prepare the Play Queue for the addition of new assets.

Prototype:
bool ClearQueue()
Example:
var rc = window.external.PlayQueue.ClearQueue();

Return Value:
A boolean value indicating whether the request was successful.

====GetMetadata()====
PlayQueue.GetMetadata() can be used to obtain asset metadata about an asset in the play queue.

Prototype:
String GetMetadata(position, metadatatag);
where:
'''position''' - (integer) is the position of the asset within the playlist.
Note: Position is "zero based" so the first entry in the
queue is at position 0.
'''metadatatag''' - (string) is a tag describing which metadata is requested.

Example:
var mdata = window.external.PlayQueue.GetMetadata(2,"artist");
Return Value:
A String that contains the metadata requested for the asset located at the specified position in the play queue

====GetTitle()====
PlayQueue.GetTitle() retrieves the title of the asset at the specified position within the play queue.

Prototype:
String GetTitle(position);
where:
'''position''' - (integer) is the position of the asset within the playlist.
Note: Position is "zero based" so the first entry in the
queue is at position "0".
Example:
var title = window.external.PlayQueue.GetTitle(1);
Return value:
A String containing the Title of the asset at the requested position in the play queue

====GetURL()====
PlayQueue.GetURL() is used to obtain the URL from the asset at the specified position in the play queue

Prototype:
String GetURL(position);
where:
'''position''' - (integer) is the position of the asset within the playlist.
Note: Position is "zero based" so the first entry in the
queue is at position "0".
Example:
var url = window.external.PlayQueue.GetURL(1);
Return value:
A String containing the URL of the asset at the rquested position in the play queue.

===Properties===
====int length (read only)====
PlayQueue.length contains the length of the current play queue

====int cursor====
PlayQueue.cursor provides access to the position of the currently playing asset within the play queue. This cursor is 0 based, meaning that the first asset in the Play Queue has a cursor value of 0. Valid values range from 0 to the length of the play queue minus one.

If this value is changed before playback is started, the next asset to play will be the one assigned to this property. However, if a song is already playing and this property is changed, the current asset will continue to play even though this property has been updated. At the point that the current asset playback completes, the player will increment the cursor position and play the next asset in the queue rather than the one to which cursor was set. So, for example, to specify the next asset to play while an asset is currently playing, set the cursor property to the position of the asset to play minus one.

== Playlists API ==
The Playlists API is used to process user playlists.

===Methods===
====GetPlaylists()====

Prototype:
Array GetPlaylists();
Example:
var playlists = window.external.Playlists.GetPlaylists();
Return Value:
A array-like object that can be used to examine all user playlists.

Each element of the array represents a user playlist and contains the following properties
*filename - filename of the playlist
*title - name of the playlist
*playlistId - a unique identifier for the playlist, so you can retrieve it later. Also used with OpenPlaylist/SavePlaylist
*length - total length (time) in seconds. Cached data - not guaranteed to be accurate
*numitems - number of items in the playlist. Cached data - not guaranteed to be accurate

====OpenPlaylist()====
Playlists.OpenPlaylist() returns a Playlist object for the specified playlist ID. You must use
Playlists.GetPlaylists() before issuing this request.

Prototype:
Playlist OpenPlaylist(playlistId);
where:
'''playlistId''' - (string) the Id of the playlist to be opened.
Example:
var playlist1 = window.external.Playlists.OpenPlaylist(playlistId);
Return Value:
The Playlist object with the specified playistId.

====SavePlaylist()====
Playlists.SavePlaylist() saves the specified playlist object with the specified ID.

Prototype:
bool SavePlaylist(playlistId, playlist_to_save);
where:
'''playlistId''' (string) is the id of the playlist to be saved.
'''playlist_to_save''' (Playlist) is the Playlist object to be saved.
Example:
var rc = window.external.Playlists.SavePlaylist(playlistId, pl);
Return Value:
A boolean value indicating whether the request was successful.

=== Playlist Object ===
Playlist objects can be created/returned by the OpenPlaylist() method as well as various other APIs.

====Methods====
=====GetItemFilename()=====
The GetItemFilename() method retrieves the filename/URL of the item at the specified index into the playlist.

Prototype:
String GetItemFilename(position);
where:
'''position''' = (number) position of the item in the playlist for which the filename
should be returned.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var filename = playlst.GetItemFilename(0);

Return value:
A string containing the filename/URL of a particular item in the playlist

=====GetItemTitle()=====
The GetItemTitle() method returns the title of the asset at the requested index.

Prototype:
String GetItemTitle(position);
where:
'''position''' = (number) position of the item in the playlist for which the title
should be returned.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var title = playlst.GetItemTitle(0);

Return value:
The song title of the given item in the playlist

=====GetItemLength()=====
The GetItemLength() method retrieves the play length of the asset at the requested index.

Number GetItemLength(position);
where:
'''position''' = (number) position of the item in the playlist for which the length
should be returned.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var itemLength = playlst.GetItemLength(0);

Return value:
A number specifying the play length of the asset, in milliseconds.

=====Reverse()=====
The Reverse() method reverses the order of the assets within a playlist, i.e., the first becomes last and the second becomes second to last, etc.

Prototype:
Reverse();

Example:
var rc = playlst.Reverse();

=====Swap()=====
The Swap() method exchanges the assets at the two specified positions.

Prototype:
Swap(Number position1, Number position2)
where:
'''position1''' = (number) the index of the first item to be swapped.
'''position2''' = (number) the index of the second item to be swapped.
Note: position1 and position2 are "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.Swap(0,1);

=====Randomize()=====
The Randomize() method re-arranges the order of the playlist, placing the assets in random positions.

Prototype:
Randomize();

Example:
var rc = playlst.Randomize();

=====Remove()=====
The Remove() method removes an asset from the playlist. Subsequent assets are moved to lower number positions in the array.

Prototype:
Remove(position);
where:
'''position''' = (number) the position of the asset to be removed.
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.Remove(0);

=====SortByTitle()=====
The SortByTitle() method re-arrainges the order of the playlist so that it is alphabetical order by title.

Prototype:
SortByTitle();

Example:
var rc = playlst.SortByTitle();

=====SortByFilename()=====
The SortByFilename() method re-arrainges the order of the playlist so that it is alphabetical order by filename.

Prototype:
SortByFilename();

Example:
var rc = playlst.SortByFilename();

=====SetItemFilename()=====
Sets the filename of the asset at the specified location in the playlist.

playlistObj.SetItemFilename(position, filename);
where:
'''position''' = (number) position of the entry in the playlist to alter the filename
'''filename''' = (string) the new filename
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.SetFilename(0, "c:\\\\myfavorites\\myfavsong.mp3");

=====SetItemTitle()=====
Sets the title of the asset at the specified location in the playlist.

Prototype:
SetItemTitle(position, title);
where:
'''position''' = (number) position of the entry in the playlist to alter the filename
'''title''' = (string) the new title
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.SetItemTitle(0, "My Favorite Title");

=====SetItemLength()=====
Sets the length of the asset at the specified location in the playlist.

SetItemLength(position, length);
where:
'''position''' = (number) position of the entry in the playlist to alter the filename
'''length''' = (number) the new length
Note: Position is "zero based" so the first entry in the
playlist is at position 0.

Example:
var rc = playlst.SetItemLength(0, 1000);

=====InsertURL()=====
Inserts the specified asset in front of the asset at the specified position. That and subsequent items are "pushed" to a higher position in the array.

InsertURL(position, url);
InsertURL(position, url, title);
InsertURL(position, url, title, length);
where:
'''position''' = (number) position within the playlist before which to insert the asset
'''url''' = (string) the URL of the asset to be inserted
'''title''' = (string) title of the asset to be inserted
'''length''' = (number) length (milliseconds) of the asset to be inserted
Note: Position is "zero based" so the first entry in the
playlist is at position 0.
Note: title and length are user specified and do not have to match
the actual values of the asset. When the asset is played, the
values will be replaced in the Play Queue when the URL is opened
for playback but will othewise retain the above values in the
playlist.

Return value:
A boolean value indicating whether the request was successful.

=====AppendURL()=====
The Playlist.AppendURL() method appends an asset URL to the playlist.

Playlist.AppendURL(url);
Playlist.AppendURL(url, title);
Playlist.AppendURL(url, title, length);
where:
'''url''' = (string) the URL to the asset to be appended
'''title''' = (string) title of the asset to be appended
'''length''' = (number) length (milliseconds) of the asset to be appended
Note: title and length are user specified and do not have to match
the actual values of the asset. When the asset is played, the
values will be replaced in the Play Queue when the URL is opened
for playback but will othewise retain the above values in the
playlist.

Return value:
A boolean value indicating whether the request was successful.

=====Clear()=====
The Playlist.Clear() method will remove all assets from the playlist.

Playlist.Clear();

Return value:
A boolean value indicating whether the request was successful

====Properties====
=====int numitems (read only)=====
The Playlist.numitems property contains the number of assets within the playlist.


== Bookmarks API ==
The Bookmarks API provides methods to manage bookmarks.
===Methods===
====Add()====

Prototype:
boolean Add(url, title);
where:
'''url''' = (string) The url of the asset to be bookmarked.
'''title''' = (string) A suitable title to be used within the bookmark.

Example:
var rc = window.external.Bookmark.Add("c:\myfavs\songstocodeby.mp3",
"Songs To Code By");

Return value:
A boolean value indicating whether the request was successful.

== Podcasts API ==
The Podcasts API provides methods to manage Podcasts.

===Methods===
====Subscribe()====
The Podcasts.Subscribe() method is used to add a channel to the list of podcast subscriptions, automatically subscribe to the podcast and begin downloading of the available episodes. Once downloaded the episodes can be selected for playback.

Prototype:
bool Subscribe(url);
where:
'''url''' = (string) the Podcast URL to subscribe to.

Example:
var rc = window.external.PodCasts.Subscribe(<nowiki>"http://services.winamp.com/rss/news"</nowiki>);

Return value:
boolean value that indicates whether the request was successful.

== Config API ==
The Config API provides a means by which properties can be saved. Properties added using the Config API are persistent across Winamp launches.

===Adding and Retrieving Properties===
Adding a property is accomplished by identifying a property and assigning it a value. Once assigned, the value can be retrieved like any other objects properties.

Example:
window.external.Config.myProperty = "Test";
var myProp = window.external.Config.myProperty; // myProp is set to "Test"

===Storing and Retrieving advanced data types===
Internally, all properties are stored as strings. If you need to store datatypes more advanced than String, Number, or Boolean, it is recommended that you create a JSON string out of your data type.

== Security API ==
===Methods===
====GetActionAuthorization()====
The Security.GetActionAuthorization() method can be used to determine whether a user has previously allowed or denied the functioning of a particular API's methods. Group strings match API names.

Prototype:
number Security.GetActionAuthorization(group);
where:
group = (string) Name of API to check for permission.

Example:
var rc = window.external.Security.GetActionAuthorization("Transport");

Return Data:
*-1 = Either the user has not specified whether to allow/deny use of this API or the action usage is unrestricted.
*0 = The user has previously specified to deny use of this API/method.
*1 = The user has previously specified to allow use of this API/method.


== MediaCore API ==
===Methods===
==== IsRegisteredExtension() ====
MediaCore.IsRegisteredExtension() method can be used to determine if the Winamp client is able to playback a specific format. The file extension of the asset usually indicates the format. This method is important since Winamp support for different formats is contained within plugins which may or may not exist for use.

Prototype:
boolean IsRegisteredExtension(ext);
where:
'''ext''' = (string) identifies the format to be queried for support in the form of a
character string of the extension (a starting period is optional).

Example:
var canPlay = window.external.MediaCore.IsRegisteredExtension("mp3");

Return value:
Boolean value indicating whether the format is supported.

==== GetMetadata() ====
MediaCore.GetMetadata() method can be used to obtain metadata about an asset. This method differs from Transport.GetMetadata() in that the asset does not have to be currently playing. It differs from PlayQueue.GetMetadata() in that it doesn't have to be present in the play queue.

Prototype:
string GetMetadata(url, tag);
where:
'''url''' = (string) containing the URL for which metadata is to be retrieved.
'''tag''' = (string) the specific piece of metadata to be returned.

Example:
var art = window.external.MediaCore.GetMetadata(
"c:\\my favs\\myfavorite.mp3","artist");

Return value:
A string containing the metadata requested.

==== AddMetadataHook() ====
MediaCore.AddMetadataHook() method can be used to add or override metadata for an asset. For example, some assets such as those that are streamed may not contain metadata. This method allows the online service to add metadata for the specified asset. Subsequent GetMetadata() methods will return this information. Online services can override the metadata present within an asset using this method. This method can be used by services that define or can obtain their own metadata for the assets they provide rather than rely on what might or might not be present in the asset itself.

Prototype:
string AddMetadataHook(url, tag, value);
where:
'''url''' = (string) containing the URL for which metadata is to be added.
'''tag''' = (string) the specific metadata key for which a value will be added.
'''value''' - (string) the value of the metadata key being added.

Example:
var rc = window.external.MediaCore.AddMetadataHook(
"c:\\my favs\\myfavorite.mp3","artist","myself");

Return value:
A boolean value that indicates whether the request was successful.

==== RemoveMetadataHook() ====
MediaCore.RemoveMetadataHook() method can be used to remove metadata added through the AddMetadataHook() method. Subsequent GetMetadata() requests will return whatever metadata was available previously, if any.

Prototype:
string RemoveMetadataHook(url, tag);
string RemoveMetadataHook(url);
where:
'''url''' = (string) containing the URL for which metadata is to be removed.
'''tag''' = (string) the specific metadata key for which a value will be removed.

If only the url parameter is provided, all metadata added with AddMetadataHook() for the specified url will be removed.

Example:
var rc = window.external.MediaCore.RemoveMetadataHook(
"c:\\my favs\\myfavorite.mp3","artist");

Return value:
A boolean value that indicates whether the request was successful.

== History API ==
The History branch of the Media Library pane is actually a database containing information about previously played assets. The History API allows a service to search and retrieve information from this database. By specifying a query string, Winamp will return an array of objects that match the values specified in the query.

===Methods===

==== Query() ====
Prototype:
results = History.Query(queryString);
where:
'''queryString''' = a properly formed string to match data to be returned.

Example:
var results = window.external.History.Query("LASTPLAYED<[now]");

Return value:
An "array-like" object that contains the results of the query.

Each entry of the array contains the following properties:
* String filename
* String title
* Number length
* Number playcount
* Date lastplay

'''Query String format:'''
<field> <comparison> [value] [<logic operator> <field> <comparison> [value] [...]]

'''Fields:'''
{| border="1"
|-
! Keyword
! Description
|-
| LASTPLAY
| Date and time when this asset was last played.
|-
| FILENAME
| Full filename (including path)
|-
| LENGTH
| Length, in seconds (or hh:mm:ss)
|-
| TITLE
| Title
|-
| PLAYCOUNT
| Number of times the asset has been played.
|}

'''Comparison Operators:'''
{| border="1"
|-
! Operator
! Description
|-
| '='
| String or integer equals value
|-
| '!='
| String or integer does not equal value
|-
| '<'
| String or integer is less than value
|-
| '>'
| String or integer is greater than value
|-
| '<='
| String or integer is less than or equal to value
|-
| '>='
| String or integer is greater than or equal to value
|-
| HAS
| String contains value
|-
| NOTHAS
| String does not contain value
|-
| LIKE
| String is similar to value ("the" and whitespace are ignored)
|-
| BEGINS
| String begins with value
|-
| BEGINSLIKE
| String begins like value
|-
| ENDS
| String ends with value
|-
| ISEMPTY
| (no comparison value required) TRUE if <field> is empty
|-
| ISNOTEMPTY
| (no comparison value required) TRUE if <field> is not empty
|}

'''Values can be:'''
*"strings with spaces" or strings_without_spaces
*integers can be "32" or just 32
*integers for LENGTH can be a plain integer (seconds), or mm:ss or hh:mm:ss
*date/timestamps should be [datetime data], which can be either an absolute or relative time. i.e.: [3 weeks ago], [18:15], [05/30/2003], [yesterday noon], [3 days ago 5 pm], [now], [5 mn before may 30th], etc.



== Application API ==
===Methods===

====LaunchURL()====
The Application.LaunchURL() method launches a URL in the bento browser
or default browser. The default browser is launched if force_external = true or in skins that don't define a browser.

Prototype:
boolean LaunchURL(url, force_external);
where:
'''url''' = (string) The url to open in the browser
'''force_external''' = (boolean) will force the url to be displayed in a browser
outside of the Winamp client.

Example:

var rc = LaunchURL(<nowiki>"http://www.winamp.com"</nowiki>, true);

Return value:
A boolean value indicating whether the request was successful.

===Properties===
====int version (read only)====
The version property returns the version number of the browser control within the Winamp client as an integer, e.g. 555 for 5.55, 560 for 5.6
====string versionstring (read only)====
The versionstring property returns the version number of the browser control within the Winamp client as a string, e.g. "5.55" for 5.55
====string language (read only) ====
Language identifier from the currently installed language pack. Follows ISO 639-1 two letter language codes

====string languagepack (read only) ====
Language pack identifier from the currently installed language pack. follows the form
lc-CC
where lc is the two letter ISO 639-1 language code
and CC is the two letter ISO 3166 country code.

Note: do not count on the country code being the same as the user's current location.


== Skin API ==

The skin color API is a bit of a challenge. This API reflects some the idiosyncrasies of the underlying skinning system. "Classic" skins define a palette of 24 colors for the skin and an additional 6 colors for the playlist editor. "Modern" skins define these as well as any number of other colors retrievable by name (e.g. wasabi.tree.text for the text color on tree views). A website relying on any of these extra "named" colors should be careful to implement a fallback color based on the classic palette, as no named colors exist in classic skins!

===Methods===
====GetClassicColor()====
The Skin.GetClassicColor() method is used to retrieve color information regarding different Skin UI elements.

Prototype:
GetClassicColor(classiccolornumber);
where:
'''classiccolornumber''' = (integer) A number in the range 0-23 identifying the Skin's UI element
for which the color should be returned.

Example:
var wndBgColor = window.external.Skin.GetClassicColor(2);

Return value:
The HTML color constant used for the specified Skin UI element.

====Classic Color Numbers====
{| border="1"
|-
! Number
! Description
|-
| 0
| Item Background
|-
| 1
| Item Foreground
|-
| 2
| Window Background
|-
| 3
| Button Foreground
|-
| 4
| Window Foreground
|-
| 5
| Hilite
|-
| 6
| Selection
|-
| 7
| List Header Background
|-
| 8
| List Header Text
|-
| 9
| List Header Frame Top
|-
| 10
| List Header Frame Middle
|-
| 11
| List Header Frame Bottom
|-
| 12
| List Header Empty Background
|-
| 13
| Scrollbar Foreground
|-
| 14
| Scrollbar Background
|-
| 15
| Scrollbar Inverse Foreground
|-
| 16
| Scrollbar Inverse Background
|-
| 17
| Scrollbar Dead Area
|-
| 18
| Selection Bar Foreground
|-
| 19
| Selection Bar Background
|-
| 20
| Inactive Selection Bar Foreground
|-
| 21
| Inactive Selection Bar Background
|-
| 22
| Alternating Item Background
|-
| 23
| Alternating Item Foreground
|}

====GetPlaylistColor()====
The Skin.GetPlaylistColor() method is used to retrieve color information regarding different Playlist UI elements.

Prototype:
GetPlaylistColor(playlistcolornumber);
where:
'''playlistcolornumber''' = (integer) a number in the range 0-5 identifying the Playlist's UI
element for which the color should be returned.

Example:
var normalBgColor = window.external.Skin.GetPlaylistColor(2);

Return value:
The HTML color constant used for the specified Playlist UI element.

====Playlist Color Numbers====
{| border="1"
|-
! Number
! Description
|-
| 0
| Normal
|-
| 1
| Current
|-
| 2
| Normal Background
|-
| 3
| Selected Background
|-
| 4
| Video Window Status Bar Foreground
|-
| 5
| Video Window Status Bar Background
|}

====GetSkinColor()====
The Skin.GetSkinColor() method is used to retrieve color information regarding different Playlist UI elements.

Prototype:
GetSkinColor(skincolorname);
where:
'''skincolorname''' = (string) identifying the Skin's UI
element for which the color should be returned.

Example:
var buttonTextColor = window.external.Skin.GetSkinColor("wasabi.button.text");

Return value:
The HTML color constant used for the specified Playlist UI element.

====Skin Color Names====
{| border="1"
|-
! Name
! Description
|-
|"wasabi.list.item.selected.fg"
|Selected item text foreground color
|-
|"wasabi.list.column.separator"
|Color of line between columns
|-
|'''Item Lists, Lists with playable items'''
|
|-
|"wasabi.itemlist.outline.current"
|Currently playing outline color
|-
|"wasabi.itemlist.outline.focus"
|Focused item dashed outline color
|-
|"wasabi.itemlist.selborder"
|
|-
|'''Message box'''
|
|-
|"wasabi.msgBox.background"
|Messagebox background color
|-
|"wasabi.textBar.text"
|Text object & message box text color
|-
|"wasabi.textBar.background"
|Text object & message box text background color
|-
|'''Buttons'''
|
|-
|"wasabi.button.text"
|Buttons text color
|-
|"wasabi.button.hiliteText"
|Buttons hilite text color, used by tab windows
|-
|"wasabi.button.dimmedText"
|Buttons dimmed text color, when disabled
|-
|'''Popup menus'''
|
|-
|"wasabi.popup.text"
|Menu items text color
|-
|"wasabi.popup.hiliteText"
|Hilited item text color
|-
|"wasabi.popup.dimmedText"
|Disabled item text color
|-
|'''Components'''
|
|-
|"wasabi.component.title.foreground"
|Old title bar text color when using TTF
|-
|"wasabi.component.title.border"
|Old title bar text outline when using TTF
|-
|'''Labeled Windows'''
|
|-
|"wasabi.labelwnd.foreground"
|Text foreground color
|-
|"wasabi.labelwnd.background"
|Text drop shadow color
|-
|'''Edit Windows'''
|
|-
|"wasabi.edit.selection"
|Selected text
|-
|"wasabi.edit.text"
|Text
|-
|"wasabi.edit.background"
|Text background
|-
|
|
|-
| "wasabi.text.color"
|
|-
| "wasabi.text.color.inverse"
|
|}

===Properties===
====string name (test)====
The Skin.name property gives access to the name of skin currently in use. Changing this value will change the skin displayed for the player.

====string font (read only)====
The Skin.font property provides the font name currently used in the player.

====string fontsize (read only)====
The Skin.fontsize property provides the size of the font currently used in the player.

== Metadata tag names ==

When retrieving metadata through Winamp, a freeform string is passed. The popular file formats (MP3, WMA, FLAC, M4A) will respond uniformly to a common base of strings. However, each file format is idiosyncratic in how metadata is stored. Some file types will respond to additional strings which are not documented here.

Remember that the metadata is only as good as the tagging in the file itself. A poorly tagged track will return poor metadata.

Common metadata tags
bitrate
length
type
title
artist
albumartist
album
genre
year
disc
publisher
comment
track
composer
conductor

Online Service Developer

2009-01-22T15:37:35Z

SMonty: New page: '''Breadcrumb''' -- Wiki Main : Skin Developer : Visual Developer : Plug-in Developer : Online Service Developer : Articles Page : [[Developers F...

Main Page

2009-01-22T15:37:05Z

SMonty:

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Online Service Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Main_Page#Glossary_of_Terms|Glossary]]

== Welcome ==
Welcome to Winamp's Developer Network wiki. By consolidating Winamp documentation, code samples, reference materials, and sample articles, we've created a one-stop shop for all things related to Winamp development. The purpose of this site is to help facilitate the development of [[Skin_Developer|Winamp skins]], [[Plug-in_Developer|plug-ins]], [[Visual_Developer|visualization presets]] and [[Online_Service_Developer|online services]]. In order to offer the most relevant material (''and since no one is more of an expert than you''), our goal is to present a wiki that is updated, maintained, and moderated by the Winamp developer community.

Why develop for Winamp, you ask? Besides being a kickass media player with a flexible programming platform, Winamp has a very loyal fan base with over 72 million worldwide users per month. So chances are your creative masterpiece will live well beyond the boundaries of your hard drive. Now that we've got your creative juices flowing (or at a minimum, appealed to your desire for fame and adoration), you can use the '''Developer Network''' as a springboard for everything you need. Most importantly, you can [http://www.winamp.com/user/submit upload] your creation and share it with the World. ''(Note: You'll need a winamp.com account to upload).''

=== How to use the Wiki ===
There are several ways that you can use this wiki. Use it as a reference guide. Start sifting through the content to find the information you need to start developing. If you find out that some key information is missing or you see that something on the site is completely inaccurate, we welcome your contributions. We'd love for you to update the site with killer content and [[Articles]]. Before you start contributing though, make sure you check out the Developer Network [[Policies & Guidelines]] page and create an account. By creating an account or logging into the Winamp Developer Network, you are agreeing to our [[Winamp Developer Network Wiki Terms and Conditions|Terms of Service]] and [http://www.winamp.com/legal/privacy Privacy Policy]

If you've never edited a wiki before, you might want to check out [http://en.wikipedia.org/wiki/Wikipedia:How_to_edit_a_page Wikipedia: How to edit a page]for some pointers.

== Who Should Use the Wiki ==
This wiki is for everyone. Whether you're a seasoned vet, intermediate coder, loyal fan, or even newbie. Primarily though, it's for Winamp developers and user-contributors who want to be actively engaged in the advancement of the Winamp media player. Either by leveraging the content of this site to build better '''skins''', '''plug-ins''', '''visualizations''' and '''online services'''; or by sharing your knowledge and expertise with the community.

===Skin Developer===
To put it as simply as possible, skins change the way your Winamp player looks. If you want to get fancy and say that it changes the GUI (graphical user interface) then you can, but really all you need to know is if you download or create a new skin, Winamp will put on a little mask and pretend to look different. Check [[Skin Developer]] page for more details.

====Classic Skins====
Based on the Winamp 2 model, [[Skin_Developer#Creating_Classic_Skins|Classic skins]] are easier to create than Modern skins, but they do not allow the developer to change the form or function of the player. [[Skin_Developer#Creating_Classic_Skins|Classic skins]] developers may only replace a standard set of images that alter the player's visual appearance.

====Modern Skins====
[[Skin_Developer#Creating_Modern_Skins|Modern skins]] are skins that adhere to the Winamp 3+ skin model. Modern (or freeform) skins offer developers a tremendous amount of flexibility by allowing you to change the player's shape, size, layout, and function. Learn how to create a modern skin for Winamp!

=== Visual Developer===
You know those funny dancing colors you see when you hear music – and no ''Autumn Moonpuppy'', I’m not talking about that time you "toured" with The Dead. [[Visual_Developer|Visualizers]] are dynamic add-ons that produce images, colors, and textures that change based elements of the music being played. Winamp offers two primary visualization platforms (AVS & MilkDrop) allowing you to create different presets. If you’re feeling invincible, you can even attempt to create your own visualization environment.

=== Plug-in Developer===

[[Plug-in_Developer|Plug-ins]] can pretty much do anything! ...within reason, of course. You can alter the sound of your music, turn your mobile phone into a Winamp remote control, or if ya’d like, translate Winamp into another language. Basically, we’ve made the platform flexible enough so that you can craft your idyllic feature and plug it right into Winamp.

'''Types of Plug-ins'''

There are all kinds of categorizes of plug-ins: Input, Output, Visualization, DSP/Effect, General Purpose, Media Library and Portables. That means, you can go nuts in discovering how a single plug-in can change your life. You can read up on the taxonomy of a plug-in here.

'''Start Creating Your Plug-in'''

If you feel like developing one yourself, you can –
# Check out the [[Plug-in_Developer#Tools|suggested tools]]
# Read-up on the [[Plug-in_Developer#SDK_Documentation|SDK documentation]]
# [http://download.nullsoft.com/winamp/plugin-dev/WA5.55_SDK.exe Download the SDK]
# Visit the [http://forums.winamp.com/ Winamp Forums]
# [http://www.winamp.com/user/login Submit your plug-in]. Ain’t it easy?

=== Online Service Developer===
[[Online_Service_Developer|Online Services]] are web pages that are rendered by the embedded browser within Winamp. The awesomeness of these pages is that they can interact with the Winamp Player. In this way a web page can start and stop the player, examine and create playlists, enqueue songs for playback, the colors used in the skin of the player, etc. We're excited to see what you come up with by merging html web pages and the Winamp player.

== Developer Resources ==
*[[Articles]] - link consolidation of all articles written by all types of developers
*[[Plug-in_Developer#SDK_Documentation|SDK Documentation]]
* Download the SDK
*[[Developers_FAQ | Frequently Asked Questions]]
*[[Skin Developer]]
*[[Visual Developer]]
*[[Plug-in Developer]]
*[[Online Service Developer]]

== Glossary of Terms ==
* '''Agent''' - Winamp's taskbar component. Maintains file type associations.

* '''APE''' - Advanced Plug-in Effect. Third party Effect Module created for AVS.

* '''AVS''' - Advanced Visualization Studio comes bundled with Winamp. Allows endless user customization.

* '''Base Skin''' - The standard skin built into Winamp. Also the downloadable template used to create new skins.

* '''Bookmark''' - Winamp feature that allows quick access to favorite songs or streams.

* '''Codec''' - Short for coder/decoder. A software program for converting between digital data and analog signals. Winamp uses codecs to play many different kinds of audio files.

* '''Developer''' - Any one who creates a skin or writes an application or plug-in for Winamp.

* '''Discussion List''' - A mailing list hosted by Winamp.com to help foster the developer community.

* '''DLL''' - Dynamically Linked Library. A Win32 property that allows Winamp's plug-in architecture.

* '''DoubleSize Mode''' - Winamp option that doubles the width and height of the Main and Equalizer components.

* '''DSP Plug-in''' - A plug-in that manipulates audio data before being sent to the speakers.

* '''Easter Egg''' - A programming term used for a hidden, often humorous feature.

* '''Equalizer''' - Winamp component that allows audio tweaking for optimal sound quality.

* '''FAQ''' - Frequently Asked Questions.

* '''Forum''' - A message board hosted by Winamp.com to help foster the Winamp community.

* '''Flounder''' - Any of various marine flatfishes of the families Bothidae and Pleuronectidae, which include important food fishes.

* '''General Purpose Plug-in''' - A plug-in that does not require access to audio data.

* '''Input Plug-in''' - A plug-in that adds a new file type to Winamp's list of supported types.

* '''IPC''' - Inter-process communication. Basically, anytime one program communicates with another.

* '''Language Pack''' - A special plug-in that translates most Winamp text.

* '''Llama''' - A domesticated South American ruminant mammal (Lama glama) related to the camel, raised for its soft, fleecy wool. The only animal fully endorsed by Nullsoft.

* '''Mini-browser''' - Winamp component that allows internet browsing during audio play.

* '''MP3''' - MPEG-1 Audio Layer 3. A digital audio compression algorithm that acheives a compression factor of about twelve while preserving sound quality.

* '''NSDN''' - Nullsoft Developers Network. The developers source for official Nullsoft information.

* '''NSIS''' - Nullsoft Scriptable Install System. Nullsoft's in-house installer utility. Required for plug-in installation.

* '''Nullsoft''' - Group of benevolent artisans who revolutionize the computer world on a regular basis.

* '''Output Plug-in''' - A plug-in that directs audio flow to one or more destinations.

* '''PiMP''' - Plug-in Mini Packager. Predecessor to NSIS.

* '''PMP''' - Portable Media Player. Creative Zen, Apple iPod, etc. Not to be confused with the original name for NSIS (PiMP).

* '''Playlist Editor''' - Winamp component that allows easy sorting and sequencing of audio files.

* '''Plug-in''' - Basis of Winamp architecture. Allows third parties to add functionality to Winamp by "plugging in" additional code.

* '''Preset''' - Visually pleasing sequence of Effect Modules in AVS or Milkdrop.

* '''SDK''' - Software Development Kit. All the tools you need to perform a programming job.

* '''SHOUTcast''' - Nullsoft's internet streaming MP3 solution.

* '''Skin''' - Interchangeable visual interface for Winamp.

* '''Visualization Plug-in''' - A plug-in that uses audio data to drive graphics.

* '''WAL''' - Required format for Modern skins before submittal.

* '''WAV''' - Widely used uncompressed audio format. Usually more than 10X larger than MP3.

* '''Winamp''' - The ultimate high-fidelity music player for Windows 2000/XP/Vista. Winamp supports MP3, CD and other audio formats, not to mention hundreds of plug-ins and thousands of skins.

* '''Winamp.com''' - Official website of Winamp. Houses all approved skins, plug-ins, updates, forums, etc.

* '''WindowShade Mode''' - Winamp option that shrinks most components to a narrow bar with only most basic functionality.

* '''WSZ''' - Required format for Classic skins before submittal.

* '''WVS''' - Obsolete name for AVS.

== FAQ ==
Check out the [[Developers FAQ]]. Not to mistaken for the standard frequently asked questions that live on the Winamp Forums (although there may be some overlap. This FAQ is specific to developers.

==Contribute to the Wiki ==
Just like the success of Winamp itself, the success of the Developer Network relies on you. We encourage '''everyone''' to contribute. From the expert developer, to the passionate user. Your updates, additions, and moderation efforts are critical and we definitely appreciate your efforts making this one of the premier developer sites.

*[[Policies & Guidelines]]