[Doc] #234 Add Documentation for the player modularity

Docs/player.md

@@ -1,3 +1,44 @@
 # Players
 
 With Kalliope project, you can set whatever Sound Player you want to use.
+
+## Settings
+
+The setting.yml defines the Player you want to use by default
+```yml
+default_player: "type default player here"
+```
+
+Then, still in the settings.yml file, each Player must set up its configuration following the 'players' tag :
+```yml
+players:
+   - player1:
+      player1parameter1: "value option1"
+      player1parameter2: "value option2"
+   - player2:
+      player2parameter1: "value option1"
+```
+Sometime, parameters will be necessary to use an engine. 
+Click on a Player engine link in the `Current CORE Available Players` section to know which parameter are required.
+
+## Current CORE Available Players
+
+Core players are already packaged with the installation of Kalliope an can be used out of the box. See the [complete list here](player_list.md).
+
+## Full Example
+
+In the settings.yml file :
+
+```yml
+default_player: "mplayer"
+
+players:
+  - mplayer: {}
+  - pyalsaaudio:
+     device: "default"
+     convert_to_wav: True
+  - pyaudioplayer:
+     convert_to_wav: True
+  - sounddeviceplayer:
+     convert_to_wav: True
+```

Docs/player_list.md

@@ -0,0 +1,21 @@
+# List of available Player
+
+A player is a module that Kalliope will use when playing a sound. 
+You can define them in your [settings.yml file](settings.md). 
+See the [complete player documentation](player.md) for more information.
+
+## Core Players
+Core Players are already packaged with the installation of Kalliope an can be used out of the box.
+
+|        Name       | Description                                                                    | Note                |
+|-------------------|--------------------------------------------------------------------------------|---------------------|
+| mplayer           | [mplayer](http://www.mplayerhq.hu/design7/news.html)                           |                     |
+| AlsaAudioPlayer   | [AlsaAudioPlayer](https://larsimmisch.github.io/pyalsaaudio/libalsaaudio.html) | Does not handle mp3 |
+| PyAudioPlayer     | [PyAudioPlayer](https://people.csail.mit.edu/hubert/pyaudio/)                  | Does not handle mp3 |
+| SoundDevicePlayer | [SoundDevicePlayer](https://pypi.python.org/pypi/sounddevice)                  | Does not handle mp3 |
+
+## Community Players
+Community Players need to be installed manually.
+
+Wanna add your Player in the list? Open [an issue](../../issues) and send a pull request to update the list directly.
+

Docs/stt.md

@@ -23,7 +23,7 @@ speech_to_text:
    - STT2:
       STT2parameter1: "value option1"
 ```
-Sometime, an API key will be necessary to use an engine. Click on a TTS engine link in the `Current Available STT` section to know which parameter are required.
+Sometime, an API key will be necessary to use an engine. Click on a TTS engine link in the `Current CORE Available STT` section to know which parameter are required.
 
 ## Current CORE Available STT
 

kalliope/players/mplayer/README.md

@@ -0,0 +1,11 @@
+### Mplayer
+
+This Player is based on the [mplayer engine](http://www.mplayerhq.hu/design7/news.html)
+
+| Parameters | Required | Default | Choices    | Comment |
+|------------|----------|---------|------------|---------|
+|
+#### Notes
+
+This Player handles mp3 and wav format.
+

kalliope/players/pyalsaaudio/README.md

@@ -0,0 +1,15 @@
+### PyAlsaAudio
+
+This Player is based on the [alsa engine](https://larsimmisch.github.io/pyalsaaudio/libalsaaudio.html)
+
+| AlsaAudioPlayer |          |           |             |                                   |
+|-----------------|----------|-----------|-------------|-----------------------------------|
+| Parameters      | Required | Default   | Choices     | Comment                           |
+| device          | No       | "default" |             | Select the device to use for alsa |
+| convert_to_wav  | No       | TRUE      | True, False | convert the file into wav         |
+
+#### Notes
+
+Ability to define the device to use.
+This Player does not handle mp3 format, converting mp3 to wav might be required.
+

kalliope/players/pyaudioplayer/README.md

@@ -0,0 +1,13 @@
+### PyAudioPlayer
+
+This Player is based on the [pyaudio engine](https://people.csail.mit.edu/hubert/pyaudio/)
+
+| PyAudioPlayer |          |           |             |                           |
+|-----------------|----------|-----------|-------------|---------------------------|
+| Parameters      | Required | Default   | Choices     | Comment                   |
+| convert_to_wav  | No       | TRUE      | True, False | convert the file into wav |
+
+#### Notes
+
+This Player does not handle mp3 format, converting mp3 to wav might be required.
+

kalliope/players/sounddeviceplayer/README.md

@@ -0,0 +1,13 @@
+### SoundDevicePlayer
+
+This Player is based on the [sounddevice and soundfile engines](https://pypi.python.org/pypi/sounddevice)
+
+| SoundDevicePlayer |          |           |             |                           |
+|-----------------|----------|-----------|-------------|---------------------------|
+| Parameters      | Required | Default   | Choices     | Comment                   |
+| convert_to_wav  | No       | TRUE      | True, False | convert the file into wav |
+
+#### Notes
+
+This Player does not handle mp3 format, converting mp3 to wav might be required.
+