Skip to content

Latest commit

 

History

History
418 lines (260 loc) · 8.92 KB

ReSpeakerPythonAPI.md

File metadata and controls

418 lines (260 loc) · 8.92 KB
Raw

ReSpeaker Python API

ReSpeaker Python Library is an open source python library to provide functions of voice interaction for ReSpeaker.

class BingSpeechAPI

Provides methods to:

  1. Initialize BingSpeechAPI
  2. Apply Bing Speech API access token
  3. Realize speech to text and text to speech
  4. Generate the WAV header and the WAV file contents

  • def __init__(self, key):

    Initialize BingSpeechAPI.

     #Example usage
 BING_KEY = ''
 bing = BingSpeechAPI(key=BING_KEY)

  • def recognize(self, audio_data, language="en-US", show_all=False):

    Translate the audio data to text by sending it to Bing Speech API.

    • Parameters:

      audio_data - the audio frames

      language - the language of the audio data translating into, defaults to "en-US"

      show_all - whether the entire JSON should be returned, defaults to False

    • Return: a JSON containing the hander and lexical

    • Raise RequestError: if recognition connection failed

     #Example usage
 
 try:
 	text = bing.recognize(data)
 	if text:
 		print('Recognized %s' % text)
 except Exception as e:
 	print(e.message)

  • def synthesize(self, text, language="en-US", gender="Female"):

    Synthesize text to audio data by sending it to Bing Speech API.

    • Parameters:

      text - an instance of the String object.

      language - the language of the text, supported languages are listed among self.locales

      gender - the text to speech voice

    • Return: raw audio data

    • Raise LocaleError: if language not in self.locales

     #Example usage
 if spoken_text:
 	audio = bing.synthesize(spoken_text)
 	player.play_raw(audio)

  • def authenticate(self):

    Apply access token from Bing Speech API. Every call to the Speech API requires a JSON Web Token (JWT) access token and the token has a expire time of 10 minutes.

    It is called by self.recognize() and self.synthesize().

    • Parameters:

      self.access_token - access token from Bing Speech API

    • Raise RequestError: if recognition connection failed

  • @staticmethod

    def to_wav(raw_data):

    Generate the WAV file contents with raw audio data.

    It is called by self.recognize().

    • Parameters:

      raw_data - raw audio data

    • Return: WAV data

  • @staticmethod

    def get_wav_header():

    Generate the WAV header.

    It is called by self.recognize().

    • Return: WAV header

class Player

Based on PyAudio and wave, provides methods to:

  1. Initialize Player
  2. Play wav file and raw audio data file.

  • def __init__(self, pa):

    Initialize Player.

    • Parameters:

      pa - PyAudio instance

     #Example usage
 mic = Microphone()
	player = Player(mic.pyaudio_instance)

  • def play(self, wav_file, block=True):

    Play wav audio file.

    • Parameters:

      wav_file - wav file

      block - whether wait for playing audio data in buffer, defaults to True

     #Example usage
 script_dir = os.path.dirname(os.path.realpath(__file__))
 hi = os.path.join(script_dir, 'audio/hi.wav')
 player.play(hi)

  • def play_raw(self, raw_data, rate=16000, channels=1, width=2, block=True):

    Play raw audio file.

    • Parameters:

      raw_data - raw audio data file

      block - whether wait for playing audio data in buffer, defaults to True

     #Example usage	
 if spoken_text:
 	audio = bing.synthesize(spoken_text)
 	player.play_raw(audio)

class Microphone

