test(microphone): Make microphone example more readable

Author: ehdsouza

appveyor.yml

@@ -20,7 +20,7 @@ install:
   - "python -m pip install --upgrade pip"
 
   # Install the build dependencies of the project.
-  - "pip install -r dev-requirements.txt"
+  - "pip install -r requirements-dev.txt"
 
 build: off
 

examples/microphone-speech-to-text.py

@@ -1,6 +1,11 @@
 # You need to install pyaudio to run this example
 # pip install pyaudio
 
+# When using a microphone, the AudioSource `input` parameter would be
+# initialised as a queue. The pyaudio stream would be continuosly adding
+# recordings to the queue, and the websocket client would be sending the
+# recordings to the speech to text service
+
 from __future__ import print_function
 import pyaudio
 from watson_developer_cloud import SpeechToTextV1
@@ -12,13 +17,30 @@
 except ImportError:
     from queue import Queue, Full
 
+###############################################
+#### Initalize queue to store the recordings ##
+###############################################
+CHUNK = 1024
+# Note: It will discard if the websocket client can't consumme fast enough
+# So, increase the max size as per your choice
+BUF_MAX_SIZE = CHUNK * 10
+# Buffer to store audio
+q = Queue(maxsize=int(round(BUF_MAX_SIZE / CHUNK)))
+
+# Create an instance of AudioSource
+audio_source = AudioSource(q, True, True)
+
+###############################################
+#### Prepare Speech to Text Service ########
+###############################################
+
 # initialize speech to text service
 speech_to_text = SpeechToTextV1(
     username='YOUR SERVICE USERNAME',
     password='YOUR SERVICE PASSWORD',
     url='https://stream.watsonplatform.net/speech-to-text/api')
 
-# define callback for the service
+# define callback for the speech to text service
 class MyRecognizeCallback(RecognizeCallback):
     def __init__(self):
         RecognizeCallback.__init__(self)
@@ -47,33 +69,30 @@ def on_data(self, data):
     def on_close(self):
         print("Connection closed")
 
+# this function will initiate the recognize service and pass in the AudioSource
+def recognize_using_weboscket(*args):
+    mycallback = MyRecognizeCallback()
+    speech_to_text.recognize_using_websocket(audio=audio_source,
+                                             content_type='audio/l16; rate=44100',
+                                             recognize_callback=mycallback)
+
+###############################################
+#### Prepare the for recording using Pyaudio ##
+###############################################
+
 # Variables for recording the speech
 FORMAT = pyaudio.paInt16
 CHANNELS = 1
 RATE = 44100
-CHUNK = 1024
-# Note: It will discard if the websocket client can't consumme fast enough
-BUF_MAX_SIZE = CHUNK * 10
 
-# Buffer to store audio
-q = Queue(maxsize=int(round(BUF_MAX_SIZE / CHUNK)))
-
-# define callback to store the recording in queue
-def callback(in_data, frame_count, time_info, status):
+# define callback for pyaudio to store the recording in queue
+def pyaudio_callback(in_data, frame_count, time_info, status):
     try:
         q.put(in_data)
     except Full:
         pass # discard
     return (None, pyaudio.paContinue)
 
-# get ready with service params
-audio_source = AudioSource(q, True, True)
-def recognize_using_weboscket(*args):
-    mycallback = MyRecognizeCallback()
-    speech_to_text.recognize_using_websocket(audio=audio_source,
-                                             content_type='audio/l16; rate=44100',
-                                             recognize_callback=mycallback)
-
 # instantiate pyaudio
 audio = pyaudio.PyAudio()
 
@@ -84,10 +103,14 @@ def recognize_using_weboscket(*args):
     rate=RATE,
     input=True,
     frames_per_buffer=CHUNK,
-    stream_callback=callback,
+    stream_callback=pyaudio_callback,
     start=False
 )
 
+#########################################################################
+#### Start the recording and start service to recognize the stream ######
+#########################################################################
+
 print("Enter CTRL+C to end recording...")
 stream.start_stream()