Add microphone array configuration

Author: mswellsi

articles/cognitive-services/Speech-Service/devices-sdk-release-notes.md

@@ -19,6 +19,7 @@ The following sections list changes in the most recent releases.
 
 ## Speech Devices SDK 1.11.0:
 
+- Support for [arbitrary microphone array geometries](how-to-devices-microphone-array-configuration.md) and setting the working angle through a [configuration file](https://aka.ms/sdsdk-micarray-json).
 - Support for [Urbetter DDK](http://www.urbetter.com/products_56/278.html).
 - Released binaries for the [GGEC Speaker](https://aka.ms/sdsdk-download-speaker) used in our [Voice Assistant sample](https://aka.ms/sdsdk-speaker).
 - Released binaries for [Linux ARM32](https://aka.ms/sdsdk-download-linux-arm32) and [Linux ARM 64](https://aka.ms/sdsdk-download-linux-arm64) for Raspberry Pi and similar devices.

articles/cognitive-services/Speech-Service/how-to-devices-microphone-array-configuration.md

@@ -0,0 +1,110 @@
+---
+title: How to configure a Microphone Array - Speech Service
+titleSuffix: Azure Cognitive Services
+description: Learn how to configure a Microphone Array so that the Speech Devices SDK can utilize it.
+services: cognitive-services
+author: mswellsi
+manager: yanbo
+ms.service: cognitive-services
+ms.subservice: speech-service
+ms.topic: conceptual
+ms.date: 05/01/2020
+ms.author: wellsi
+---
+
+# How to configure a Microphone Array
+
+In this article, you learn how to configure a [microphone array](https://aka.ms/sdsdk-microphone), including setting the working angle, and how to select which microphone is used for the Speech Devices SDK.
+
+The Speech Devices SDK works best with a microphone array that has been designed according to [our guidelines](https://aka.ms/sdsdk-microphone), and either exposes the microphone array configuration or the configuration is supplied through one of the following methods.
+
+The Speech Devices SDK initially supported microphone arrays by selecting from a fixed set of configurations.
+
+```java
+private static String DeviceGeometry = "Circular6+1"; // "Circular6+1", "Linear4",
+private static String SelectedGeometry = "Circular6+1"; // "Circular6+1", "Circular3+1", "Linear4", "Linear2"
+```
+
+On Windows the microphone array configuration is supplied by the audio driver.
+
+From v1.11.0 The Speech Devices SDK also supports configuration from a [JSON file](https://aka.ms/sdsdk-micarray-json).
+
+
+## Windows
+On Windows the microphone array geometry information is automatically obtained from the audio driver. So, the properties `DeviceGeometry` and `SelectedGeometry` as well as the new property `MicArrayGeometryConfigFile` are optional. We use the [JSON file](https://aka.ms/sdsdk-micarray-json) provided using `MicArrayGeometryConfigFile` for only getting the beamforming range.
+
+If a microphone array is specified using `AudioConfig::FromMicrophoneInput`, then we use the specified microphone. If microphone is not specified or `AudioConfig::FromDefaultMicrophoneInput` is called, then we use the default microphone which is specified in Sound settings on Windows.
+The Microsoft Audio Stack in the Speech Devices SDK only supports down sampling for sample rates that are integral multiples of 16KHz.
+
+## Linux
+On Linux the microphone geometry information must be provided. The use of `DeviceGeometry` and `SelectedGeometry` remains supported. It can also be provided via the JSON file using the `MicArrayGeometryConfigFile` property. Similar to Windows, the beamforming range cane be provided by the JSON file.
+
+If a microphone array is specified using `AudioConfig::FromMicrophoneInput`, then we use the specified microphone. If a microphone is not specified or `AudioConfig::FromDefaultMicrophoneInput` is called, then we record from ALSA device named *default*. By default, *default* always points to card 0 device 0, but users can change it in the `asound.conf` file. 
+
+The Microsoft Audio Stack in the Speech Devices SDK only supports downsampling for sample rates that are integral multiples of 16KHz. Additionally the following formats are supported: 32-bit IEEE little endian float, 32-bit little endian signed int, 24-bit little endian signed int, 16-bit little endian signed int and 8-bit signed int.
+
+## Android
+Currently only [Roobo v1](speech-devices-sdk-android-quickstart.md) is supported by te Speech Devices SDK. Behavior is same as previous releases, except now `MicArrayGeometryConfigFile` property can be used to specify JSON file containing beamforming range.
+
+## Microphone Array Configuration JSON
+
+The [JSON file](https://aka.ms/sdsdk-micarray-json) for microphone array geometry configuration will follow the JSON schema. Following are some examples that follow the schema.
+
+
+```json
+{
+    "micArrayType": "Linear",
+    "geometry": "Linear4"
+}
+```
+
+
+Or
+
+
+```json
+{
+    "micArrayType": "Planar",
+    "horizontalAngleBegin": 0,
+    "horizontalAngleEnd": 360,
+    "numberOfMicrophones": 4,
+    "micCoord": [
+        {
+            "xCoord": 0,
+            "yCoord": 0,
+            "zCoord": 0
+        },
+        {
+            "xCoord": 40,
+            "yCoord": 0,
+            "zCoord": 0
+        },
+        {
+            "xCoord": -20,
+            "yCoord": -35,
+            "zCoord": 0
+        },
+        {
+            "xCoord": -20,
+            "yCoord": 35,
+            "zCoord": 0
+        }
+    ]
+}
+```
+
+Or
+
+```json
+{
+    "micArrayType": "Linear",
+    "horizontalAngleBegin": 70,
+    "horizontalAngleEnd": 110
+}
+```
+
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Choose your speech device](get-speech-devices-sdk.md)

articles/cognitive-services/Speech-Service/toc.yml

@@ -519,6 +519,10 @@
           href: speech-devices-sdk-roobo-v1.md
         - name: Roobo v2 details
           href: speech-devices-sdk-roobo-v2.md
+    - name: How-to guides
+      items:
+        - name: How to configure a Microphone Array
+          href: how-to-devices-microphone-array-configuration.md
     - name: Quickstart
       items:
         - name: Use Speech devices SDK