Python Client for Alexa Voice Service (AVS)

pip install avs_client

from avs_client import AlexaVoiceServiceClient


alexa_client = AlexaVoiceServiceClient(
    client_id='my-client-id',
    secret='my-secret',
    refresh_token='my-refresh-token',
)
alexa_client.connect()  # authenticate and other handshaking steps
with open('./tests/resources/alexa_what_time_is_it.wav', 'rb') as f:
    alexa_response_audio = alexa_client.send_audio_file(f)
with open('./output.wav', 'wb') as f:
    f.write(alexa_response_audio)

Now listen to output.wave and Alexa should tell you the time.

from io import BytesIO

import pyaudio

from avs_client import AlexaVoiceServiceClient


buffer = BytesIO()

def callback(in_data, frame_count, time_info, status):
    buffer.write(in_data)
    return (in_data, pyaudio.paContinue)
p = pyaudio.PyAudio()
stream = p.open(
    format=pyaudio.paInt16,
    channels=1,
    rate=16000,
    input=True,
    stream_callback=callback,
)


alexa_client = AlexaVoiceServiceClient(
    client_id='my-client-id',
    secret='my-secret',
    refresh_token='my-refresh-token',
)


try:
    stream.start_stream()
    print('listening. Press CTRL + C to exit.')
    alexa_client.connect()
    alexa_response_audio = alexa_client.send_audio_file(buffer)
    if alexa_response_audio:
        with open('./output.wav', 'wb') as f:
            f.write(alexa_response_audio)
finally:
    stream.stop_stream()
    stream.close()
    p.terminate()

To use AVS you must first have a developer account. Then register your product here. Choose "Application" under "Is your product an app or a device"?

The client requires your client_id, secret and refresh_token:

You will need to login to Amazon via a web browser to get your refresh token.

To enable this first go here and click on your product to set some security settings under Security Profile:

Then run:

python ./avs_client/refreshtoken/serve.py \
    --device-type-id=enter-device-type-id-here \
    --client-id=enter-client-id-here \
    --client-secret=enter-client-secret-here

Follow the on-screen instructions shown at http://localhost:9000 in your web browser. On completion Amazon will return your refresh_token.

alexa_client.send_audio_file streaming uploads a file-like object to AVS for great latency. The file-like object can be an actual file on your filesystem, an in-memory BytesIo buffer containing audio from your microphone, or even audio streaming from your browser over a websocket in real-time.

AVS requires the audio data to be 16bit Linear PCM (LPCM16), 16kHz sample rate, single-channel, and little endian.

Calling alexa_client.connect() creates a persistent connection to AVS. The connection may get forcefully closed due to inactivity. Keep open by calling alexa_client.alexa_client.conditional_ping():

import threading


def ping_avs():
    while True:
        alexa_client.conditional_ping()

ping_thread = threading.Thread(target=ping_avs)
ping_thread.start()

You will only need this if you intend to run the process for more than five minutes. More information.

Passing extra context to AVS is useful if you're running a custom AVS skill and need some data passed from the client to the AVS adapter, e.g, a smart home skill that controls the lights in the current room must know from which room the audio command came from:

alexa_response_audio = alexa_client.send_audio_file(f, context={
    'header': {
        'namespace': 'MyCustomSkill',
        'name': 'RoomState'
    },
    'payload': {
        'name': 'kitchen'
    }
})

To run the unit tests, call the following commands:

pip install -r requirements-dev.txt
./scripts/tests.sh

This library is used by alexa-browser-client, which allows you to talk to Alexa from your browser.