ソースを参照

[Doc] #136 #138 : Add contributing docs to create a stt and tts + lists + templates

monf 8 年 前
コミット
b24d7dc135

+ 2 - 2
Docs/contributing/contribute_neuron.md

@@ -6,7 +6,7 @@ Creating a new Neuron must follow some rules:
 
 ## Repository Structure
 1. The Neuron repository name is in __lowercase__.
-1. Under the Neuron repository, the Neuron has a __README.md file__ describing the Neuron following this structure. You can get a [template here](../neuron_template.md):
+1. Under the Neuron repository, the Neuron has a __README.md file__ describing the Neuron following this structure. You can get a [template here](neuron_template.md):
     - Neuron name:
     - Installation:     The CLI command used to install the neuron
     - Synopsis:         Description of the Neuron
@@ -15,7 +15,7 @@ Creating a new Neuron must follow some rules:
     - Synapses example: An example of how to use the Neuron inside a Synapse.
     - Notes:            Something which needs to be add.
 1. Under the Neuron repository, include a __Tests repository__ to manage the test of the Neuron.
-1. Under the neuron repository, a [dna.yml file](dna.md) must be added that contains information about the neuron.
+1. Under the neuron repository, a [dna.yml file](dna.md) must be added that contains information about the neuron. type = "neuron"
 1. Under the neuron repository, a [install.yml file](installation_file.md) must be added that contains the installation process.
 
 

+ 77 - 1
Docs/contributing/contribute_stt.md

