WinampEasyService

Making it easier to integrate services with good old WinAmp

Goal:

• Make it easier to write plugins and integrate services into WinAmp and WACUP

Installing plugins:

• Put the ml_easysrv and in_easyfngetter plugins in the WACUP Plugins folder
• Also put isrv_managed and isrv_web in the WACUP Plugins folder
• Put any service plugins (esrv_\*.exe, msrv_\*.dll, srv_\*.dll, wsrv_\*.html) in the same folder
• The services will be accessible in the Services tree of the Media Library

Using plugins (Instead of this, plugins can now provide their own custom UI):

• Press the Invoke plugin button to interact with the selected service
• Double click an entry in the list to play it
• Alt + double click an entry in the list to enqueue it
• Right click an entry for more options

Service plugin development:

• Managed (.NET based) DLLs have to be named msrv_\*.dll and contain the msrv.EasyService class implementing the following:
  • public void InitService(Dictionary<string, object> functionDict, string pluginDir, uint serviceID)
    • functionDict contains the following functions:
      • string GetOption(string optionName, string defaultValue)
      • void SetOption(string optionName, string optionValue)
      • void SkinForm(Form form)
  • public Tuple<string, string, string, uint> GetNodeDesc() should return a tuple with the following information:
    • Category
    • Node name you wish to show in the Media Library
    • The column names you wish to show in the Media Library, delimited by \t
    • Capabilities (0):
      • const uint CAP_DEFAULT = 0; for no additional capabilities
      • const uint CAP_CUSTOMDIALOG = 1; for custom UI support
  • public List<List<string>> InvokeService(IntPtr hwndWinampParent, IntPtr hwndLibraryParent, IntPtr hwndParentControl, string skinPath) should return the entries to populate the Media Library ListView with
    • The inner lists should always contain three strings in this order: Column contents delimited by \t, Title to show in the playlist, Filename
    • The filename can be a direct filename (e.g. e:\\example.mp3) or a reference (e.g. ref_examplefile)
  • Optional: public string GetFileName(string fileID) should return the direct filename when called with a reference
  • Important: If you wish to show a window, call ShowWindow(form.Handle, SW_SHOW); on your Form after creation
    • ShowWindow resides in user32.dll, SW_SHOW equals 5
  • Full example: WinampEasyService\\msrv_exampledll
• Managed (.NET based) DLLs with custom UIs have to be named msrv_\*.dll and contain the msrv.EasyService class implementing the following:
  • public void InitService(Dictionary<string, object> functionDict, string pluginDir, uint serviceID)
    • functionDict contains the following functions:
      • string GetOption(string optionName, string defaultValue)
      • void SetOption(string optionName, string optionValue)
      • void SkinForm(Form form)
  • public Tuple<string, string, string, uint> GetNodeDesc() should return a tuple with the following information:
    • Category
    • Node name you wish to show in the Media Library
    • The column names you wish to show in the Media Library, delimited by \t
    • Capabilities (1):
      • const uint CAP_DEFAULT = 0; for no additional capabilities
      • const uint CAP_CUSTOMDIALOG = 1; for custom UI support
  • public UserControl GetCustomDialog(IntPtr hwndWinampParent, IntPtr hwndLibraryParent, IntPtr hwndParentControl, string skinPath) should return the System.Windows.Forms.UserControl you'd like to show
• Unmanaged DLLs have to be named srv_\*.dll and implement the functions in WinampEasyService\\ml_easysrv\\easysrv.h:
  • void InitService(AddItemFunc addItemFunc, GetOptionFunc getOptionFunc, SetOptionFunc setOptionFunc, const wchar_t\* pluginDir, UINT_PTR serviceID):
    • The function pointers are described in easysrv.h:
      • typedef void (\*AddItemFunc)(const wchar_t\* displayInfo, const wchar_t\* playlistInfo, const wchar_t\* filename, UINT_PTR serviceID);
      • typedef void (\*GetOptionFunc)(UINT_PTR serviceID, const wchar_t\* optionName, const wchar_t\* defaultValue, wchar_t\* output, DWORD outputSize);
      • typedef void (\*SetOptionFunc)(UINT_PTR serviceID, const wchar_t\* optionName, const wchar_t\* optionValue);
  • NodeDescriptor GetNodeDesc() should return a NodeDescriptor struct with the following information:
    • Category
    • Node name you wish to show in the Media Library
    • The column names you wish to show in the Media Library, delimited by \t
    • Capabilities (0):
      • #define CAP_DEFAULT 0u for no additional capabilities
      • #define CAP_CUSTOMDIALOG 1u for custom UI support
  • void InvokeService(HWND hwndWinampParent, HWND hwndLibraryParent, HWND hwndParentControl, wchar_t\* skinPath) should call AddItemFunc as many times as needed
    • Filenames can be direct filenames (e.g. e:\\example.mp3) or references (e.g. ref_examplefile)
  • Optional: const wchar_t\* GetFileName(const wchar_t\* fileID) should return the direct filename when called with a reference
  • Full example: WinampEasyService\\srv_exampledll
