Merge pull request #484 from kivy/speech2stt

Change 'Speech' to 'STT'

examples/speech/main.py → examples/speech2text/main.py

@@ -4,47 +4,42 @@
 from kivy.properties import StringProperty
 from kivy.uix.boxlayout import BoxLayout
 
-from plyer import speech
+from plyer import stt
 
 Builder.load_string('''
-#:import speech plyer.speech
+#:import stt plyer.stt
 
 <SpeechInterface>:
     orientation: 'vertical'
     Label:
         size_hint_y: None
         height: sp(40)
-        text: 'Is supported: %s' % speech.exist()
+        text: 'Is supported: %s' % stt.exist()
     Label:
         size_hint_y: None
         height: sp(40)
         text: 'Possible Matches'
     TextInput:
         id: results
         hint_text: 'results (auto stop)'
-        size_hint_y: 0.3
     TextInput:
         id: partial
         hint_text: 'partial results (manual stop)'
-        size_hint_y: 0.3
     TextInput:
         id: errors
-        size_hint_y: None
-        height: sp(20)
+        hint_text: 'errors'
     Button:
         id: start_button
         text: 'Start Listening'
-        on_release:
-            root.start_listening()
-
+        on_release: root.start_listening()
 ''')
 
 
 class SpeechInterface(BoxLayout):
     '''Root Widget.'''
 
     def start_listening(self):
-        if speech.listening:
+        if stt.listening:
             self.stop_listening()
             return
 
@@ -54,27 +49,27 @@ def start_listening(self):
         self.ids.results.text = ''
         self.ids.partial.text = ''
 
-        speech.start()
+        stt.start()
 
         Clock.schedule_interval(self.check_state, 1 / 5)
 
     def stop_listening(self):
         start_button = self.ids.start_button
         start_button.text = 'Start Listening'
 
-        speech.stop()
+        stt.stop()
         self.update()
 
         Clock.unschedule(self.check_state)
 
     def check_state(self, dt):
         # if the recognizer service stops, change UI
-        if not speech.listening:
+        if not stt.listening:
             self.stop_listening()
 
     def update(self):
-        self.ids.partial.text = '\n'.join(speech.partial_results)
-        self.ids.results.text = '\n'.join(speech.results)
+        self.ids.partial.text = '\n'.join(stt.partial_results)
+        self.ids.results.text = '\n'.join(stt.results)
 
 
 class SpeechApp(App):

plyer/__init__.py

@@ -9,8 +9,8 @@
     'brightness', 'call', 'camera', 'compass', 'cpu', 'email', 'filechooser',
     'flash', 'gps', 'gravity', 'gyroscope', 'humidity', 'irblaster',
     'keystore', 'light', 'notification', 'orientation', 'processors',
-    'proximity', 'screenshot', 'sms', 'spatialorientation', 'speech',
-    'storagepath', 'temperature', 'tts', 'uniqueid', 'vibrator', 'wifi'
+    'proximity', 'screenshot', 'sms', 'spatialorientation', 'storagepath',
+    'stt', 'temperature', 'tts', 'uniqueid', 'vibrator', 'wifi'
 )
 
 __version__ = '1.3.3.dev0'
@@ -77,8 +77,8 @@
 #: Sms proxy to :class:`plyer.facades.Sms`
 sms = Proxy('sms', facades.Sms)
 
-#: Speech proxy to :class:`plyer.facades.Speech`
-speech = Proxy('speech', facades.Speech)
+#: Speech proxy to :class:`plyer.facades.STT`
+stt = Proxy('stt', facades.STT)
 
 #: TTS proxy to :class:`plyer.facades.TTS`
 tts = Proxy('tts', facades.TTS)

plyer/facades/__init__.py

@@ -12,7 +12,7 @@
            'Sms', 'TTS', 'UniqueID', 'Vibrator', 'Wifi', 'Flash', 'CPU',
            'Temperature', 'Humidity', 'SpatialOrientation', 'Brightness',
            'Processors', 'StoragePath', 'keystore', 'Bluetooth', 'Screenshot',
-           'Speech')
+           'STT')
 
 from plyer.facades.accelerometer import Accelerometer
 from plyer.facades.audio import Audio
@@ -33,7 +33,7 @@
 from plyer.facades.orientation import Orientation
 from plyer.facades.notification import Notification
 from plyer.facades.sms import Sms
-from plyer.facades.speech import Speech
+from plyer.facades.stt import STT
 from plyer.facades.tts import TTS
 from plyer.facades.uniqueid import UniqueID
 from plyer.facades.vibrator import Vibrator

