macOS Quick Start Guide
The following instructions show you how to set up the Alexa Smart Screen SDK on a computer running macOS. The instructions guide you through obtaining the SDK, installing and building the SDK, and running the included sample app.
cmake
build flag when you're using it together with the Alexa Smart Screen SDK.Tested on the following macOS versions
- macOS Catalina or Mojave
macOS prerequisites
- Homebrew
- Xcode command line tools
To determine your installed versions, enter the following commands.
brew --version
xcode-select --version
Browser requirements
The Alexa Smart Screen SDK reference implementation relies on the browser to play APL media. It therefore requires a browser built on the WebKit/Chromium-based web engine that supports the following features:
- ECMAScript 2015, ECMAScript 6 (ES6)
- Must be capable of playing MP3 MPEG-2 Audio Layer III at a bit rate of 48 KBPS
- Must be capable of playing video MPEG-4 AVC
- HTTP/2 (RFC 7540)
- HTML5 WebKit/Chromium-based web engine
Additional required software
Procedure overview
The following steps show the procedure that you must follow to obtain, install, and build the Alexa Voice Service (AVS) Device SDK and the Alexa Smart Screen SDK to get the Smart Screen SDK sample app up and running on your macOS computer.
- Step 1: Create an AVS device on the developer portal, including a security profile
- Step 2: Set up your development environment on your Mac
- Step 3: Download and configure the AVS Device SDK, APL Core Library, APL Client Library, and Alexa Smart Screen SDK
- Step 4: Build the AVS Device SDK
- Step 5: Run the AVS Device SDK sample app
- Step 6: Build the APL Core Library
- Step 7: Build the APL Client Library
- Step 8: Build the Alexa Smart Screen SDK
- Step 9: Run the Alexa Smart Screen SDK sample app
Step 1: Create an AVS device on the Amazon developer portal
Before you can use both the AVS Device SDK sample app and the Alexa Smart Screen SDK sample app, you must have a test device registered as a placeholder on the Amazon developer portal.
Follow the instructions to register an AVS device and create a security profile for the AVS Device SDK, which generates a certificate that you can use with the AVS Device SDK and Alexa Smart Screen SDK sample apps.
Make sure that you download and save the config.json
file for later use.
Step 2: Set up your development environment on your Mac
When you set up your development environment, you must create a directory structure for the SDKs and dependencies.
sdk_folder
as the parent folder, compared to the standalone AVS Device SDK instructions, which uses my_project
as the parent folder.To set up your development environment on your Mac
- Enter the following commands to create the required directories.
cd ~ mkdir sdk_folder cd sdk_folder mkdir sdk-build third-party sdk-install db
- Install and configure
curl-openssl
.brew install curl-openssl
- On macOS Catalina, add the path for
curl-openssl
to your.zshrc
file.echo export PATH="/usr/local/opt/curl/bin:$PATH" >> ~/.zshrc
On other macOS versions, add the path for
curl-openssl
to your.bash_profile
.echo export PATH="/usr/local/opt/curl/bin:$PATH" >> ~/.bash_profile
- Enter the following commands to install the SDK dependencies.
brew install gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav sqlite3 repo cmake clang-format doxygen wget git openssl@1.1
As each dependency installs, your command line interface (CLI) displays a status message with confirmation that the installation was successful.
-
Download, install and configure PortAudio.
cd third-party wget -c http://www.portaudio.com/archives/pa_stable_v190600_20161030.tgz tar xf pa_stable_v190600_20161030.tgz # If you use MacOS Big Sur, install the following version instead # wget -c http://files.portaudio.com/archives/pa_stable_v190700_20210406.tgz # tar xf pa_stable_v190700_20210406.tgz cd portaudio ./configure --disable-mac-universal && make
Your CLI should display many lines of status updates as it configures
portaudio
. -
Set your
PKG_CONFIG_PATH
.- Determine the path on your Mac.
brew info openssl@1.1
- Update the
PKG_CONFIG_PATH
. Replace path-to-openssl in the following example with your own path toopenssl
. To obtain this path, do one of the following.- On macOS Catalina, copy the path in the previous output that looks similar to
usr/local/Cellar/openssl@1.1/1.1.1g/
.echo export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig:/_path-to-openssl_/lib/pkgconfig:$PKG_CONFIG_PATH" >> ~/.zshrc
- On other macOS versions, copy the path in the previous output that looks similar to
usr/local/Cellar/openssl/1.0.2t
.echo export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig:/_path-to-openssl_/lib/pkgconfig:$PKG_CONFIG_PATH" >> ~/.bash_profile
- On macOS Catalina, copy the path in the previous output that looks similar to
- Determine the path on your Mac.
Step 3: Download and configure the AVS Device SDK, APL Core Library, APL Client Library, and Alexa Smart Screen SDK
- Clone the Git repository for version 1.26.0 of the AVS Device SDK.
cd ~/sdk_folder git clone --single-branch --branch v1.26.0 https://github.com/alexa/avs-device-sdk.git
- Clone the Git repository for version 1.8.1 of the APL Core Library.
cd ~/sdk_folder git clone --single-branch --branch v1.8.1 https://github.com/alexa/apl-core-library.git
- Clone the Git repository for version 1.8.2 of the APL Client Library.
cd ~/sdk_folder git clone --single-branch --branch v1.8.2 https://github.com/alexa/apl-client-library.git
- Clone the Git repository for version v2.9.0 of the Alexa Smart Screen SDK.
cd ~/sdk_folder git clone --single-branch --branch v2.9.0 https://github.com/alexa/alexa-smart-screen-sdk.git
Step 4: Build the AVS Device SDK
Because the Alexa Smart Screen SDK has several dependencies on the AVS Device SDK, you must build the AVS Device SDK and run the AVS Device SDK sample app before attempting to build and run the Alexa Smart Screen SDK and sample app.
To build the AVS Device SDK
- Navigate to the build folder that you created in step 2 for the AVS Device SDK.
cd ~/sdk_folder/sdk-build
- Configure a
cmake
command for the AVS Device SDK.cmake ../avs-device-sdk \ -DGSTREAMER_MEDIA_PLAYER=ON \ -DCURL_LIBRARY=/usr/local/opt/curl/lib/libcurl.dylib \ -DCURL_INCLUDE_DIR=/usr/local/opt/curl/include \ -DPORTAUDIO=ON \ -DPORTAUDIO_LIB_PATH=$HOME/sdk_folder/third-party/portaudio/lib/.libs/libportaudio.a \ -DPORTAUDIO_INCLUDE_DIR=$HOME/sdk_folder/third-party/portaudio/include \ -DCMAKE_BUILD_TYPE=DEBUG \ -DCMAKE_INSTALL_PREFIX=$HOME/sdk_folder/sdk-install \ -DRAPIDJSON_MEM_OPTIMIZATION=OFF \ -DPKCS11=OFF
You should see output similar to the following truncated example if your
cmake
command is successful.Creating the build directory for the AlexaClientSDK with build type: DEBUG No keyword detector type specified, skipping build of keyword detector. Bluetooth implementation not supported CMake Warning (dev) at ThirdParty/googletest-release-1.8.0/CMakeLists.txt:3 (project): Policy CMP0048 is not set: project() command manages VERSION variables. Run "cmake --help-policy CMP0048" for policy details. Use the cmake_policy command to set the policy and suppress this warning. The following variable(s) would be set to empty: PROJECT_VERSION PROJECT_VERSION_MAJOR PROJECT_VERSION_MINOR PROJECT_VERSION_PATCH This warning is for project developers. Use -Wno-dev to suppress it.
…
Bluetooth implementation not supported -- Could NOT find GTest (missing: GTEST_LIBRARY GTEST_INCLUDE_DIR GTEST_MAIN_LIBRARY) -- Configuring done -- Generating done -- Build files have been written to: /Users/me/sdk_folder/sdk-build
If you see messages about missing GTEST, ignore them, as this library doesn't cause errors with the SDK or sample app.
- Build the AVS Device SDK.
make -j4
The build process for the SDK takes several minutes. Your CLI displays a scrolling set of status messages to inform you of the build process similar to the following.
... Scanning dependencies of target SampleApp [ 98%] Building CXX object SampleApp/src/CMakeFiles/SampleApp.dir/ConsolePrinter.cpp.o [ 98%] Building CXX object SampleApp/src/CMakeFiles/SampleApp.dir/ConsoleReader.cpp.o [ 98%] Built target DoNotDisturbCapabilityAgentTest [ 98%] Building CXX object SampleApp/src/CMakeFiles/SampleApp.dir/GuiRenderer.cpp.o [ 99%] Building CXX object SampleApp/src/CMakeFiles/SampleApp.dir/InteractionManager.cpp.o [ 99%] Building CXX object SampleApp/src/CMakeFiles/SampleApp.dir/KeywordObserver.cpp.o [ 99%] Building CXX object SampleApp/src/CMakeFiles/SampleApp.dir/LocaleAssetsManager.cpp.o [ 99%] Building CXX object SampleApp/src/CMakeFiles/SampleApp.dir/UIManager.cpp.o [ 99%] Building CXX object SampleApp/src/CMakeFiles/SampleApp.dir/UserInputManager.cpp.o [100%] Building CXX object SampleApp/src/CMakeFiles/SampleApp.dir/SampleApplication.cpp.o [100%] Building CXX object SampleApp/src/CMakeFiles/SampleApp.dir/SampleEqualizerModeController.cpp.o [100%] Building CXX object SampleApp/src/CMakeFiles/SampleApp.dir/main.cpp.o [100%] Building CXX object SampleApp/src/CMakeFiles/SampleApp.dir/PortAudioMicrophoneWrapper.cpp.o [100%] Linking CXX executable SampleApp [100%] Built target SampleApp
- Install the AVS Device SDK.
make install
The installation also takes several minutes. As with the build process, your CLI window displays scrolling status messages, such as the following.
[ 15%] Built target AVSCommon [ 16%] Built target gmock_main [ 16%] Built target gtest [ 17%] Built target gtest_main [ 17%] Built target AttachmentCommonTestLib [ 17%] Built target NamespaceAndNameTest [ 17%] Built target HandlerAndPolicyTest [ 17%] Built target AttachmentTest [ 17%] Built target AttachmentWriterTest [ 18%] Built target ExceptionEncounteredSenderTest [ 18%] Built target CapabilityAgentTest [ 19%] Built target AttachmentUtilsTest [ 19%] Built target AttachmentReaderTest [ 20%] Built target DialogUXStateAggregatorTest
-
Generate the
AlexaClientSDKConfig.json
file to be used by the sample apps for the SDKs.- Navigate to the AVS Device SDK install directory:
cd ~/sdk_folder/avs-device-sdk/tools/Install
- Run the
genConfig.sh
configuration script. Replacepath-to-config.json
with theconfig.json
file that you downloaded from your security profile earlier. Replacedevice-serial-number
with theClient ID
that you entered for the test device that you registered on the Developer Profile that corresponds to theconfig.json
file. Also, make sure to change the"manufacturer name"
and"device description"
values to the actual manufacturer name and device description../genConfig.sh path-to-config.json \ device-serial-number \ $HOME/sdk_folder/db \ $HOME/sdk_folder/avs-device-sdk \ $HOME/sdk_folder/sdk-build/Integration/AlexaClientSDKConfig.json \ -DSDK_CONFIG_MANUFACTURER_NAME="manufacturer name" \ -DSDK_CONFIG_DEVICE_DESCRIPTION="device description"
The CLI window displays confirmation that you successfully created the configuration file.
Completed generation of config file: /Users/me/sdk_folder/sdk-build/Integration/AlexaClientSDKConfig.json
- Navigate to the AVS Device SDK install directory:
Step 5: Run the AVS Device SDK sample app
To confirm that you have installed and configured everything correctly on your computer, run the AVS Device SDK, and then try a few test Alexa commands.
To run the AVS Device SDK
- Navigate to the SampleApp source folder.
cd ~/sdk_folder/sdk-build/SampleApp/src
- Run the sample app.
./SampleApp $HOME/sdk_folder/sdk-build/Integration/AlexaClientSDKConfig.json DEBUG9
The first time that you run the sample app, the text output prompts you to enter a code to authorize the app, as shown in the following example.
################################## # NOT YET AUTHORIZED # ################################## ################################################################################################ # To authorize, browse to: 'https://amazon.com/us/code' and enter the code: {XXXX} # ################################################################################################
To authorize the app
- In a web browser, go to amazon.com/us/code.
- Log in with your Amazon developer credentials.
-
Enter the code shown in your sample app text output.
The sample app running in your CLI window connects to Alexa and displays confirmation that the app is running.
You can now test out the sample app with the enabled mic on your Mac.
To test the sample app
- To ask Alexa a question, press t + Enter. You don't need to include "Alexa" at the start of your question. For example, try, "What time is it?" or "How is the weather?"
- To quit and exit the app, press q + Enter.
If the sample app doesn't work, see Troubleshooting Alexa Smart Screen SDK for troubleshooting tips.
Step 6: Build the APL Core Library
The Alexa Smart Screen SDK has two components: the APL Client Library and the SDK itself. The APL Client Library relies on the APL Core Library.
You must build the APL Core Library before you can build APL Client Library.
To learn more about the APL Core Library, see APL Core Library README.
To build the APL Core Library
- Navigate to the APL Core Library directory.
cd ~/sdk_folder/apl-core-library
- Create and enter a build directory for the APL Core Library.
mkdir build cd build
- Configure
cmake
.cmake ..
- Build the APL Core Library.
make
Your CLI output displays the build status.
[ 6%] Built target enumgen [ 13%] Built target yoga [ 18%] Built target rapidjson-build [ 24%] Built target pegtl-build [100%] Built target apl
Step 7: Build the APL Client Library
Before you build the Smart Screen SDK, you must build the APL Client Library.
To learn more about the APL Client Library, see APL Client Library README.
To build the APL Client Library
-
Navigate to the APL Client Library directory, then create and enter the build directory.
cd ~/sdk_folder/apl-client-library mkdir build cd build
-
Configure a
cmake
command for the APL Client Library.cmake -DAPLCORE_INCLUDE_DIR=$HOME/sdk_folder/apl-core-library/aplcore/include \ -DYOGA_INCLUDE_DIR=$HOME/sdk_folder/apl-core-library/build/yoga-prefix/src/yoga \ -DAPLCORE_LIB_DIR=$HOME/sdk_folder/apl-core-library/build/aplcore \ -DAPLCORE_BUILD_INCLUDE_DIR=$HOME/sdk_folder/apl-core-library/build/aplcore/include \ -DYOGA_LIB_DIR=$HOME/sdk_folder/apl-core-library/build/lib \ -DAPL_CORE=ON \ -DAPLCORE_RAPIDJSON_INCLUDE_DIR=$HOME/sdk_folder/apl-core-library/build/rapidjson-prefix/src/rapidjson/include/ \ -DCMAKE_BUILD_TYPE=DEBUG \ -DAPLCORE_BUILD=$HOME/sdk_folder/apl-core-library/build \ -DBUILD_TESTING=OFF \ -DSTANDALONE=ON \ -DCMAKE_INSTALL_PREFIX=$HOME/sdk_folder/apl-client-library/preinstall \ ..
-
Build the APL Client Library
make -j8
-
Install the APL Client Library
make install
Step 8: Build the Alexa Smart Screen SDK
In this step, you install a few additional dependencies and then build the Smart Screen SDK.
To build the SDK
-
Download and install
websocketpp
.- Navigate to your
third-party
directory.cd ~/sdk_folder/third-party
- Download and extract
websocketpp
.wget https://github.com/zaphoyd/websocketpp/archive/0.8.2.tar.gz -O websocketpp-0.8.2.tar.gz
You should see the following text output.
--2021-12-10 11:22:41-- https://github.com/zaphoyd/websocketpp/archive/0.8.2.tar.gz Resolving github.com (github.com)... 192.30.255.113 Connecting to github.com (github.com)|192.30.255.113|:443... connected. HTTP request sent, awaiting response... 302 Found Location: https://codeload.github.com/zaphoyd/websocketpp/tar.gz/0.8.2 [following] --2021-12-10 11:22:42-- https://codeload.github.com/zaphoyd/websocketpp/tar.gz/0.8.2 Resolving codeload.github.com (codeload.github.com)... 192.30.255.120 Connecting to codeload.github.com (codeload.github.com)|192.30.255.120|:443... connected. HTTP request sent, awaiting response... 200 OK Length: unspecified [application/x-gzip] Saving to: ‘websocketpp-0.8.2.tar.gz’ websocketpp-0.8.2.tar.gz [ <=> ] 684.93K 129KB/s in 5.6s 2021-12-10 11:22:48 (123 KB/s) - ‘websocketpp-0.8.2.tar.gz’ saved [701364]
- Extract
websocketpp
.tar -xvzf websocketpp-0.8.2.tar.gz
You should see output similar to the following truncated example in your CLI window.
x websocketpp-0.8.2/ x websocketpp-0.8.2/.gitattributes x websocketpp-0.8.2/.gitignore x websocketpp-0.8.2/.travis.yml x websocketpp-0.8.2/CMakeLists.txt x websocketpp-0.8.2/COPYING x websocketpp-0.8.2/Doxyfile x websocketpp-0.8.2/SConstruct
- Navigate to your
- Download version 1.12 of the ASIO C++ Library. Unzip the downloaded file into
~/sdk_folder
. Navigate to the unzipped folder and installASIO
by running the following command../configure --without-boost && make && make install
- If you haven't previously installed
Node.js
, installNode.js
.brew install node
- Create and navigate into a build folder for the Smart Screen SDK.
cd ~/sdk_folder mkdir ss-build cd ss-build
- Configure
cmake
.cmake -DCMAKE_PREFIX_PATH=$HOME/sdk_folder/sdk-install \ -DWEBSOCKETPP_INCLUDE_DIR=$HOME/sdk_folder/third-party/websocketpp-0.8.2 \ -DDISABLE_WEBSOCKET_SSL=ON \ -DGSTREAMER_MEDIA_PLAYER=ON \ -DCMAKE_BUILD_TYPE=DEBUG \ -DPORTAUDIO=ON -DPORTAUDIO_LIB_PATH=$HOME/sdk_folder/third-party/portaudio/lib/.libs/libportaudio.a \ -DPORTAUDIO_INCLUDE_DIR=$HOME/sdk_folder/third-party/portaudio/include/ \ -DAPL_CLIENT_INSTALL_PATH=$HOME/sdk_folder/apl-client-library/preinstall \ -DAPL_CLIENT_JS_PATH=$HOME/sdk_folder/apl-client-library/apl-client-js \ -DPKCS11=OFF \ ../alexa-smart-screen-sdk
The following example shows truncated output from
cmake
.No keyword detector type specified, skipping build of keyword detector. Bluetooth implementation not supported Creating the build directory for the CapabilityAgents with build type: DEBUG No keyword detector type specified, skipping build of keyword detector. Bluetooth implementation not supported -- Could NOT find GTest (missing: GTEST_LIBRARY GTEST_INCLUDE_DIR GTEST_MAIN_LIBRARY) -- Could NOT find GTest (missing: GTEST_LIBRARY GTEST_INCLUDE_DIR GTEST_MAIN_LIBRARY) Creating the build directory for the ApplicationUtilities with build type: DEBUG No keyword detector type specified, skipping build of keyword detector. Bluetooth implementation not supported Creating the build directory for the SmartScreenClient with build type: DEBUG
…
WARNING: Target "SampleApp" requests linking to directory "/usr/local/Cellar/gst-plugins-base/1.16.1/lib". Targets may link only to libraries. CMake is dropping the item. WARNING: Target "SampleApp" requests linking to directory "/usr/local/Cellar/glib/2.62.1/lib". Targets may link only to libraries. CMake is dropping the item. WARNING: Target "SampleApp" requests linking to directory "/usr/local/opt/gettext/lib". Targets may link only to libraries. CMake is dropping the item. -- Generating done -- Build files have been written to: /Users/me/sdk_folder/ss-build
- Build the Smart Screen SDK.
make
Your screen output should look similar to the following example.
[ 5%] Built target AlexaPresentation [ 15%] Built target gmock_main [ 21%] Built target AlexaPresentationTest [ 26%] Built target SmartScreenTemplateRunTime [ 31%] Built target TemplateRuntimeTest [ 42%] Built target SmartScreenClient [100%] Built target SampleApp npm WARN gui@1.0.0 No repository field. npm WARN gui@1.0.0 license should be a valid SPDX license expression audited 6584 packages in 3.62s found 0 vulnerabilities > gui@1.0.0 build /Users/me/sdk_folder/Alexa-smart-screen-sdk/modules/GUI/js > npm run lint && webpack --config webpack.config.js "--output-path" "/Users/me/sdk_folder/ss-build/modules/GUI" "--define" "DISABLE_WEBSOCKET_SSL=true" > gui@1.0.0 lint /Users/me/sdk_folder/Alexa-smart-screen-sdk/modules/GUI/js > tslint --project tsconfig.json -c tslint.json 'src/**/*.ts' 'src/**/.tsx' Hash: 12462024bc3092060422 Version: webpack 4.41.2 Time: 13419ms Built at: 10/22/2019 3:30:20 PM Asset Size Chunks Chunk Names ../dist/app.d.ts 2.99 KiB [emitted] ../dist/components/buttonInterface.d.ts 285 bytes [emitted] ../dist/components/home.d.ts 144 bytes [emitted] ../dist/components/nowplaying.d.ts 265 bytes [emitted] ../dist/components/serverSideRenderer.d.ts 1.5 KiB [emitted] ../dist/environment.d.ts 103 bytes [emitted] ../dist/lib/Environment.d.ts 248 bytes [emitted] ../dist/lib/NavigationEvent.d.ts 339 bytes [emitted] ../dist/lib/activity/ActivityEvent.d.ts 554 bytes [emitted] ../dist/lib/activity/ActivityTracker.d.ts 1.09 KiB [emitted] ../dist/lib/avshelpers.d.ts 1.07 KiB [emitted] ../dist/lib/client.d.ts 1.7 KiB [emitted] ../dist/lib/device/ExtraLargeTV.d.ts 217 bytes [emitted] ../dist/lib/device/LargeHub.d.ts 213 bytes [emitted] ../dist/lib/device/MediumHub.d.ts 214 bytes [emitted] ../dist/lib/device/device.d.ts 975 bytes [emitted] ../dist/lib/focus/ChannelName.d.ts 343 bytes [emitted] ../dist/lib/focus/FocusManager.d.ts 2.06 KiB [emitted] ../dist/lib/focus/FocusResource.d.ts 296 bytes [emitted] ../dist/lib/focus/FocusState.d.ts 183 bytes [emitted] ../dist/lib/focus/IChannelObserver.d.ts 236 bytes [emitted] ../dist/lib/focus/IFocusBridge.d.ts 248 bytes [emitted] ../dist/lib/media/AVSAudioPlayer.d.ts 1.25 KiB [emitted] ../dist/lib/media/AVSVideo.d.ts 1.43 KiB [emitted] ../dist/lib/messages.d.ts 3.22 KiB [emitted] ../dist/lib/screen.d.ts 179 bytes [emitted] ../dist/lib/sdkLogTransport.d.ts 842 bytes [emitted] ../dist/main.d.ts 21 bytes [emitted] ../dist/model/renderPlayerInfo.d.ts 976 bytes [emitted] 20db d5eaf289a6e63cf91f8c05c37cf6.png 5.34 KiB [emitted] index.html 187 bytes [emitted] main.bundle.js 4.18 MiB main [emitted] main Entrypoint main = main.bundle.js [../../apl-client/index.js] /Users/me/sdk_folder/Alexa-smart-screen-sdk/modules/GUI/apl-client/index.js 490 KiB {main} [built] [../node_modules/css-loader/dist/cjs.js!./main.css] 4.46 KiB {main} [built] [./app.tsx] 13.5 KiB {main} [built] [./images/alexa.png] 82 bytes {main} [built] [./lib/NavigationEvent.ts] 648 bytes {main} [built] [./lib/activity/ActivityEvent.ts] 883 bytes {main} [built] [./lib/activity/ActivityTracker.ts] 2.1 KiB {main} [built] [./lib/avshelpers.ts] 2.26 KiB {main} [built] [./lib/client.ts] 3.45 KiB {main} [built] [./lib/device/device.ts] 2.26 KiB {main} [built] [./lib/focus/FocusManager.ts] 3.71 KiB {main} [built] [./lib/screen.ts] 529 bytes {main} [built] [./lib/sdkLogTransport.ts] 1.7 KiB {main} [built] [./main.tsx] 885 bytes {main} [built] + 33 hidden modules Child html-webpack-plugin for "index.html": 1 asset Entrypoint undefined = index.html 4 modules [100%] Built target GUIClient
Step 9: Run the Alexa Smart Screen SDK sample app
After you have successfully built the AVS Device SDK, APL Core Library, APL Client Library, and Alexa Smart Screen SDK, you can run and experiment with the Alexa Smart Screen SDK sample app on your Mac.
To run the sample app
- Navigate into your Smart Screen SDK build folder.
cd ~/sdk_folder/ss-build
- Run the sample app, making sure to point to the correct path where you generated your configuration file.
./modules/Alexa/SampleApp/src/SampleApp -C ~/sdk_folder/sdk-build/Integration/AlexaClientSDKConfig.json -C ~/sdk_folder/alexa-smart-screen-sdk/modules/GUI/config/SmartScreenSDKConfig.json -L INFO
If you receive any error messages at this step, check Troubleshooting Alexa Smart Screen SDK, which addresses several common sample app execution errors for macOS. You can also try running the sample again, changing the verbosity level from
INFO
toDEBUG9
.When the app successfully initializes and runs, your CLI window displays scrolling text output similar to the following truncated example.
Running app with log level: DEBUG0 2019-10-23 17:53:31.864 [ 1] 0 ConfigurationNode:initializeSuccess 2019-10-23 17:53:32.023 [ 1] I LocaleAssetsManager:initialize:supportedWakeWords=NONE 2019-10-23 17:53:32.033 [ 6] I WebSocketServer:Listening for websocket connections:interface=127.0.0.1,port=8933 2019-10-23 17:53:32.198 [ 1] I Setting:handleSetValue:value=false 2019-10-23 17:53:32.205 [ 1] I Setting:handleSetValue:value="NONE" 2019-10-23 17:53:32.206 [ 1] I Setting:handleSetValue:value="NONE" 2019-10-23 17:53:32.207 [ 1] I Setting:handleSetValue:value="America/Vancouver" 2019-10-23 17:53:32.209 [ 11] I LocaleAssetsManager:changeAssets:Locale=["en-US"],WakeWords=[] 2019-10-23 17:53:32.219 [ 14] 0 MediaPlayer:handleSetObserverCalled:name=SystemSoundMediaPlayer 2019-10-23 17:53:32.225 [ 17] 0 MediaPlayer:handleSetObserverCalled:name=SpeakMediaPlayer 2019-10-23 17:53:32.232 [ 1a] 0 MediaPlayer:handleSetObserverCalled:name=AudioMediaPlayer 2019-10-23 17:53:32.234 [ 1] 0 SpeakerManager:mapCreated:numSpeakerVolume=6,numAlertsVolume=1 2019-10-23 17:53:32.243 [ 1d] 0 MediaPlayer:handleSetObserverCalled:name=AlertsMediaPlayer 2019-10-23 17:53:32.254 [ 20] 0 MediaPlayer:handleSetObserverCalled:name=NotificationsMediaPlayer 2019-10-23 17:53:32.260 [ 1] 0 ExternalMediaPlayer:createAdapters ################################################# # NOTIFICATION INDICATOR STATE: OFF # ################################################# ...
-
To view and interact with Alexa in your web browser, navigate to
~/sdk_folder/ss-build/modules/GUI
, and open theindex.html
file in a web browser.Your web browser displays the Alexa Smart Screen splash screen.
-
Press and hold the A key on your keyboard to interact with Alexa. For example, with your mic and speakers enabled, press and hold the A key and ask, "What time is it?" (You don't need to preface your question with "Alexa.")
Alexa responds with the current time.
-
To try a question with a visual component, press and hold the A key and ask, "How is the weather?"
Alexa recites and displays the current forecast.
-
Try some of these other questions to explore various Alexa skills.
- "Who is Jeff Bezos?"
- "Tell me a joke."
- "What does a Corgi look like?"
- "Play Jeopardy."
- "Open Food Network."
- To end the session, press Ctrl+C in your CLI window.
To learn more about the things that you can try with the Smart Screen SDK, see the Alexa Multi-Modal API Overview.
Optional features
Now that you've installed the Alexa Smart Screen SDK and tested it by running the sample app, you can add optional features, such as captions, to your device.
Add captions
The following procedure shows how to add captions to your device.
webvtt
GitHub repository.To add captions to your device
-
Download and install
webvtt
in a directory that's independent of the SDK directories, for example,$HOME/captions
. - Build the AVS Device SDK as you did in Step 4: Build the AVS Device SDK, only this time include
webvtt
by adding the following flags when you configure yourcmake
command.-DCAPTIONS=ON \ -DLIBWEBVTT_LIB_PATH=$HOME/captions/webvtt-master/build/src/webvtt/libwebvtt.a \ -DLIBWEBVTT_INCLUDE_DIR=$HOME/captions/webvtt-master/include
- Build the Alexa Smart Screen SDK as you did in Step 8: Build the Alexa Smart Screen SDK, only this time include
webvtt
by adding the following flags when you configure yourcmake
command.-DCAPTIONS=ON \ -DLIBWEBVTT_LIB_PATH=$HOME/captions/webvtt-master/build/src/webvtt/libwebvtt.a \ -DLIBWEBVTT_INCLUDE_DIR=$HOME/captions/webvtt-master/include
- Run the Alexa Smart Screen SDK sample app as you did in Step 9: Run the Alexa Smart Screen SDK sample app. Captions aren't enabled by default. After opening the sample app in the browser, press the C key on your keyboard to toggle captions on. The caption setting persists across restarts.
Modify the Smart Screen SDK configuration file for your device
For guidance on using the configuration file to define your device's visual capabilities, functionality, and supported server communication, see the Smart Screen SDK Config Specification.
Related topics
Last updated: Sep 28, 2022