Add Readme, Changelog, and License (#7)

* Initial readme commit

* Add '.' and change android min studio version to 3.6+

* First draft of the Getting Started section

* Add changelog

* Add getting started section to changelog [skip ci]

Co-authored-by: Aaron Alaniz <[email protected]>

Author: John Qualls

CHANGELOG.md

@@ -0,0 +1,60 @@
+# Change Log
+
+### 0.1.0
+
+This release marks the first iteration of the AudioSwitch library: an Android audio management library for real-time communication apps.
+
+This initial release comes with the following features:
+
+-  Manage [audio focus](https://developer.android.com/guide/topics/media-apps/audio-focus) for typical VoIP and Video conferencing use cases.
+-  Manage audio input and output devices.
+    -  Detect changes in available audio devices
+    -  Enumerate audio devices
+    -  Select an audio device
+
+## Getting Started
+
+To get started using this library, follow the steps below.
+
+### AudioDeviceSelector Setup
+Instantiate an instance of the [AudioDeviceSelector](audioswitch/src/main/java/com/twilio/audioswitch/selection/AudioDeviceSelector.kt) class, passing a reference to the application context.
+
+```
+val audioDeviceSelector = AudioDeviceSelector(applicationContext)
+```
+
+### Listen for Devices
+To begin listening for live audio device changes, call the start function and pass a lambda that will receive [AudioDevices](audioswitch/src/main/java/com/twilio/audioswitch/selection/AudioDevice.kt) when they become available.
+
+```
+audioDeviceSelector.start { audioDevices, selectedDevice ->
+    // TODO update UI with audio devices
+}
+```
+You can also retrieve the available and selected audio devices manually at any time by calling the following properties:
+```
+val devices: List<AudioDevice> = audioDeviceSelector.availableAudioDevices
+val selectedDevice: AudioDevice? = audioDeviceSelector.selectedAudioDevice
+```
+**Note:** Don't forget to stop listening for audio devices when no longer needed in order to prevent a memory leak.
+```
+audioDeviceSelector.stop()
+```
+
+### Select a Device
+Before activating an AudioDevice, it needs to be selected first.
+```
+devices.find { it is AudioDevice.Speakerphone }?.let { audioDeviceSelector.selectDevice(it) }
+```
+If no device is selected, then the library will automatically select a device based on the following priority: `BluetoothHeadset -> WiredHeadset -> Earpiece -> Speakerphone`.
+
+### Activate a Device
+Activating a device acquires audio focus with [voice communication usage](https://developer.android.com/reference/android/media/AudioAttributes#USAGE_VOICE_COMMUNICATION) and begins routing audio input/output to the selected device.
+```
+audioDeviceSelector.activate()
+```
+Make sure to revert back to the prior audio state when it makes sense to do so in your app.
+```
+audioDeviceSelector.deactivate()
+```
+**Note:** The `stop()` function will call `deactivate()` before closing AudioDeviceSelector resources.

LICENSE renamed to LICENSE.txt

@@ -178,15 +178,15 @@
    APPENDIX: How to apply the Apache License to your work.
 
       To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
+      boilerplate notice, with the fields enclosed by brackets "{}"
       replaced with your own identifying information. (Don't include
       the brackets!)  The text should be enclosed in the appropriate
       comment syntax for the file format. We also recommend that a
       file or class name and description of purpose be included on the
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2020 Twilio, inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,2 +1,72 @@
-# audioswitch
-An Android audio management library for building real-time communication apps.
+# AudioSwitch
+
+[![CircleCI](https://circleci.com/gh/twilio/audioswitch.svg?style=svg)](https://circleci.com/gh/twilio/audioswitch)
+
+An Android audio management library for real-time communication apps.
+
+![video-app-screenshots](images/audioswitch-logo.png)
+
+## Features
+
+- [x] Manage [audio focus](https://developer.android.com/guide/topics/media-apps/audio-focus) for typical VoIP and Video conferencing use cases.
+- [x] Manage audio input and output devices.
+    - [x] Detect changes in available audio devices
+    - [x] Enumerate audio devices
+    - [x] Select an audio device
+
+## Requirements
+
+Android Studio Version | Android API Version Min
+------------ | -------------
+3.6+ | 16
+
+## Getting Started
+
+To get started using this library, follow the steps below.
+
+### AudioDeviceSelector Setup
+Instantiate an instance of the [AudioDeviceSelector](audioswitch/src/main/java/com/twilio/audioswitch/selection/AudioDeviceSelector.kt) class, passing a reference to the application context.
+
+```
+val audioDeviceSelector = AudioDeviceSelector(applicationContext)
+```
+
+### Listen for Devices
+To begin listening for live audio device changes, call the start function and pass a lambda that will receive [AudioDevices](audioswitch/src/main/java/com/twilio/audioswitch/selection/AudioDevice.kt) when they become available.
+
+```
+audioDeviceSelector.start { audioDevices, selectedDevice ->
+    // TODO update UI with audio devices
+}
+```
+You can also retrieve the available and selected audio devices manually at any time by calling the following properties:
+```
+val devices: List<AudioDevice> = audioDeviceSelector.availableAudioDevices
+val selectedDevice: AudioDevice? = audioDeviceSelector.selectedAudioDevice
+```
+**Note:** Don't forget to stop listening for audio devices when no longer needed in order to prevent a memory leak.
+```
+audioDeviceSelector.stop()
+```
+
+### Select a Device
+Before activating an AudioDevice, it needs to be selected first.
+```
+devices.find { it is AudioDevice.Speakerphone }?.let { audioDeviceSelector.selectDevice(it) }
+```
+If no device is selected, then the library will automatically select a device based on the following priority: `BluetoothHeadset -> WiredHeadset -> Earpiece -> Speakerphone`.
+
+### Activate a Device
+Activating a device acquires audio focus with [voice communication usage](https://developer.android.com/reference/android/media/AudioAttributes#USAGE_VOICE_COMMUNICATION) and begins routing audio input/output to the selected device.
+```
+audioDeviceSelector.activate()
+```
+Make sure to revert back to the prior audio state when it makes sense to do so in your app.
+```
+audioDeviceSelector.deactivate()
+```
+**Note:** The `stop()` function will call `deactivate()` before closing AudioDeviceSelector resources.
+
+## License
+
+Apache 2.0 license. See [LICENSE.txt](LICENSE.txt) for details.