From b5dc520d1fbbfdc1881eb605df15638a5f07a979 Mon Sep 17 00:00:00 2001
From: Mark Heath <mark.heath@gmail.com>
Date: Thu, 30 Nov 2017 18:55:00 +0000
Subject: [PATCH] ASIO playback documentation

---
 Docs/AsioPlayback.md | 62 ++++++++++++++++++++++++++++++++++++++++++++
 NAudio.sln           |  1 +
 README.md            |  1 +
 3 files changed, 64 insertions(+)
 create mode 100644 Docs/AsioPlayback.md

diff --git a/Docs/AsioPlayback.md b/Docs/AsioPlayback.md
new file mode 100644
index 00000000..7074ef55
--- /dev/null
+++ b/Docs/AsioPlayback.md
@@ -0,0 +1,62 @@
+# Playback with ASIO
+
+The `AsioOut` class in NAudio allows you to both play back and record audio using an ASIO driver. ASIO is a driver format supported by many popular Digital Audio Workstation (DAW) applications on Windows, and usually offers very low latency for record and playback. 
+
+To use ASIO, you do need a soundcard that has an ASIO driver. Most professional soundcards have ASIO drivers, but you can also try the [ASIO4ALL](http://asio4all.com/) driver which enables ASIO for soundcards that don't have their own native ASIO driver.
+
+The `AsioOut` class is able to play, record or do both simultaneously. This article covers the scenario where we just want to play audio.
+
+## Opening an ASIO device for playback
+
+To discover the names of the installed ASIO drivers on your system you use `AsioOut.GetDriverNames()`.
+
+We can use one of those driver names to pass to the constructor of `AsioOut`
+
+```c#
+var asioOut = new AsioOut(asioDriverName);
+```
+
+## Selecting Output Channels
+
+Pro Audio soundcards often support multiple inputs and outputs. We may want to find out how many output channels are available on the device. We can get this with:
+
+```c#
+var outputChannels = asioOut.DriverOutputChannelCount;
+```
+
+By default, `AsioOut` will send the audio to the first output channels on your soundcard. So if you play stereo audio through a four channel soundcard, the samples will come out of the first two channels. If you wanted it to come out of different channels you can adjust the `OutputChannelOffset` parameter.
+
+Next, I call `Init`. This lets us pass the `IWaveProvider` or `ISampleProvider` we want to play. Note that the sample rate of the `WaveFormat` of the input provider must be one supported by the ASIO driver. Usually this means 44.1kHz or higher.
+
+
+```c#
+// optionally, change the starting channel for outputting audio:
+asioOut.OutputChannelOffset = 2;  
+asioOut.Init(mySampleProvider);
+```
+
+## Start Playback
+
+As `AsioOut` is an implementation of `IWavePlayer` we just need to call `Play` to start playing.
+
+```c#
+asioOut.Play(); // start playing
+```
+
+Note that since ASIO typically works at very low latencies, it's important that the components that make up your signal chain are able to provide audio fast enough. If the ASIO buffer size is say 10ms, that means that every 10ms you need to generate the next 10ms of audio. If you miss this window, the audio will gitch.
+
+## Stop Playback
+
+We stop recording by calling Stop().
+
+```c#
+asioOut.Stop();
+```
+
+As with other NAudio `IWavePlayer` implementations, we'll get a `PlaybackStopped` event firing when the driver stops.
+
+And of course we should remember to `Dispose` our instance of `AsioOut` when we're done with it.
+
+```c#
+asioOut.Dispose();
+```
\ No newline at end of file
diff --git a/NAudio.sln b/NAudio.sln
index 8b9c9f77..112b0412 100644
--- a/NAudio.sln
+++ b/NAudio.sln
@@ -32,6 +32,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Samples", "Samples", "{778D
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Docs", "Docs", "{BA7F6DBB-9FC4-49E6-92E4-621EFE4BBBBC}"
 	ProjectSection(SolutionItems) = preProject
+		Docs\AsioPlayback.md = Docs\AsioPlayback.md
 		Docs\AsioRecording.md = Docs\AsioRecording.md
 		Docs\ConcatenatingAudio.md = Docs\ConcatenatingAudio.md
 		Docs\ConvertBetweenStereoAndMono.md = Docs\ConvertBetweenStereoAndMono.md
diff --git a/README.md b/README.md
index 70df1649..e353a88b 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,7 @@ NAudio comes with several demo applications which are the quickest way to see ho
  - [Play streaming MP3](http://markheath.net/post/how-to-play-back-streaming-mp3-using)
  - [Handling playback stopped](Docs/PlaybackStopped.md)
  - [Understanding WaveStream, IWavePlayer and ISampleProvider](Docs/WaveProviders.md)
+ - [Playing Audio with ASIO](Docs/AsioPlayback.md)
 
 ### Working with Codecs