• Unmanaged DLLs with custom UIs have to be named srv_\*.dll and implement the functions in WinampEasyService\\ml_easysrv\\easysrv.h:
  • void InitService(AddItemFunc addItemFunc, GetOptionFunc getOptionFunc, SetOptionFunc setOptionFunc, const wchar_t\* pluginDir, UINT_PTR serviceID):
    • The function pointers are described in easysrv.h:
      • typedef void (\*AddItemFunc)(const wchar_t\* displayInfo, const wchar_t\* playlistInfo, const wchar_t\* filename, UINT_PTR serviceID);
      • typedef void (\*GetOptionFunc)(UINT_PTR serviceID, const wchar_t\* optionName, const wchar_t\* defaultValue, wchar_t\* output, DWORD outputSize);
      • typedef void (\*SetOptionFunc)(UINT_PTR serviceID, const wchar_t\* optionName, const wchar_t\* optionValue);
  • NodeDescriptor GetNodeDesc() should return a NodeDescriptor struct with the following information:
    • Category
    • Node name you wish to show in the Media Library
    • The column names you wish to show in the Media Library, delimited by \t
    • Capabilities (1):
      • #define CAP_DEFAULT 0u for no additional capabilities
      • #define CAP_CUSTOMDIALOG 1u for custom UI support
  • HWND GetCustomDialog(HWND _hwndWinampParent, HWND _hwndLibraryParent, HWND hwndParentControl, wchar_t\* skinPath) should return the HWND of the newly created child dialog
  • Full example: WinampEasyService\\srv_cdlexampledll
