Skip to main content

Python Client for Alexa Voice Service (AVS)

Project description

Alexa Voice Service Client

code-climate-image circle-ci-image codecov-image

Python Client for Alexa Voice Service (AVS)

This package has been renamed to alexa-client. Only alexa-client will receive updates.


pip install avs_client

or if you want to run the demos:

pip install avs_client[demo]


File audio

from avs_client import AlexaVoiceServiceClient

alexa_client = AlexaVoiceServiceClient(
alexa_client.connect()  # authenticate and other handshaking steps
with open('./tests/resources/alexa_what_time_is_it.wav', 'rb') as f:
    for i, directive in enumerate(alexa_client.send_audio_file(f)):
        if in ['Speak', 'Play']:
            with open(f'./output_{i}.mp3', 'wb') as f:

Now listen to output_0.wav and Alexa should tell you the time.

Microphone audio

import io

from avs_client import AlexaVoiceServiceClient
import pyaudio

def callback(in_data, frame_count, time_info, status):
    return (in_data, pyaudio.paContinue)

p = pyaudio.PyAudio()
stream =

alexa_client = AlexaVoiceServiceClient(

buffer = io.BytesIO()
    print('listening. Press CTRL + C to exit.')
    for i, directive in enumerate(alexa_client.send_audio_file(buffer)):
        if in ['Speak', 'Play']:
            with open(f'./output_{i}.mp3', 'wb') as f:

Voice Request Lifecycle

An Alexa command may relate to a previous command e.g,

[you] "Alexa, play twenty questions" [Alexa] "Is it a animal, mineral, or vegetable?" [you] "Mineral" [Alexa] "Is it valuable" [you] "No" [Alexa] "is it..."

This can be achieved by passing the same dialog request ID to multiple send_audio_file calls:

from avs_client.avs_client import helpers

dialog_request_id = helpers.generate_unique_id()
directives_one = alexa_client.send_audio_file(audio_one, dialog_request_id=dialog_request_id)
directives_two = alexa_client.send_audio_file(audio_two, dialog_request_id=dialog_request_id)
directives_three = alexa_client.send_audio_file(audio_three, dialog_request_id=dialog_request_id)

Run the streaming microphone audio demo to use this feature:

pip install avs_client[demo]
python -m avs_client.demo.streaming_microphone \
    --client-id="{enter-client-id-here}" \
    --client-secret="{enter-client-secret-here"} \


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:

client kwarg Notes
client_id Retrieve by clicking on the your product listed here
secret Retrieve by clicking on the your product listed here
refresh_token You must generate this. See below

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:

setting value
Allowed Origins http://localhost:9000
Allowed Return URLs http://localhost:9000/callback/

Note what you entered for Product ID under Product Information, as this will be used as the device-type-id (case sensitive!)

Then run:

python -m avs_client.refreshtoken.serve \
    --device-type-id="{enter-device-type-id-here}" \
    --client-id="{enter-client-id-here}" \

Follow the on-screen instructions shown at http://localhost:9000 in your web browser. On completion Amazon will return your refresh_token - which you will require to send audio or recorded voice.

Steaming audio to AVS

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.

Persistent AVS connection

Calling alexa_client.connect() creates a persistent connection to AVS. A thread runs that pings AVS after 4 minutes of no request being made to AVS. This prevents the connection getting forcefully closed due to inactivity.

Unit test

To run the unit tests, call the following commands:

git clone
pip install -e .[test]
make test_requirements
make test

Other projects

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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

avs_client-1.3.1-py3-none-any.whl (14.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page