Quick Start: Set Up the AVS Device SDK on macOS for Voice-Only Devices
The following quick start guide provides step-by-step instructions to set up the Alexa Voice Service (AVS) Device SDK on macOS. This process includes installing, building, authorizing, and using the AVS Device SDK. When finished, you have a working Sample App to test interactions with Alexa.
Before you get started, see the SDK overview page to establish a working knowledge of how the SDK works. This quick start guide is applicable to both beginners and advanced users of the SDK. However, you should have some basic knowledge of the Mac Terminal.
Prerequisites
You must meet the following prerequisites before you begin this quick start guide.
- Mac running OS X 12.4+ – Amazon tested the procedures on versions 12.4 and 12.5. No other Mac OS X versions were tested.
- External speaker or headset – Your audio source.
- AVS Device SDK 3.0 and above – This quick start guide instructs you to download the latest version of the SDK.
- Python3 – Minimum version 3.0.x.
- Homebrew – A software package management system that simplifies installation.
- XCode command line tools – An integrated development environment for macOS.
- Minimum dependencies – The Alexa app relies on external libraries to compile. For more details about the external libraries you must install, see AVS Device SDK Dependencies.
- Registered product with AVS – You must register your product with Alexa Voice Service. After you have registered your product, save the
config.json
for “Other devices and platforms” because you need it to complete this quick start guide. This file contains the client ID for your Alexa Voice Service product and is used as part of the authorization between Alexa Voice Service and your device.
Steps to set up the AVS Device SDK on macOS for voice-only devices
To set up the AVS Device SDK on macOS, complete the following steps:
- Set up your macOS environment
- Download the AVS Device SDK
- Find paths to dependencies
- Build the SDK Sample App
Note: This quick start guide doesn't include instructions to enable wake word.
- Set up your configuration file
- Run and authorize the Sample App
- Use the Sample App
Step 1: Set up your macOS environment
The following instructions use your home directory represented by $HOME
. If you want to store the SDK under a different path, update the commands accordingly.
To set up your development environment on macOS
1. Open the Terminal, and then create your SDK folder structure.
cd $HOME
mkdir sdk-folder
cd sdk-folder
mkdir sdk-build sdk-source sdk-install db
2. Update your Homebrew package list.
brew update && brew upgrade
3. Install the core SDK dependencies.
The AVS Device SDK uses external libraries to handle the following functionality:
- Maintain an HTTP/2 connection with AVS.
- Play Alexa text-to-speech (TTS) and music.
- Record audio from the microphone.
- Store records in a database.
cd $HOME
brew install sqlite3 git cmake curl gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav clang-format doxygen googletest openssl@1.1 portaudio
brew install
command. Step 2: Download the AVS Device SDK
The AVS Device SDK is available on GitHub. Clone the SDK into the sdk-source
folder by using the following commands.
cd $HOME/sdk-folder/sdk-source
git clone --single-branch https://github.com/alexa/avs-device-sdk.git
Step 3: Find paths to dependencies
1. Update the libffi package configuration path to the path retrieved in the previous step.
export PKG_CONFIG_PATH="$(brew --prefix)/opt/libffi/lib/pkgconfig:$(brew --prefix)/opt/openssl@1.1/lib/pkgconfig:$PKG_CONFIG_PATH"
echo 'export PKG_CONFIG_PATH="$(brew --prefix)/opt/libffi/lib/pkgconfig:$(brew --prefix)/opt/openssl@1.1/lib/pkgconfig:$PKG_CONFIG_PATH"' >> $HOME/.bash_profile
2. Set environment variables for PortAudio
and curl
.
Homebrew installs the PortAudio
and curl
packages into a folder that can be found using the brew --prefix
command.
brew --prefix
The following commands set environment variables to hold the paths for needed dependencies for you to use in step 4.1.
export CURL_LIBRARY_PATH=$(brew --prefix)/opt/curl/lib/libcurl.dylib
export CURL_INCLUDE_DIR=$(brew --prefix)/opt/curl/include
export PORTAUDIO_LIB_PATH=$(brew --prefix)/opt/portaudio/lib/libportaudio.dylib
export PORTAUDIO_INCLUDE_DIR=$(brew --prefix)/opt/portaudio/include
Step 4: Build the SDK Sample App
In this step, you build the SDK by using your Terminal.
Use CMake parameters to customize what features you want to build in the Sample App.
This example configures the following build options:
To build the SDK Sample App
1. Generate the build dependencies for the Sample App by using the following CMake
command.
cd $HOME/sdk-folder/sdk-build/
cmake $HOME/sdk-folder/sdk-source/avs-device-sdk \
-DGSTREAMER_MEDIA_PLAYER=ON \
-DPORTAUDIO=ON \
-DPKCS11=OFF \
-DCURL_LIBRARY=$CURL_LIBRARY_PATH \
-DCURL_INCLUDE_DIR=$CURL_INCLUDE_DIR \
-DPORTAUDIO_LIB_PATH=$PORTAUDIO_LIB_PATH \
-DPORTAUDIO_INCLUDE_DIR=$PORTAUDIO_INCLUDE_DIR \
-DCMAKE_BUILD_TYPE=DEBUG
2. Build the Sample App.
make SampleApp
The command
make SampleApp
uses a single thread for compilation. You can speed up compilation with more threads by adding the -j2
, -j4
, or -j8
make
flag, depending on your processor. The
make SampleApp
command only builds the SDK Sample App. To build the entire SDK— including unit tests— run the make
command instead.Step 5: Set up your configuration file
Before you can run the Sample App, you must set up an SDK configuration file named, AlexaClientSDKConfig.json
. This file contains your SDK settings to authorize your device with Amazon.
To set up this file, you run a configuration script named genconfig.sh
. This script is located in your SDK download package at $HOME/sdk-folder/sdk-source/avs-device-sdk/tools/Install
.
AlexaClientSDKConfig.json
before you run genconfig.sh
. Running the genConfig.sh
script overwrites the values contained in your AlexaClientSDKConfig.json
file. To set up your SDK configuration file
1. Place the config.json
file you downloaded in the $HOME/sdk-folder/sdk-source/avs-device-sdk/tools/Install
directory.
2. Run genConfig.sh
script to generate your config. When you run the script, include all the parameters shown in the following code example.
cd $HOME/sdk-folder/sdk-source/avs-device-sdk/tools/Install
bash genConfig.sh config.json 12345 \
$HOME/sdk-folder/db \
$HOME/sdk-folder/sdk-source/avs-device-sdk \
$HOME/sdk-folder/sdk-build/Integration/AlexaClientSDKConfig.json \
-DSDK_CONFIG_MANUFACTURER_NAME="my_project" \
-DSDK_CONFIG_DEVICE_DESCRIPTION="macos"
genConfig.sh
overwrites any values set in AlexaClientSDKConfig.json
. If necessary, back up the file.Step 6: Run and authorize the Sample App
When you run the Sample App for the first time, you must authorize it with Amazon using a generated code specific to your device.
To run and authorize the Sample App
1. Navigate to your build
folder, set up an environment variable, and then start the Sample App.
cd $HOME/sdk-folder/sdk-build/
GST_PLUGIN_PATH=$(brew --prefix)/lib/gstreamer-1.0/ ./SampleApplications/ConsoleSampleApplication/src/SampleApp ./Integration/AlexaClientSDKConfig.json
GST_PLUGIN_PATH
is used to override the Gstreamer
plugin search path to $(brew --prefix)/lib/gstreamer-1.0/
.2. Wait for the Sample App to display the following message.
##################################
# NOT YET AUTHORIZED #
##################################
################################################################################################
# To authorize, browse to: 'https://amazon.com/us/code' and enter the code: {XXXX} #
################################################################################################
3. Open a browser. If you're in the US, navigate to the US-specific URL to authorize the Sample App. If you're outside of the US, use the URL as shown in your step 6.2.
4. Sign in to your Amazon developer account.
5. Enter the code specified in the message from the Sample App.
6. Select Allow.
7. Wait for the Sample App to authorize. You can now use the Sample App to talk to Alexa.
###########################
# Authorized! #
###########################
########################################
# Alexa is currently idle! #
########################################
Step 7: Use the Sample App
Now that you have a working Sample App, try an interaction with Alexa. For more details about how to interact with Alexa, see Use the Console Sample App.
To relaunch the Sample App
- Run the following command.
cd $HOME/sdk-folder/sdk-build
GST_PLUGIN_PATH=$(brew --prefix)/lib/gstreamer-1.0/ ./SampleApplications/ConsoleSampleApplication/src/SampleApp ./Integration/AlexaClientSDKConfig.json DEBUG9
Extra build options
Use the following instructions to enable additional build options.
Enable debug logs
Use the debug flag to get more information about problems you might encounter. Accepted values include DEBUG1
through DEBUG9
.
For example, the following command uses the DEBUG9
logging flag.
cd $HOME/sdk-folder/sdk-build
GST_PLUGIN_PATH=$(brew --prefix)/lib/gstreamer-1.0/ ./SampleApplications/ConsoleSampleApplication/src/SampleApp ./Integration/AlexaClientSDKConfig.json DEBUG9
Troubleshooting
For details about fixing common issues, see Troubleshooting the AVS Device SDK Common Issues.
Related topics
- AVS Device SDK Implementation Guides
- Alexa Voice Service Device SDK Dependencies
- Alexa Voice Service Device SDK Authorization
Last updated: Nov 29, 2022