Provides methods to:

  1. Initialize Microphone
  2. Translate raw audio data into text
  3. Wake up ReSpeaker with keyword
  4. Listen and record the speech

  • def __init__(self, pyaudio_instance=None, quit_event=None):

    Initialize Microphone.

    • Parameters:

      pyaudio_instance - PyAudio instance, defaults to None

      quit_event - if quit_event is set, defaults to None

     #Example usage	
 mic = Microphone()

  • def recognize(self, data):

    Translate raw audio data into text with PocketSphinx.

    • Parameters:

      data - raw audio data

    • Return: string

     #Example usage	
 data = mic.listen()
 text = mic.recognize(data)
 if text:
 	time.sleep(1)
 	print('Recognized %s' % text)

  • def detect(self, keyword=None):

    def wakeup(self, keyword=None):

    detect and wakeup are used to wake up ReSpeaker when the keyword is detected.

    • Parameters:

      keyword - the keyword to wake up ReSpeaker

    • Return: if the keyword is detected, return the keyword; if not, return None.

     #Example usage	
 if mic.wakeup('respeaker'):
 	print('wake up')
 	data = mic.listen()
 	text = mic.recognize(data)
 	if text:
 		time.sleep(1)
 		print('Recognized %s' % text)

  • def listen(self, duration=9, timeout=3):

    Listen and record the speech.

    • Parameters:

      duration - listen the speech for the given number of seconds, defaults to 9 seconds

      timeout - stop listening when don't detect any speeches for the given number of seconds, defaults to 3 seconds

    • Return: raw audio data

     #Example usage	
 if mic.wakeup('respeaker'):
 	print('wake up')
 	data = mic.listen()
 	text = mic.recognize(data)
 	if text:
 		time.sleep(1)
 		print('Recognized %s' % text)

  • def record(self, file_name, seconds=1800):

    Record the speech and save the audio file.

    • Parameters:

      file_name - file name of the saved audio file

      seconds - recording seconds, defaults to 1800 seconds

  • def start(self):

    Start processing the audio stream.

  • def stop(self):

    Pause playing/recording.

  • def close(self):

    Terminate the stream.

  • def task(quit_event):

    An example of a wakeup and recognize task.

     #Example usage	
 q = Event()
	t = Thread(target=task, args=(q,))
	t.start()
	while True:
		try:
 		time.sleep(1)
 	except KeyboardInterrupt:
    	print('Quit')
    	q.set()
   		break
	t.join()

class SPI

Provides methods to:

  1. Initialize SPI
  2. Send data to Arduino via SPI

  • def __init__(self, sck=15, mosi=17, miso=16, cs=14):

    Initialize SPI. Note that class SPI has been instantiated in spi.py, so don't have to initialize it again.

     #Example usage
 from respeaker import spi
 spi.write(data = bytearray([1, 0, 0, 50]), address = 0x00)

  • def write(self, data=None, address=None):

    Send data to Arduino. Click this Data exchange between Arduino and OpenWrt for more introduction.

    • Parameters:

      data - the data sent to Arduino, it should be a bytearray

      address - the address of SPI

     from respeaker import spi
 #send data [1, 0, 0, 50] to Arduino, which will make the leds turn blue.
 spi.write(data = bytearray([1, 0, 0, 50]), address = 0x00)

class PixelRing

Depends on class SPI, provides methods to:

  1. Initialize PixelRing
  2. Set pixel leds to off``listen``wait modes
  3. Set specific color to pixel leds

  • def __init__(self):

    Initialize PixelRing. Note that class PixelRing has been instantiated in pixel_ring.py, so you don't need to initialize it again.

     #Example usage
 from respeaker import pixel_ring
 
 pixel_ring.listen()
 time.sleep(3)
 pixel_ring.wait()
 time.sleep(3)
 for level in range(2, 8):
 	pixel_ring.speak(level, 0)
 	time.sleep(1)
 pixel_ring.set_volume(4)
 time.sleep(3)

  • def off(self):

    Set pixel leds all off.

     #Example usage
 pixel_ring.off()

  • def listen(self, direction=None):

    Set pixel leds to listen mode, which makes leds all green.

    • Parameters:

      direction - when direction is None, send self.write(0, [7, 0, 0, 0]) and while direction is not None, send self.write(0, [2, 0, direction & 0xFF, (direction >> 8) & 0xFF])

     #Example usage
 pixel_ring.listen()

  • def wait(self):

    Set pixel leds to wait mode, which makes three leds green and running in circle.

     #Example usage
 pixel_ring.wait()

  • def set_color(self, rgb=None, r=0, g=0, b=0):

    Set specific color to all pixel leds.

    • Parameters:

      rgb - hex color codes, for example, 0xff0000 means red and 0xffff00 means yellow

      r - color codes of red, from 0 to 255 or 0x00 to 0xff

      g - color codes of green, from 0 to 255 or 0x00 to 0xff

      b - color codes of blue, from 0 to 255 or 0x00 to 0xff

     #Example usage
 pixel_ring.set_color(rgb=0x505000)
 time.sleep(3)
 pixel_ring.set_color(r=150, g=100, b=20)