@@ -1 +1,77 @@
-# Contributing: Create a STT
+# Contributing: Create a STT
+
+[STT](../stt.md) are independent projects so they can be developed under a github project. 
+Anyone can clone them and place them under the STT repository and reuse them or directly [install](../stt.md) them
+
+Creating a new STT must follow some rules:
+
+## Repository Structure
+1. The STT repository name is in __lowercase__.
+1. Under the STT repository, the STT has a __README.md file__ describing the STT following this structure. You can get a [template here](stt_template.md):
+    - STT name:
+    - Installation:     The CLI command used to install the STT
+    - Synopsis:         Description of the STT
+    - Options:          A table of the incoming parameters managed by the STT.
+    - Notes:            Something which needs to be add.
+    - Licence:          The licence you want to use
+1. Under the STT repository, a [dna.yml file](dna.md) must be added that contains information about the STT. type = "stt"
+1. Under the STT repository, a [install.yml file](installation_file.md) must be added that contains the installation process.
+
+
+## Code
+1. Under the STT repository, the STT file name .py is also in __lowercase__.
+1. The STT must be coded in __Python 2.7__.
+1. Under the STT repository, include the __init__.py file which contains: *from stt import STT* (/!\ respect the Case)
+1. Inside the STT file, the STT Class name is in __uppercase__.
+1. The STT __inherits from the OrderListener__ coming from the Core.
+
+    ```
+    from kalliope.core.OrderListener import OrderListener
+    class Google(OrderListener):
+    ```
+
+1. The STT has a constructor __init__ which is the entry point.
+The constructor has an incoming callback to call once we get the text.
+The constructor has a __**kwargs argument__ which is corresponding to the Dict of incoming variables:values defined either in the settings file.
+1. The STT must init itself first.
+1. Attach the incoming callback to the self.attribute.
+1. Obtain audio from the microphone in the constructor. (Note : we mostly use the [speech_recognition library](https://pypi.python.org/pypi/SpeechRecognition/))
+1. Once you get the text back, let give it to the callback
+
+    ```
+    def __init__(self, callback=None, **kwargs):
+        OrderListener.__init__(self)
+        self.callback = callback
+        # -------------------
+        # do amazing code
+        # -------------------
+        self.callback(audio_to_text)
+    ```
+
+
+
+## Code example
+
+Example of STT structure
+```
+mystt/
+├── __init__.py
+├── mystt.py
+├── dna.yml
+├── install.yml
+└── README.md
+```
+
+Example of STT code
+```
+class Mystt(OrderListener):
+def __init__(self, callback=None, **kwargs):
+        OrderListener.__init__(self)
+        self.callback = callback
+        # -------------------
+        # - get the microphone audio 
+        # - do amazing code to retrieve the text
+        # - call the callback giving it the result text -> self.callback(audio_to_text)
+        # -------------------
+        
+```

+ 90 - 1
Docs/contributing/contribute_tts.md

@@ -1 +1,90 @@
-# Contributing: Create a TTS
+# Contributing: Create a TTS
+
+[TTS](../tts.md) are independent projects so they can be developed under a github project. 
+Anyone can clone them and place them under the TTS repository and reuse them or directly [install](../tts.md) them
+
+Creating a new TTS must follow some rules:
+
+## Repository Structure
+1. The TTS repository name is in __lowercase__.
+1. Under the TTS repository, the TTS has a __README.md file__ describing the TTS following this structure. You can get a [template here](tts_template.md):
+    - TTS name:
+    - Installation:     The CLI command used to install the TTS
+    - Synopsis:         Description of the TTS
+    - Options:          A table of the incoming parameters managed by the TTS.
+    - Notes:            Something which needs to be add.
+    - Licence:          The licence you want to use
+1. Under the TTS repository, a [dna.yml file](dna.md) must be added that contains information about the TTS. type = "tts"
+1. Under the TTS repository, a [install.yml file](installation_file.md) must be added that contains the installation process.
+
+
+## Code
+1. Under the TTS repository, the TTS file name .py is also in __lowercase__.
+1. The TTS must be coded in __Python 2.7__.
+1. Under the TTS repository, include the __init__.py file which contains: *from tts import TTS* (/!\ respect the Case)
+1. Inside the TTS file, the TTS Class name is in __uppercase__.
+1. The TTS __inherits from the TTSModule__ coming from the Core.
+
+    ```
+    from kalliope.core.TTS.TTSModule import TTSModule
+    class Pico2wave(TTSModule):
+    ```
+
+
+1. The TTS has a constructor __init__ which is the entry point.
+The constructor has a __**kwargs argument__ which is corresponding to the Dict of incoming variables:values defined either in the settings file.
+1. The TTS must refer to its __parent structure__ in the init by calling the super of TTSModule.
+
+    ```
+    def __init__(self, **kwargs):
+        super(Pico2wave, self).__init__(**kwargs)
+    ```
+
+1. The TTS __must__ implements a method _say(self, words) which must run call a method coming from the mother Class self.generate_and_play(words, callback).
+1. Implement a callback in a separate method to run the audio. 
+This callback is in charge to get the sound and save it on the disk. You can use our lib "FileManager.write_in_file(file_path, content)"
+1. It also must define the attribute self.file_path with the path to this audio file.
+
+
+## Code example
+
+Example of TTS structure
+```
+mytts/
+├── __init__.py
+├── mytts.py
+├── dna.yml
+├── install.yml
+└── README.md
+```
+
+Example of TTS code
+```
+class Mytts(TTSModule):
+def __init__(self, **kwargs):
+    super(Mytts, self).__init__(**kwargs)
+    # the args from the tts configuration
+    self.arg1 = kwargs.get('arg1', None)
+    self.arg2 = kwargs.get('arg2', None)
+
+    def say(self, words):
+        """
+        :param words: The sentence to say
+        """
+
+        self.generate_and_play(words, self._generate_audio_file)
+        
+    def _generate_audio_file(self):
+    """
+    Generic method used as a Callback in TTSModule
+        - must provided the audio file and write it on the disk
+
+    .. raises:: FailToLoadSoundFile
+    """
+    # -------------------
+    # - do amazing code to get the sound 
+    # - save it to the disk using
+    # - Attach the sound file path to the attribute : self.file_path = audio_file_path !
+    # -------------------
+    
+```

+ 4 - 0
Docs/neuron_template.md → Docs/contributing/neuron_template.md

@@ -59,3 +59,7 @@ This is a var {{ var }}
 ## Notes
 
 > **Note:** This is an important note concerning the neuron
+
+## Licence
+
+Here define or link the licence you want to use.

+ 28 - 0
Docs/contributing/stt_template.md

@@ -0,0 +1,28 @@
+# Name of the STT
+
+## Synopsis
+
+Description of your STT
+
+## Installation
+
+    kalliope install --git-url "https://github.com/username/mystt.git"
+
+## Options
+
+(usage of a [table generator](http://www.tablesgenerator.com/markdown_tables) is recommended)
+
+| parameter        | required | default                       | choices                           | comments                     |
+|------------------|----------|-------------------------------|-----------------------------------|------------------------------|
+| parameter_name_1 | yes      |                               |                                   | description of the parameter |
+| parameter_name_2 | no       |                               | possible_value_1,possible_value_2 | description of the parameter |
+| parameter_name_3 | yes      | default_value_if_not_provided |                                   | description of the parameter |
+
+
+## Notes
+
+> **Note:** This is an important note concerning the neuron
+
+## Licence
+
+Here define or link the licence you want to use.

+ 18 - 2
Docs/stt.md

@@ -7,7 +7,6 @@ Each STT has a specific configuration and supports multiple languages.
 
 The configuration of each STT you use must appear in the [settings.yml](settings.md) file.
 
-
 ## Settings
 
 The setting.yml defines the STT you want to use by default
@@ -26,7 +25,8 @@ speech_to_text:
 ```
 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.
 
-## Current Available STT
+## Current CORE Available STT
+Core STTs are already packaged with the installation of Kalliope an can be used out of the box.
 
 - [apiai](../kalliope/stt/apiai/README.md)
 - [bing](../kalliope/stt/bing/README.md)
@@ -34,6 +34,22 @@ Sometime, an API key will be necessary to use an engine. Click on a TTS engine l
 - [houndify](../kalliope/stt/houndify/README.md)
 - [witai](../kalliope/stt/wit/README.md)
 
+## STT Community Installation
+
+Community STTs need to be installed manually.
+
+Use the CLI
+```
+kalliope install --git-url "<git_url>"
+```
+
+E.g:
+```
+kalliope install --git-url "https://github.com/Ultchad/kalliope-espeak"
+```
+
+You may be prompted to type your `sudo` password during the process. You can see the list of [available STT here](stt_list.md)
+
 ## Full Example
 
 In the settings.yml file :

+ 28 - 0
Docs/stt_list.md

@@ -0,0 +1,28 @@
+# List of available STT
+
+A stt is a module that Kalliope will use to speak out. You can define them in your [settings.yml file](settings.md). 
+See the [complete STT documentation](stt.md) for more information.
+
+## Core STT
+Core STTs are already packaged with the installation of Kalliope an can be used out of the box.
+
+| Name     | Description                                    |
+|----------|------------------------------------------------|
+| api.ai   | [apiai](../kalliope/stt/apiai/README.md)       |
+| bing     | [bing](../kalliope/stt/bing/README.md)         |
+| Google   | [google](../kalliope/stt/google/README.md)     |
+| Houndify | [houndify](../kalliope/stt/houndify/README.md) |
+| wit.ai   | [wit.ai](../kalliope/stt/wit/README.md)        |
+
+
+## Community STT
+Community STTs need to be installed manually.
+
+To know how to install a community STT, read the "Installation" section of the [STT documentation](stt.md).
+
+| Name     | Description                                    |
+|----------|------------------------------------------------|
+
+Wanna add your STT in the list? Open [an issue](../../issues) with the link of your STT or send a pull request to update the list directly.
+
+

+ 13 - 1
Docs/tts.md

@@ -50,6 +50,7 @@ cache_path: "/tmp/kalliope_tts_cache"
 generated audio files that will not be played more than once.
 
 ## Current Available TTS
+Core TTSs are already packaged with the installation of Kalliope an can be used out of the box.
 
 - [acapela](../kalliope/tts/acapela/README.md)
 - [googletts](../kalliope/tts/googletts/README.md)
@@ -57,6 +58,17 @@ generated audio files that will not be played more than once.
 - [voicerss](../kalliope/tts/voicerss/README.md)
 - [voxygen](../kalliope/tts/voxygen/README.md)
 
+## TTS Community Installation
+
+Community TTSs need to be installed manually.
+
+Use the CLI
+```
+kalliope install --git-url "<git_url>"
+```
+
+You may be prompted to type your `sudo` password during the process. You can see the list of [available TTS here](tts_list.md)
+
 ## Full Example
 
 ```
@@ -81,4 +93,4 @@ text_to_speech:
   - voicerss:
       language: "fr-fr"
       cache: True
-```
+```

+ 28 - 0
Docs/tts_list.md

@@ -0,0 +1,28 @@
+# List of available TTS
+
+A TTS is a module that Kalliope will use to speak out. You can define them in your [settings.yml file](settings.md). 
+See the [complete TTS documentation](stt.md) for more information.
+
+## Core TTS
+Core TTSs are already packaged with the installation of Kalliope an can be used out of the box.
+
+| Name      | Description                                      |
+|-----------|--------------------------------------------------|
+| Acapela   | [Acapela](../kalliope/tts/acapela/README.md)     |
+| GoogleTTS | [GoogleTTS](../kalliope/tts/googletts/README.md) |
+| VoiceRSS  | [VoiceRSS](../kalliope/tts/voicerss/README.md)   |
+| Pico2wave | [Pico2wave](../kalliope/tts/pico2wave/README.md) |
+| Voxygen   | [Voxygen](../kalliope/tts/voxygen/README.md)     |
+
+## Community TTS
+Community TTSs need to be installed manually.
+
+To know how to install a community TTS, read the "Installation" section of the [TTS documentation](tts.md).
+
+| Name   | Description                                          |
+|--------|------------------------------------------------------|
+| Espeak | [Espeak](https://github.com/Ultchad/kalliope-espeak) |
+
+Wanna add your TTS in the list? Open [an issue](../../issues) with the link of your TTS or send a pull request to update the list directly.
+
+

+ 5 - 5
kalliope/stt/google/google.py

@@ -36,18 +36,18 @@ class Google(OrderListener):
 
             captured_audio = r.recognize_google(audio, key=key, language=language, show_all=show_all)
             Utils.print_success("Google Speech Recognition thinks you said %s" % captured_audio)
-            self._analyse_audio(captured_audio)
+            self._analyse_audio(audio_to_text=captured_audio)
 
         except sr.UnknownValueError:
             Utils.print_warning("Google Speech Recognition could not understand audio")
             # callback anyway, we need to listen again for a new order
-            self._analyse_audio(audio=None)
+            self._analyse_audio(audio_to_text=None)
         except sr.RequestError as e:
             Utils.print_danger("Could not request results from Google Speech Recognition service; {0}".format(e))
             # callback anyway, we need to listen again for a new order
-            self._analyse_audio(audio=None)
+            self._analyse_audio(audio_to_text=None)
 
-    def _analyse_audio(self, audio):
+    def _analyse_audio(self, audio_to_text):
         """
         Confirm the audio exists and run it in a Callback
         :param audio: the captured audio
@@ -56,4 +56,4 @@ class Google(OrderListener):
         # if self.main_controller is not None:
         #     self.main_controller.analyse_order(audio)
         if self.callback is not None:
-            self.callback(audio)
+            self.callback(audio_to_text)