plyer/facades/speech.py → plyer/facades/stt.py

@@ -1,52 +1,81 @@
-class Speech(object):
-    '''
-    .. versionadded:: 1.3.3
+'''
+Speech to Text
+==============
+
+.. versionadded:: 1.3.3
+
+Speech Recognition facade.
+
+In order to check that your device supports voice recognition use method
+`exist`.
+
+Variable `language` indicates which language will be used to match words from
+ voice.
+
+Use `start` to start voice recognition immediately and `stop` to stop.
+
+.. note::
+    Needed permissions for Android: `RECORD_AUDIO` (and `INTERNET` if you want
+    online voice recognition API to be used)
 
-    Speech Recognition facade.
+.. note::
+    On Android platform, after execute `start` method you can hear BEEP!
+    Mute sound in order to disable it.
 
-    In order to check that your device supports voice recognition use method
-    `exist`.
+.. note::
+    For Android implementation to work there has to be an application with
+    `android.speech.RecognitionService` implementation present in the system.
+    Mostly it's `com.google.android.googlequicksearchbox` or "Google"
+    application (the search bar with the launcher widget).
 
-    Variable `language` indicates which language will be used to match words
-    from voice.
+Offline Speech Recognition on Android
+-------------------------------------
 
-    Use `start` to start voice recognition immediately and `stop` to stop.
+Requires any application that provides an
+`android.speech.RecognitionService` implementation to the other apps. One of
+such applications is on a lot of devices preinstalled Google (quick search
+box).
 
-    .. note::
-        Needed permissions for Android: `RECORD_AUDIO` (and `INTERNET` if you
-        want online voice recognition API to be used)
+The API prefers offline recognition, but should be able to switch to online
+alternative in case you don't have a language package installed (`INTERNET`
+permission necessary).
 
-    .. note::
-        On Android platform, after execute `start` method you can hear BEEP!
-        Mute sound in order to disable it.
+You can enable offline speech recognition this way (Android 8.1):
 
-    .. note::
-        For Android implementation to work there has to be an application
-        with `android.speech.RecognitionService` implementation present
-        in the system. Mostly it's `com.google.android.googlequicksearchbox`
-        or "Google" application (the search bar with the launcher widget).
+* open the `Settings` app
+* choose `Language & Input` / `Language & Keyboard` (Samsung might include it
+  in the `General` category)
+* choose `On-Screen keyboard` or `Voice search`
+* choose `Google Keyboard`
+* choose `Offline Speech recognition`
+* download language package if you don't have one already
 
-    Offline Speech Recognition on Android
-    -------------------------------------
+Simple Examples
+---------------
 
-    Requires any application that provides an
-    `android.speech.RecognitionService` implementation to the other apps. One
-    of such applications is on a lot of devices preinstalled Google (quick
-    search box).
+To start listening::
 
-    The API prefers offline recognition, but should be able to switch to online
-    alternative in case you don't have a language package installed (`INTERNET`
-    permission necessary).
+    >>> from plyer import stt
+    >>> stt.start()
 
-    You can enable offline speech recognition this way (Android 8.1):
+To retrieve partial results while listening::
 
-    * open the `Settings` app
-    * choose `Language & Input` / `Language & Keyboard` (Samsung might include
-      it in the `General` category)
-    * choose `On-Screen keyboard` or `Voice search`
-    * choose `Google Keyboard`
-    * choose `Offline Speech recognition`
-    * download language package if you don't have one already
+    >>> assert stt.listening
+    >>> print(stt.partial_results)
+
+To stop listening::
+
+    >>> stt.stop()
+
+To retrieve results after the listening stopped::
+
+    >>> print(stt.results)
+'''
+
+
+class STT(object):
+    '''
+    Speech to text facade.
     '''
 
     _language = 'en-US'

plyer/platforms/android/speech.py → plyer/platforms/android/stt.py

@@ -4,7 +4,7 @@
 from jnius import java_method
 from jnius import PythonJavaClass
 
-from plyer.facades import Speech
+from plyer.facades import STT
 from plyer.platforms.android import activity
 
 ArrayList = autoclass('java.util.ArrayList')
@@ -174,7 +174,7 @@ def onRmsChanged(self, rmsdB):
             self.volume_callback(rmsdB)
 
 
-class AndroidSpeech(Speech):
+class AndroidSpeech(STT):
     '''
     Android Speech Implementation.