Kernel Streaming Output Plugin V2.5
===================================

Contents
========

1. Background
2. Features
3. Configuration
4. Known Issues
5. Please Note
6. Credits
7. Revision History (2.0 onwards)



1. Background
=============

Kernel Streaming is a method of sending digital audio data to an audio device that
bypasses Windows' KMixer. KMixer takes audio feeds from any program attempting to
output sounds and mixes them together before outputting the mixed signal to the
computers sound card. In order to make this process more achievable, the varios
streams of data get resampled to a single sample frequency, typically 48KHz before
being passed on to the sound card. In general this process is acceptable, but for
high fidelity applications it is not desirable. In these situations it is preferable
to keep all signals in their original format right through the chain and this is
where Kernel Streaming comes in. As it bypasses KMixer, this stage of resampling is
avoided and, assuming the sound card and driver are capable of handling it, the audio
stream is passed through to the ouput (either DAC's or SPDIF) without modification.

Bear in mind that not all cards are capable of this and some cards will always internally
resample audio to a specific frequency (Creative's Soundblaster range are well documented
for doing this).

For my purposes, I wanted to be able to play HDCD tracks from my media PC and decode the
HDCD data with my external HiFi processor. For this to work, the bitstream coming out of
the PC must be a perfectly uncorrupted copy of the original data for the HDCD decoder to
recognise that it is indeed dealing with HDCD data so I started using Chun-Yu's original
WinAmp plugin with my M-Audio Audiophile 2496 cards SPDIF output. While this allowed me
to get an uncorrupted bitstream through to the HDCD processor, it made my system very
unstable resulting in some very unpleasant crashes. Fortunately, Chun-Yu had also posted
his source code, so I was able to rewrite the core routines of the plugin to address
these stability issues. Since then, various people have asked about other features and
there have been things about the plugin that have personally annoyed me, which leads us
to this release.

I believe I have now catered for most of the features that people requested and in my
own testing stability no longer seems to be an issue.


2. Features
===========

The plugin now has the following features;

Kernel streaming for 16 and 24 bit audio data - bypasses KMixer and allows unmodified
output via DAC and SPDIF where hardware and drivers permit

Output device may be selected via the Config screen. Now uses friendly device names.

Optional volume control - the WinAmp volume control will now work with this plugin
when playing 16 and 24 bit audio data. The code that attenuates the data is bypassed
when the volume control is set to 100%, thereby maintaining an un-modified data stream.
In addition, the volume control can be completely disabled in the Config screen to ensure
it has no effect where it is not needed and a pure data stream is required.
By default, the volume control is disabled.

The Audio Device is now released at the end of tracks or when playback is stopped
(but not when paused). This behaviour can be disabled by unchecking the "Release Audio
Device When Stopped" option in the Config screen. If this feature is disabled,
the plugin will accquire the Audio Device when the first track is played and will not
release it until WinAmp is closed down. In many systems, this will prevent any other
program from being able to output any audio while WinAmp is running, in addition,
switching to another output plugin will fail because WinAmp does not notify the current
output plugin that it is no longer selected, as a result, the Kernel Streaming plugin
will keep hold of the output device even though it is no longer being used, this stops
any other output plugin from getting hold of it and will result in an error. Unless you
experience any stability issues it is recommended that you leave this option checked as
it integrates better alongside other plugins and applications.

An optional oversampling filter has been added, this adds a linear interpolation filter
to 2x the current sample rate for input signals of up to 48KHz (so, 44,100 becomes 88,200
and 48,000 becomes 96,000). In my own tests with my Tag DAC I cannot perceive any noticable
difference with this feature enabled or disabled however it may give audible benefits
in some systems. This feature is only available for 16 bit audio.

Note that activating either the oversampling filter or the volume control will prevent
HDCD data from being decoded by an external decoder. If you play a lot of HDCD and want
to get the best from them, then I would recommend leaving both of these features disabled.


3. Configuration
================

The plugin defaults to the following settings;

Output Device                     - first one in system list
Volume Control                    - disabled
Release Audio Device When Stopped - Yes
Oversampler                       - Off

These can all be changed by entering the Config screen, making your selections then
pressing "Ok".


4. Known Issues
===============

At present the plugin will keep hold of the audio device when paused, this means that the
kind of issues mentioned above regarding other programs trying to generate sound still
apply when paused. The plugin will only release the audio device when;

1. Winamp is closed.
2. When a track ends or Stop is pressed (only when "Release Audio Device When Stopped" is
   checked in the Config screen).
3. When the output format changes, however it will immediately re-acquire it after this.

Because of the above issue, having "Release Audio Device When Stopped" un-checked and
attempting to swap to another output plugin may generate an error from the other plugin
because the Kernel Streaming plugin still holds the audio device. If you do swap to another
output plugin, it is highly recommended that you shut down and restart WinAmp before
attempting to play any further tracks.

Audio device enumeration can pick up some devices that are not suitable for output, the
plug-in will pop up an "unable to create output pin" error when you select such a device
and try to play. If this happens, simply select another device and try again. Note, that
Winamp will attempt to play each track in your playlist when this kind of error happens,
so it's best to try swapping output devices with just one track in the playlist.

The plugin does not check if sampling frequencies higher than 48KHz are supported, so
activating the oversampler may cause an error. In this instance, please deactivate this
feature.

The plugin does not check if sample sizes greater than 16 bit are supported, so attempting
to play media of this type on hardware that does not support it will result in an error.



5. Please Note
==============

This plugin is supplied "as is", it is, to the best of my knowledge robust and reliable, but
you use it entirely at your own risk.

6. Credits
==========

Original Kernel Streaming Plugin developed and written by Chun-Yu Shei - Copyright 2002

Version 2.0 onwards rewritten and maintained by Steve Monks - Copyright 2005

7. Revision History
===================

2.0 - Initial revision. Fixed most stability issues and added a config screen to allow selection
      of output device.

2.1 - Fixed crash on pause bug

2.2 - Fixed confusion when paused - plugin could lose track of pause status requiring several presses
      of pause button to get it going again.
      Fixed problem from original plugin where certain tracks would stop at the end rather than
      advancing to the next track in the play list.

2.3 - Added a volume control for 8/16 bit audio
      Added option to release output device when stopped
      Changed config list box to use "friendly names" rather than device paths

2.4 - Fixed bug where all settings would disappear from the config screen if no tracks were playing
      and "Release Audio Device When Stopped" was checked.
      Added experimental oversampler.

2.5 - Fixed incompatibility with streaming media (e.g. internet radio)
      Added support for 24 bit playback of 24 bit stereo media