Yet Another (WA)SAPI Output Plugin for Winamp (YASAPI)

The "Yet Another (WA)SAPI Output Plugin for Winamp" (YASAPI) utilizes the "Windows Audio Session API" (WASAPI). WASAPI's exclusive mode for rendering audio is a native way on Windows to render audio undisturbed, similar to Steinberg's "Audio Stream Input/Output" (ASIO). The YASAPI output plugin may serve as a replacement for any other Winamp output plugin.

Home:		http://out-yasapi.sourceforge.net/
Project:		http://sourceforge.net/projects/out-yasapi/
Download:		http://sourceforge.net/projects/out-yasapi/files/out-yasapi/
Winamp Forum:		http://forums.winamp.com/showthread.php?t=380396
Input Plugin:		http://in-ffsox.sourceforge.net/

Content

1. History
2. Introduction
3. Implementation
4. Configuration
5. Debug

The Core Audio APIs were introduced in Windows Vista. This is a new set of user-mode audio components provides client applications with improved audio capabilities. These capabilities include the following:

• Low-latency, glitch-resilient audio streaming.
• Improved reliability (many audio functions have moved from kernel mode to user mode).
• Improved security (processing of protected audio content takes place in a secure, lower-privilege process).
• Assignment of particular system-wide roles (console, multimedia, and communications) to individual audio devices.
• Software abstraction of the audio endpoint devices (for example, speakers, headphones, and microphones) that the user manipulates directly.

https://msdn.microsoft.com/en-us/library/windows/desktop/dd370784%28v=vs.85%29.aspx

Of special interest is that there is an exclusive mode for rendering audio, i.e. there is a mode where an application has exclusive access to the audio device without being disturbed by third parties.

The aim of the YASAPI plugin is to make the WASAPI exclusive mode for audio rendering available to the users of Winamp.

The name of the plugin was choosen because there are already at least two WASAPI output plugins for Winamp:

• Maiko WASAPI output plugin
• adionSoft Winamp WASAPI Output Plugin

The implementation on the WASAPI side follows along the lines of an example provided by Microsoft. The startegy shown in this example is not only applicable for shared mode streams but also for exclusive mode ones, i.e. not the share mode should be emphasized but what is known as the push model. There is also an example demonstrating the pull model in conjunction with the exclusive mode. In that sence there are four strategies:

• push exclusive,
• push shared,
• plull exclusive, and
• plull shared.

The YASAPI plugin implements the first two strategies, i.e. the ones based on the push model.

The push model, in principle, works as follows:

1. Query the size of the buffer shared with the audio device.
2. Fill in completety the buffer shared with the audio device.
3. Start playing.
4. Loop until the track is played:
   1. Sleep half of the time corresponding to the size of the buffer shared with the audio device.
   2. Into the buffer shared with the audio device, fill in the gap which was growing free by playing during sleep.
5. Sleep until the possibly remaining filled rest of the buffer shared with the audio device was played.
6. Stop playing.

The YASAPI plugin decouples the two sides by means of a ring or circular buffer. That way,

• Winamp can luckily write to the ring buffer whenever it likes without caring about WASAPI, and
• WASAPI can luckily read from the ring buffer and write to the audio device wehenever it likes without caring about Winamp.

According to step 2 of the push model sketched above, it shoud become clear that the ring buffer should be at least as large (or larger) as the buffer the plugin's WASAPI component shares with the audio device.

4. Configuration

The YASAPI plugin comes with a configuration dialog which is described in the following. The dialog's top region presents the two most important parameters "Mode" (exclusive or share) and "Strategy" (push or pull)

Below those two parameters you find a tab-control consisting of four pages,

• a page for setting general (i.e. non device dependent) parameters,
• a page for choosing the device, and
• two pages for setting per device parameters.

The tab-control's first page looks as follows:

It let's you configure

• whether mono should be treated as stereo (i.e. the one mono channel should be duplicated),
• whether Winamp's volume control should be enabled, and
• whether the IAudioClock interface (WASAPI) or the GetTickCount function (System) should be used for synchronizing with Winamp.

On the next page there are the following per device options:

• the share mode, either exlusive, shared or automatic (automatic is similar to exclusive, except in case exclusive fails it falls back to shared), in case shared or automatic mode is choosen
  • whether the audio should be automatically re-sampled,
  • whether a more accurate re-sampling algorithmen should be applied, and finally
• the strategy, either push or pull.

On the final page you can configure the following per device buffer sizes:

• the duration of the buffer shared with the audio device (device period),
• the size of the ring buffer which should be a (small) multiple of the buffer the plugin's WASAPI component shares with the audio device, and
• the number of samples which should be available in the ring buffer before playing starts.

From the above sketch of the push model it shold be clear that the following relation holds (which is enforced by the configuration dialog):

minimum size of the buffer shared with the device (provided by WASAPI) <= size of buffer shared with the device <= number of samples in the ring buffer before start playing <= size of ring buffer

Please note that no option takes effect before hitting the OK button.

5. Debug

In case something went wrong you may be interested in some more information. In order to utilize this there is a debug version of the plugin (distinguished by a lower case "d" at the and of the name, i.e. out_yasapid.dll) available from the download site.

Do the following:

1. Close Winamp.
2. Copy "out_yasapi-debug.dll" to Winamp's "Plugin" folder.
3. Start Winamp.
4. A console window should pop up tracing the initialiazation of the debug YASAPI plugin.
5. From Winamps's preferences dialog choose "out_yasapi-debug.dll" as output plugin.
6. When playing tracks in Winamp, the debug YASAPI plugin traces initialization and cleanup of each track.
7. When shutting down Winamp, the cleanup of the YASAPI debug plugin is traced.
8. After closing Winamp, the console window remains visible for another 5 s before vanishing.

The debug console.

You can get rid of the debug console by choosing the respective "Console" option from the debug YASAPI plugin's configuration dialog:

The following debug options can be configured:

• whether the debug console is switched Off or on and displaying a trace in Default or Verbose mode, and
• how long closing the debug console should be delayed from closing Winamp.