• EXE files (doesn't matter if managed or unmanaged) have to be named esrv_\*.exe and respond to the following command line arguments:
  • GetNodeDesc: Print the following information to STDOUT:
    • Category
    • Node name you wish to show in the Media Library
    • The column names you wish to show in the Media Library, delimited by \t
    • Capabilities (0):
      • const uint CAP_DEFAULT = 0; for no additional capabilities
      • const uint CAP_CUSTOMDIALOG = 1; for custom UI support
  • InvokeService hwndWinampParent hwndLibraryParent hwndParentControl pluginDir skinPath configFileName shortName serviceID: Print the entries to populate the Media Library ListView with to STDOUT in the following way:
    • Column contents delimited by \t
    • Title to show in the playlist
    • Filename
      • Filenames can be direct filenames (e.g. e:\\example.mp3) or references (e.g. ref_examplefile)
  • Optional: GetFileName FileID: Print the direct filename corresponding to the reference FileID to STDOUT
  • Important: If you wish to show a window, you might have to call ShowWindow(form.Handle, SW_SHOW); on your Form after creation
    • ShowWindow resides in user32.dll, SW_SHOW equals 5
  • Full example: WinampEasyService\\esrv_exampleexe
• EXE files (doesn't matter if managed or unmanaged) with custom UIs have to be named esrv_\*.exe and respond to the following command line arguments:
  • GetNodeDesc: Print the following information to STDOUT:
    • Category
    • Node name you wish to show in the Media Library
    • The column names you wish to show in the Media Library, delimited by \t
    • Capabilities (1):
      • const uint CAP_DEFAULT = 0; for no additional capabilities
      • const uint CAP_CUSTOMDIALOG = 1; for custom UI support
  • GetCustomDialog hwndWinampParent hwndLibraryParent hwndParentControl pluginDir skinPath configFileName shortName serviceID: Show a correctly set up window
  • Important: If you wish to show a window, you might have to call ShowWindow(form.Handle, SW_SHOW); on your Form after creation
    • ShowWindow resides in user32.dll, SW_SHOW equals 5
  • Full example: WinampEasyService\\esrv_cldexampleexe
• HTML files have to be named wsrv_\*.html and implement the following:
  • Implement the function function getNodeName() that returns the node name you wish to show in the Media Library
  • Make use of the window.winamp object, which provides the following functions:
    • string getoption(string optionName, string defaultValue)
    • void setoption(string optionName, string optionValue)
    • void additem(string filename, bool enqueue)
    • void inject(string url, string js)
  • Full example: WinampEasyService\\WebExamples\\wsrv_example.html

Multiservice plugin development:

• Managed (.NET based) DLLs have to implement the following, in addition to those above:
  • public int GetNodeNum() should return the number of services implemented by the plugin
  • public void SelectService(int multiID) is called to select the currently needed subservice
  • Important: The selected subservice ID should be taken into consideration on subsequent function calls
  • Full example: WinampEasyService\\msrv_examplemulti
• Unmanaged DLLs have to implement the following, in addition to those above:
  • int GetNodeNum() should return the number of services implemented by the plugin
  • void SelectService(int multiID) is called to select the currently needed subservice
  • Important: The selected subservice ID should be taken into consideration on subsequent function calls
  • Full example: WinampEasyService\\srv_examplemulti
• EXE files (doesn't matter if managed or unmanaged) have to respond to the following, in addition to those above:
  • GetNodeNum: Print the number of services implemented by the plugin to STDOUT
  • select MultiID Usual_Arguments should respond to Usual_Arguments with MultiID being the selected subservice ID
  • Full example: WinampEasyService\\esrv_examplemulti

Custom Reference ID usage:

• Declare CAP_CUSTOMREFID in your Capabilities
• Implement GetCustomRefId and return your custom Reference ID
• To declare a playlist entry using a custom Reference ID, the file name yourcustomrefid_ref_examplefile.ref has to be used, instead of the usual ref_examplefile
• Reference handling through GetFileName is unchanged
• Example: WinampEasyService\\refidexample

Custom URL Handling:

• Declare CAP_URLHANDLER in your Capabilities
• Implement GetUrlPrefix and return the prefix of the URLs you want to handle
• URLs have to be handled in GetFileName

ServicePlugins

The following plugins have been developed using this framework:

• esrv_bandcamp: Bandcamp integration
  • Needs a username and the content of the identity cookie
  • Can save credentials for later
  • Only works for purchased items
  • Works for both tracks and albums
• esrv_localsearch: Local file search
  • Searches the given directory for the given file pattern
  • Has recursive search option
• esrv_soundcloud: SoundCloud integration
  • Uses SoundCloudExplode under the hood
• msrv_skinner: Spawn overlays to skin other windows' titlebars
• msrv_soundcloud_plus: SoundCloud integration with better UI
• esrv_spotify: Spotify integration
  • Falls back to YouTube if a track is unavailable and its YouTube ID is set
  • Uses SpotifyExplode and YouTubeExplode under the hood
• esrv_youtube: YouTube integration
  • Unfortunately slow
  • Uses YouTubeExplode under the hood
• srv_skinbrowser: Browse and switch WinAmp skins right from the Media Library!
  • Presumes the Skins directory is next to the Plugins directory
  • Updates the filelist with newly appeared files every second
  • Automatically applies newly added skins if checkbox is checked
• srv_skinbrowser2: Browse and switch WinAmp skins from the Media Library using thumbnails!
  • Presumes the Skins directory is next to the Plugins directory
  • Updates the filelist with newly appeared files and thumbnails every second
  • Automatically applies newly added skins if checkbox is checked
• srv_skinmuseum: Browse the WinAmp Skin Museum right from the Media Library
  • Double click to download and set a skin
  • Click "Keep current skin" to copy the last set skin from the current page to your Skins directory
    • This only works if you have Write rights to the directory
• srv_steamimport: Import the soundtracks you downloaded on steam to the Local Library or into individual playlists!
• srv_heritageskins: Browse the WinAmp Heritage Skin colleciton right from the Media Library
  • Double click to download and set a skin
  • Click "Keep current skin" to copy the last set skin from the current page to your Skins directory
    • This only works if you have Write rights to the directory
  • Default category can be set in the config file
• srv_screensavers: Watch screensavers in the Media Library
• wsrv_youtube: Browser YouTube through the website, but open videos in the player
• srv_archiveskins: Browse the Archive.org Winamp Skins Collection right from the Media Library
  • Double click to download and set a skin
  • Click "Keep current skin" to copy the last set skin from the current page to your Skins directory
    • This only works if you have Write rights to the directory

Common operation:

• Most plguins, including the main ml_easysrv plugin, can be configured by editing the easysrv.ini file
• Downloaded files and saved credentials are stored in System.IO.Path.GetTempPath(), unless specified otherwise

Known problems

esrv_soundcloud and msrv_soundcloud_plus are inoperable, though wsrv_soundcloud still seems to work.

Screenshot