AVS Device SDK Optional Features
This page provides information to help you implement optional Alexa Voice Service (AVS) Device SDK features. For code samples and full implementation details, see the AVS Device SDK on GitHub or the AVS Device SDK API references.
Alerts
To enable Alerts, you must follow these instructions:
- Install SQLite.
- Set your device system clock to UTC time. To set UTC time, use Network Time Protocol (NTP).
- Install a file system.
SQLITE_THREADSAFE
value of 0.Apple Music
Streaming from Apple Music isn't enabled by default. To enable Apple Music, use the following instructions.
Ubuntu / Linux / Raspberry Pi
To enable Apple Music on Unix/Linux systems
-
Install the required dependencies with the following command.
sudo apt install libavcodec-dev libavformat-dev libavutil-dev ffmpeg
-
Add the following CMake flags to your build command.
-DENABLE_SAMPLE_AES=ON -DFFMPEG_INCLUDE_DIR=<path to ffmpeg include> -DFFMPEG_LIB_PATH=<path to ffmpeg lib>
-
Link the Apple Music account that you are using to the Alexa account that's registered to the SDK through the Apple Music Skill on the companion app.
Example CMake command for Ubuntu/Linux
cmake \
-DGSTREAMER_MEDIA_PLAYER=ON \
-DENABLE_SAMPLE_AES=ON \
-DPORTAUDIO=ON \
-DPORTAUDIO_LIB_PATH=$PORTAUDIO/lib/.libs/libportaudio.a \
-DPORTAUDIO_INCLUDE_DIR=$PORTAUDIO/include \
-DCMAKE_BUILD_TYPE=DEBUG \
-DENABLE_ALL_ENDPOINT_CONTROLLERS=ON \
-DFFMPEG_INCLUDE_DIR=/usr/include/x86_64-linux-gnu/ \
-DFFMPEG_LIB_PATH=/usr/lib/x86_64-linux-gnu
-DCURL_LIBRARY=/usr/local/opt/curl-openssl/lib/libcurl.dylib \
-DCURL_INCLUDE_DIR=/usr/local/opt/curl-openssl/include
Example CMake command for Raspberry Pi
cmake \
-DGSTREAMER_MEDIA_PLAYER=ON \
-DENABLE_SAMPLE_AES=ON \
-DPORTAUDIO=ON \
-DPORTAUDIO_LIB_PATH=$PORTAUDIO/lib/.libs/libportaudio.a \
-DPORTAUDIO_INCLUDE_DIR=$PORTAUDIO/include \
-DCMAKE_BUILD_TYPE=DEBUG \
-DENABLE_ALL_ENDPOINT_CONTROLLERS=ON \
-DFFMPEG_INCLUDE_DIR=/usr/include/arm-linux-gnueabihf / \
-DFFMPEG_LIB_PATH=/usr/lib/arm-linux-gnueabihf \
-DCURL_LIBRARY=/usr/local/opt/curl-openssl/lib/libcurl.dylib \
-DCURL_INCLUDE_DIR=/usr/local/opt/curl-openssl/include
macOS
To enable Apple Music on macOS
-
Install the required dependencies with the following command.
brew install ffmpeg
-
Add the following CMake flags to your build command.
-DENABLE_SAMPLE_AES=ON -DFFMPEG_INCLUDE_DIR=<path to ffmpeg include> -DFFMPEG_LIB_PATH=<path to ffmpeg lib>
-
Link the Apple Music account that you are using to the Alexa account that's registered to the SDK through the Apple Music Skill on the companion app.
Example CMake command for macOs
cmake
-DGSTREAMER_MEDIA_PLAYER=ON \
-DENABLE_SAMPLE_AES=ON \
-DPORTAUDIO=ON \
-DPORTAUDIO_LIB_PATH=$PORTAUDIO/lib/.libs/libportaudio.a \
-DPORTAUDIO_INCLUDE_DIR=$PORTAUDIO/include \
-DCMAKE_BUILD_TYPE=DEBUG \ -DENABLE_ALL_ENDPOINT_CONTROLLERS=ON \
-DFFMPEG_INCLUDE_DIR=/usr/local/Cellar/ffmpeg/4.3_1/include/ \
-DFFMPEG_LIB_PATH=/usr/local/Cellar/ffmpeg/4.3_1/lib
-DCURL_LIBRARY=/usr/local/opt/curl-openssl/lib/libcurl.dylib \
-DCURL_INCLUDE_DIR=/usr/local/opt/curl-openssl/include
Windows
To enable Apple Music on Windows
-
Install the required dependencies with the following command.
pacman -S --noconfirm --needed mingw-w64-x86_64-ffmpeg
-
Change the
mingw.sh
file you use to build and install on Windows by adding the following CMake flags after line 23.-DENABLE_SAMPLE_AES=ON -DFFMPEG_INCLUDE_DIR=/mingw64/include \ -DFFMPEG_LIB_PATH=/mingw64/lib \
-
Link the Apple Music account that you are using to the Alexa account that's registered to the SDK through the Apple Music Skill on the companion app.
Example CMake command for Windows
CMAKE_PLATFORM_SPECIFIC=(-G 'MSYS Makefiles' -Dgtest_disable_pthreads=ON \
-DENABLE_SAMPLE_AES=ON \
-DFFMPEG_INCLUDE_DIR=/mingw64/include \
-DFFMPEG_LIB_PATH=/mingw64/lib \
-DGSTREAMER_MEDIA_PLAYER=ON -DPORTAUDIO=ON \
-DPORTAUDIO_LIB_PATH="$THIRD_PARTY_PATH/portaudio/lib/.libs/libportaudio.$LIB_SUFFIX" \
-DPORTAUDIO_INCLUDE_DIR="$THIRD_PARTY_PATH/portaudio/include")
Asset manager
This feature lets you store and manage files from an external location and use them with the SDK. For example, you can store an audio file and play it when required.
To use asset manager, you need the following dependencies:
- libarchive – install this using your package manager.
- FileSystemUtils – Installed and configured automatically by the SDK.
For more details about the dependencies, see Dependencies.
To build the SDK with asset manager
- Install the libarchive package by following the instructions made available on libarchive.
-
Enable asset manager with the
ASSET_MANAGER
CMake command.The following example shows a full CMake build command on a Raspberry Pi, with the Asset Manager included.
cmake /home/pi/sdk-folder/sdk-source/avs-device-sdk \ -DASSET_MANAGER=ON \ -DGSTREAMER_MEDIA_PLAYER=ON \ -DPORTAUDIO=ON \ -DPORTAUDIO_LIB_PATH=/home/pi/sdk-folder/third-party/portaudio/lib/.libs/libportaudio.a \ -DPORTAUDIO_INCLUDE_DIR=/home/pi/sdk-folder/third-party/portaudio/include \ -DCURL_INCLUDE_DIR=/home/pi/sdk-folder/third-party/curl-7.67.0/include/curl \ -DCURL_LIBRARY=/home/pi/sdk-folder/third-party/curl-7.67.0/lib/.libs/libcurl.so
If you get an error that states the libarchive library is missing, provide the libarchive header and library path with your
ASSET_MANAGER
CMake command.If you get an error that states
FileSystemUtils is not supported on this platform
, you must provide a custom implementation of theFileSystemUtils
APIs.
Bluetooth
Building with Bluetooth is optional and is supported on Linux or Raspberry Pi.
- To build with Bluetooth on a Raspberry Pi, see the Raspberry Pi Quick-start Guide.
- To build with Bluetooth on Ubuntu, see the Ubuntu Quick-start Guide.
Captions
By default, the SDK disables the use of captions. To enable captions, use the CMake build option CAPTIONS=ON
. You must also install the libwebvtt parsing library. Webvtt is a C/C++ library for interpreting and authoring WebVTT content. WebVTT is a caption and subtitle format designed for use with HTML5 audio and video elements.
By default, captions works with the en-US
locale. If you want to support another locale, modify the line break logic in the CaptionManager::onParsed()
method and use a locale-safe method for determining the break points between words. For example, you can use the ICU BreakIterator to handle the task. You must determine the exact method of this implementation yourself.
MediaPlayerInterface::SourceId
value being unique across all instances.To enable captions to your device
- Download and install libwebvtt to a directory of your choice. If there are any additional instructions on the libwebvtt page, make sure you follow them.
-
Build the AVS Device SDK and configure your CMake command with the following flags.
-DCAPTIONS=ON \ -DLIBWEBVTT_LIB_PATH=$HOME/captions/webvtt-master/build/src/webvtt/libwebvtt.a \ -DLIBWEBVTT_INCLUDE_DIR=$HOME/captions/webvtt-master/include
Custom media player
For more details about enabling a custom media player, see Media Players.
Endpoints
For more details about enabling endpoints, see Smart Home Endpoints.
SAMPLE-AES decryption
SAMPLE-AES decryption is optional.
To enable SAMPLE-AES decryption for audio streamed to your device
- Install the FFMPEG library.
-
Enable SAMPLE-AES decryption with the following CMake command.
cmake [absolute path to source] -DENABLE_SAMPLE_AES[ON|OFF] -DFFMPEG_LIB_PATH=[absolute path to ffmpeg library] -DFFMPEG_INCLUDE_DIR=[absolute path to ffmpeg include directory]
Out-of-box onboarding experience
You can use the DeviceSetup Interface to inform AVS that a device has finished setting up. You can use this interface to trigger an onboarding experience, such as a first-time set up walk through process.
To see how this process works, you can simulate the device set up process in the SampleApp menu.
To simulate a device set up
- Launch the SampleApp.
- Enter
i
to bring up the settings menu. -
Enter
v
to send aSetupCompleted
Event to AVS.You can use this sample experience as a reference to build your own device set up experience.
Last updated: Nov 12, 2021