Update GitHub issue template, add threaded workers example, update do…

…cumentation for listen_in_background

.github/ISSUE_TEMPLATE.md

@@ -34,4 +34,6 @@ My **SpeechRecognition library version** is <INSERT VERSION HERE>. (You can chec
 
 My **PyAudio library version** is <INSERT VERSION HERE> / I don't have PyAudio installed. (You can check this by running `python -c "import pyaudio as p;print(p.__version__)"`.)
 
+My **microphones** are: (You can check this by running `python -c "import speech_recognition as sr;print(sr.Microphone.list_microphone_names())"`.)
+
 I **installed PocketSphinx from** <INSERT SOURCE HERE>. (For example, from the Debian repositories, from Homebrew, or from the source code.)

.gitignore

@@ -9,4 +9,4 @@ fr-FR.zip
 zh-CN.zip
 it-IT.zip
 pocketsphinx-python/
-venv/
+examples/TEST.py

examples/threaded_workers.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+
+# NOTE: this example requires PyAudio because it uses the Microphone class
+
+from queue import Queue
+
+import speech_recognition as sr
+
+
+r = sr.Recognizer()
+audio_queue = Queue()
+
+def recognize_worker():
+    # this runs in a background thread
+    while True:
+        audio = audio_queue.get()  # retrieve the next audio processing job from the main thread
+        if audio is None: break  # stop processing if the main thread is done
+
+        # received audio data, now we'll recognize it using Google Speech Recognition
+        try:
+            # for testing purposes, we're just using the default API key
+            # to use another API key, use `r.recognize_google(audio, key="GOOGLE_SPEECH_RECOGNITION_API_KEY")`
+            # instead of `r.recognize_google(audio)`
+            print("Google Speech Recognition thinks you said " + recognizer.recognize_google(audio))
+        except sr.UnknownValueError:
+            print("Google Speech Recognition could not understand audio")
+        except sr.RequestError as e:
+            print("Could not request results from Google Speech Recognition service; {0}".format(e))
+
+        audio_queue.task_done()  # mark the audio processing job as completed in the queue
+
+# start a new thread to recognize audio, while this thread focuses on listening
+recognize_thread = threading.Thread(target=recognize_worker)
+recognize_thread.daemon = True
+recognize_thread.start()
+with sr.Microphone() as source:
+    try:
+        while True:  # repeatedly listen for phrases and put the resulting audio on the audio processing job queue
+            audio_queue.put(r.listen(source))
+    except KeyboardInterrupt:  # allow Ctrl + C to shut down the program
+        pass
+
+audio_queue.join()  # block until all current audio processing jobs are done
+audio_queue.put(None)  # tell the recognize_thread to stop
+recognize_thread.join()  # wait for the recognize_thread to actually stop

reference/library-reference.rst

@@ -170,7 +170,7 @@ This operation will always complete within ``timeout + phrase_timeout`` seconds
 
 Spawns a thread to repeatedly record phrases from ``source`` (an ``AudioSource`` instance) into an ``AudioData`` instance and call ``callback`` with that ``AudioData`` instance as soon as each phrase are detected.
 
-Returns a function object that, when called from the current thread, requests that the background listener thread stop. The background thread is a daemon and will not stop the program from exiting if there are no other non-daemon threads. The function accepts one parameter, ``wait_for_stop``: if truthy, the function will wait for the background listener to stop before returning, otherwise it will return immediately and the background listener thread might still be running for a second or two afterwards.
+Returns a function object that, when called, requests that the background listener thread stop. The background thread is a daemon and will not stop the program from exiting if there are no other non-daemon threads. The function accepts one parameter, ``wait_for_stop``: if truthy, the function will wait for the background listener to stop before returning, otherwise it will return immediately and the background listener thread might still be running for a second or two afterwards. Additionally, if you are using a truthy value for ``wait_for_stop``, you must call the function from the same thread you originally called ``listen_in_background`` from.
 
 Phrase recognition uses the exact same mechanism as ``recognizer_instance.listen(source)``. The ``phrase_time_limit`` parameter works in the same way as the ``phrase_time_limit`` parameter for ``recognizer_instance.listen(source)``, as well.
 

speech_recognition/__init__.py

@@ -723,7 +723,7 @@ def listen_in_background(self, source, callback, phrase_time_limit=None):
         """
         Spawns a thread to repeatedly record phrases from ``source`` (an ``AudioSource`` instance) into an ``AudioData`` instance and call ``callback`` with that ``AudioData`` instance as soon as each phrase are detected.
 
-        Returns a function object that, when called from the current thread, requests that the background listener thread stop. The background thread is a daemon and will not stop the program from exiting if there are no other non-daemon threads. The function accepts one parameter, ``wait_for_stop``: if truthy, the function will wait for the background listener to stop before returning, otherwise it will return immediately and the background listener thread might still be running for a second or two afterwards.
+        Returns a function object that, when called, requests that the background listener thread stop. The background thread is a daemon and will not stop the program from exiting if there are no other non-daemon threads. The function accepts one parameter, ``wait_for_stop``: if truthy, the function will wait for the background listener to stop before returning, otherwise it will return immediately and the background listener thread might still be running for a second or two afterwards. Additionally, if you are using a truthy value for ``wait_for_stop``, you must call the function from the same thread you originally called ``listen_in_background`` from.
 
         Phrase recognition uses the exact same mechanism as ``recognizer_instance.listen(source)``. The ``phrase_time_limit`` parameter works in the same way as the ``phrase_time_limit`` parameter for ``recognizer_instance.listen(source)``, as well.