December 31, 2023
+ January 23, 2024
diff --git a/search/search_index.json b/search/search_index.json
index 5c45bee..43c8566 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-,:!=\\[\\]()\"`/]+|\\.(?!\\d)|&[lg]t;|(?!\\b)(?=[A-Z][a-z])","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Welcome","text":""},{"location":"#welcome","title":"Welcome","text":"ovos-docker is one of the fastest ways to get started with Open Voice OS.
"},{"location":"#quickstart","title":"Quickstart","text":"A nice, simple and intuitive way to install Open Voice OS and/or HiveMind using Bash, Whiptail (Newt) and Ansible.
curl, git and sudo packages must be installed before running the installer.
sh -c \"curl -s https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh -o installer.sh && chmod +x installer.sh && sudo ./installer.sh && rm installer.sh\"\nThen follow the instructions displayed on screen then you will be all set !
"},{"location":"#getting-started","title":"Getting started","text":"Want to give Open Voice OS a try? Open Voice OS is an open source software that runs where you want it to, whether it\u2019s on your own hardware or one of the dedicated Mark 1 or Mark II.
Docker
arm64 x86_64
Use container engine such as Docker or Podman and their composer to run a complete, secure, isolated and \"easy to update\" instance of Open Voice OS!
Getting started with Docker
"},{"location":"quickstart/","title":"Quickstart","text":""},{"location":"quickstart/#quickstart","title":"Quickstart","text":"A nice, simple and intuitive way to install Open Voice OS and/or HiveMind using Bash, Whiptail (Newt) and Ansible.
curl, git and sudo packages must be installed before running the installer.
sh -c \"curl -s https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh -o installer.sh && chmod +x installer.sh && sudo ./installer.sh && rm installer.sh\"\nThen follow the instructions displayed on screen then you will be all set !
"},{"location":"about/what-is-it/","title":"What is it?","text":""},{"location":"about/what-is-it/#what-is-open-voice-os","title":"What is Open Voice OS?","text":"Open Voice OS is a free and open source personal assistant and smart speaker that offers a powerful and flexible alternative to proprietary solutions like Amazon\u2122 Alexa\u2122, Google Assistant\u2122, Microsoft Cortana\u2122 or Apple's Siri\u2122.
At the same time, it is also an open virtual assistant platform that enables developers and organizations to create custom voice-controlled applications. With its cutting-edge technology and user-friendly design, Open Voice OS is revolutionizing the way we interact with technology.
The platform provides a comprehensive suite of features that makes it easy to deploy voice-based applications for a wide range of use cases, including home automation, entertainment, education, and more. With natural language processing, multi-device compatibility, a customizable UI, robust APIs, and a focus on privacy and security, Open Voice OS delivers a highly responsive and accurate experience for users.
Open Voice OS is the perfect choice for anyone who wants a personal assistant and smart speaker that gives them complete control over their data and the ability to customize their experience.
In addition to its voice capabilities, Open Voice OS also features a touch-screen GUI made using QT and the KDE frameworks, providing an intuitive and user-friendly interface. And with its open source nature, anyone with technical skills can contribute to the platform and help shape its future.
"},{"location":"about/why-use-ovos/","title":"Why use OVOS?","text":""},{"location":"about/why-use-ovos/#why-use-ovos","title":"Why use OVOS?","text":"Whether you prefer voice commands or a more traditional touch interface, Open Voice OS has you covered, and the option to run the platform fully offline gives you complete control over your data and ensures that your information is never shared with third parties.
With its powerful and flexible features, Open Voice OS is the ideal choice for anyone who wants a voice-controlled virtual assistant and smart speaker that offers complete control and customization. Whether you\u2019re a software developer, data scientist, or just someone with a passion for technology, be sure to check out Open Voice OS today!
"},{"location":"about/why-use-ovos/#multi-device-compatibility","title":"Multi-device compatibility","text":"Open Voice OS can be integrated with a wide range of devices making it easy for you to access and control your virtual assistant no matter where you are.
Smart speakers Smartphones System on a chip (SoC) Laptops Televisions "},{"location":"about/why-use-ovos/#customizable-ui","title":"Customizable UI","text":"With its easy-to-use GUI interface, Open Voice OS allows developers to create custom interfaces that match their specific brand and style. Whether you\u2019re a business looking to integrate voice control into your product offerings, or a home user who wants a unique interface that matches your personal style, Open Voice OS has you covered.
"},{"location":"about/why-use-ovos/#robust-modular","title":"Robust & Modular","text":"Open Voice OS leverages the power of skills and plugins to create a robust and modular virtual assistant platform, offering unparalleled customization and extension capabilities.
"},{"location":"about/why-use-ovos/#fully-offline","title":"Fully offline","text":"Open Voice OS can run without the use of any online Text-To-Speech (TTS) or Speech-To-Text (STT) services, so you don\u2019t have to rely on anyone keeping their servers up or recording your requests.
"},{"location":"about/why-use-ovos/#privacy-and-security","title":"Privacy and security","text":"Open Voice OS is designed with privacy and security in mind. Whether you\u2019re concerned about the security of your personal information or the privacy of your voice commands, Open Voice OS provides peace of mind.
"},{"location":"about/glossary/components/","title":"Components","text":""},{"location":"about/glossary/components/#components","title":"Components","text":"Open Voice OS is very modular which means instead of a big monolith block of code, multiple projects exist around the OVOS ecosystem with each of them having their own role to play in order to deliver the best and fastest experience.
"},{"location":"about/glossary/components/#ovos-audio","title":"ovos-audio","text":"The audio service is responsible for loading Text-To-Speech and audio plugins.
All audio playback (sounds played on the speakers) is handled by this service by leveraging the sound server/service from the system where its running.
"},{"location":"about/glossary/components/#ovos-common-play","title":"ovos-common-play","text":"OVOS Common Play (OCP) is a full-fledged voice media player packaged as an audio plugin.
OCP handles the whole voice integration and playback functionality, it also integrates with external players via Media Player Remote Interfacing Specification (MPRIS).
"},{"location":"about/glossary/components/#ovos-config","title":"ovos-config","text":"Helper package to interact with OVOS configuration. A small tool is included to quickly show, get or set config values.
"},{"location":"about/glossary/components/#ovos-core","title":"ovos-core","text":"The skills service is responsible for loading skills and intent parsers, all user queries are handled by the skills service.
This is the brains of the device. Without it, you would have some cool software that does not work together. It controls the skills service and directs intents to the right skill.
"},{"location":"about/glossary/components/#ovos-classifiers","title":"ovos-classifiers","text":"Base implementations for Natural language processing (NPL) tasks, from baseline heuristics to classic machine learning models that run everywhere.
"},{"location":"about/glossary/components/#ovos-gui","title":"ovos-gui","text":"OVOS uses the standard Mycroft GUI framework, you can find the official documentation here.
The GUI is an open source visual and display framework running on top of KDE Plasma Technology and built using Kirigami a lightweight user interface framework for convergent applications which are empowered by QT.
Component dependency
This component depends on ovos-gui-messagebus.
"},{"location":"about/glossary/components/#ovos-gui-messagebus","title":"ovos-gui-messagebus","text":"GUI messagebus service, manages GUI state and implements the GUI protocol.
The GUI service provides a websocket for gui clients to connect to, it is responsible for implementing the gui protocol under ovos-core.
GUI clients (the application that actually draws the GUI) connect to this service.
"},{"location":"about/glossary/components/#ovos-listener","title":"ovos-listener","text":"The listener (also known as speech) is responsible for loading STT, VAD and wake word plugins. Speech is transcribed into text (intent) and forwarded to the core service.
The newest listener that OVOS uses is ovos-dinkum-listener. It is a version of the listener from the Mycroft Dinkum software for the Mark 2 modified for use with OVOS.
"},{"location":"about/glossary/components/#ovos-messagebus","title":"ovos-messagebus","text":"The message bus service provides a websocket where all internal events travel, you can think of the bus service as Open Voice OS's nervous system.
Internal usage only
The bus is considered as an internal and private websocket, external clients should not connect directly to it. Please check HiveMind for more information. For more detail please go to the System Hardening section
"},{"location":"about/glossary/components/#ovos-phal","title":"ovos-phal","text":"Plugin based Hardware Abstraction Layer is a wrapper for software system level abstraction, where based on the environment either through known configuration or via fingerprinting, only specific plugins load to interface with the system and specific hardware.
A PHAL plugin can provide anything from hardware integrations (ReSpeaker, Mark1, Mark2, etc...) or system integrations (Network-Manager, OVOS Shell, etc...).
Any number of plugins providing functionality can be loaded and validated at runtime, plugins can be system integrations to handle things like reboot and shutdown, or hardware drivers such as Mycroft Mark2 plugin.
PHAL admin variant
In addition of the initial PHAL service, PHAL admin is running as root or as a priviledged user. This variant allows PHAL admin to perform actions which require more privileges such as reboot for example.
"},{"location":"about/glossary/components/#ovos-plugin-manager","title":"ovos-plugin-manager","text":"OPM is the OVOS Plugin Manager, this base package provides arbitrary plugins to the OVOS ecosystem. OPM plugins import their base classes from OPM making them portable and independent of ovos-core, plugins can be used in a standalone projects.
By using OPM you can ensure a standard interface to plugins and easily make them configurable in your project.
"},{"location":"about/glossary/components/#ovos-shell","title":"ovos-shell","text":"OVOS Shell is the Open Voice OS client implementation of the ovos-gui library, basically it represents the OVOS graphical layer on top of Mycroft GUI.
Component dependency
This component depends on ovos-gui.
"},{"location":"about/glossary/components/#ovos-utils","title":"ovos-utils","text":"Just a collection of simple utilities and functions for use across the components from the OVOS ecosystem.
"},{"location":"about/glossary/components/#ovos-workshop","title":"ovos-workshop","text":"Workshop contains skill base classes and supporting tools to build skills and applications for Open Voice OS systems.
"},{"location":"about/glossary/components/#padacioso","title":"padacioso","text":"A lightweight, dead-simple intent parser which aim to replace the current intent parser; Padatious.
"},{"location":"about/glossary/terms/","title":"Terms","text":""},{"location":"about/glossary/terms/#glossary","title":"Glossary","text":"Use our Glossary to learn more about the specialist terms that we use in natural language processing generally, and more specifically with Open Voice OS software.
"},{"location":"about/glossary/terms/#fallback","title":"Fallback","text":"A skill that is designated to be a 'catch-all' when Open Voice OS cannot interpret the intent from an utterance.
"},{"location":"about/glossary/terms/#hivemind","title":"HiveMind","text":"HiveMind is a community-developed superset or extension of Open Voice OS the open-source voice operating system.
With HiveMind, you can extend an instance of Open Voice OS to as many devices as you want, including devices that can't ordinarily run Open Voice OS!
HiveMind could be considered as an external Open Voice OS component leaving its \"own\" life under its \"own\" lifecycle.
"},{"location":"about/glossary/terms/#hotword","title":"Hotword","text":"See wake word.
"},{"location":"about/glossary/terms/#intent","title":"Intent","text":"When a user speaks an utterance to Open Voice OS, Open Voice OS tries to interpret the intent of the utterance, and match the intent with a skill.
"},{"location":"about/glossary/terms/#playback","title":"Playback","text":"Playback is the audio output going through the speakers, for example when asking What's the temperature?, OVOS will speaks to you using the playback capability.
"},{"location":"about/glossary/terms/#plugin","title":"Plugin","text":"A plugin allows you to install \"small bricks\" of functionnalities using OVOS Plugin Manager in order to make your voice assistant more capable.
Open Voice OS uses many plugins in many different areas:
Wake word plugin VAD plugins Microphone plugins PHAL plugins TTS plugins STT plugins etc... "},{"location":"about/glossary/terms/#skill","title":"Skill","text":"When Open Voice OS hears the wake word, then an utterance, Open Voice OS will try to find a skill that matches the utterance. The skill might fetch some data, or play some audio, or speak, or display some information.
If Open Voice OS can't find a skill that matches the utterance, he will tell you he doesn't understand and fallback (when configured).
"},{"location":"about/glossary/terms/#speech-to-text-stt","title":"Speech-To-Text (STT)","text":"Speech-To-Text is what converts your voice into a text which becomes a commands that OVOS recognizes, then converts to an intent that is used to activate skills.
Several options are available each with different attributes and supported languages. Some can be run on device, others need an internet connection to work.
"},{"location":"about/glossary/terms/#text-to-speech-tts","title":"Text-To-Speech (TTS)","text":"Text-To-Speech is responsible for converting text into audio for playback (verbal response from OVOS).
Several options are available each with different attributes and supported languages. Some can be run on device, others need an internet connection to work.
"},{"location":"about/glossary/terms/#utterance","title":"Utterance","text":"An utterance is how you interact with Open Voice OS. An utterance is a command or question - like What's the weather like in Kansas City? or Tell me about the Pembroke Welsh Corgi.
"},{"location":"about/glossary/terms/#vad","title":"VAD","text":"Voice Activity Detection is used by the listener to determine when a user stopped speaking, this indicates the voice command is ready to be executed.
"},{"location":"about/glossary/terms/#wake-word","title":"Wake Word","text":"The wake word is the phrase or word you use to (wake up) tell Open Voice OS you're about to issue a command.
"},{"location":"getting-started/docker/","title":"Docker or Podman","text":""},{"location":"getting-started/docker/#docker-or-podman","title":"Docker or Podman","text":"Before going further, here are quick and simple definitions of what a container is and what a composer is, these definitions are important and must be well understood before starting.
Two engines, same definition
Both of the definitions described below are valid for either Docker or Podman.
"},{"location":"getting-started/docker/#container-definition","title":"Container definition","text":"A container is a standard unit of software that packages up code and all its dependencies so the application runs quickly and reliably from one computing environment to another. A container image is a lightweight, standalone, executable package of software that includes everything needed to run an application.
Initial source
"},{"location":"getting-started/docker/#composer-definition","title":"Composer definition","text":"A composer is a tool for defining and running multi-container container applications. With Compose, you use a YAML file to configure your application\u2019s services. Then, with a single command, you create and start all the services from your configuration.
Initial source
"},{"location":"getting-started/docker/cli/","title":"OVOS command line","text":""},{"location":"getting-started/docker/cli/#open-voice-os-command-line","title":"Open Voice OS command line","text":"The command line allows you to send a message (but not only) directly to the message bus by using the ovos-cli-client command from the ovo_cli container.
Skill interactions
The command line doesn't support any action related to skills other than :skills as this setup is running inside containers. Please read the skill section to manage skills.
"},{"location":"getting-started/docker/cli/#ovos-cli-client","title":"ovos-cli-client","text":"ovos-cli-client is deprecated
Please read https://github.com/OpenVoiceOS/ovos-cli-client/issues/14 for more information.
Interact directly with the ncurses OVOS client interface.
DockerPodman docker exec --interactive --tty ovos_cli ovos-cli-client\npodman exec --interactive --tty ovos_cli ovos-cli-client\nTo display or manage the current configuration, the ovos-config command could be used.
read-write access to the configuration
The ovos_cli container is the only one having read-write access to the mycroft.conf configuration file.
DockerPodman docker exec --interactive --tty ovos_cli ovos-config show\npodman exec --interactive --tty ovos_cli ovos-config show\nvim as default editor
vim and nano editors are available within the ovos-cli image, vim has been set as default.
"},{"location":"getting-started/docker/cli/#ovos-speak","title":"ovos-speak","text":"An easy way to make Open Voice OS speaks is to run the ovos-speak command.
DockerPodman docker exec --interactive --tty ovos_cli ovos-speak \"hello world\"\npodman exec --interactive --tty ovos_cli ovos-speak \"hello world\"\nNeon Mana (Messagebus Application for Neon AI) provides tools for interacting with the message bus.
DockerPodman docker exec --interactive --tty ovos_cli mana --help\npodman exec --interactive --tty ovos_cli mana --help\nThe easiest and quickest way to deploy Open Voice OS containers is to use a composer such as docker composer or podman-compose.
"},{"location":"getting-started/docker/composition/#composition-files","title":"Composition files","text":"Composition files provide an easy way to provision the stack (services and volumes) with the required options and configuration for each of the services.
Compose file Platforms Description docker-compose.yml Install core components (except the GUI) docker-compose.gui.yml Install GUI components docker-compose.skills.yml Install pre-defined skills docker-compose.hivemind.yml Install HiveMind components docker-compose.macos.yml Install core components (except the GUI) docker-compose.windows.yml Install core components (except the GUI) docker-compose.raspberrypi.yml Add GPIO support to ovos_core component docker-compose.raspberrypi.gui.yml Add /dev/vchiq to ovos_gui component"},{"location":"getting-started/docker/composition/#environment-files","title":"Environment files","text":"A Docker or Podman environment file contains lines about environment variables that are usable by the Docker or Podman command line. It is a convenient way to pass many environment variables to a single command.
Environment file Platforms Description .env Set of variables used by the composition files .env-raspberrypi Add GPIO_GID, I2C_GID and SPI_GID variables Some variables might need to be tuned to match your setup such as the TZ, XDG_RUNTIME_DIR, etc...
Variable Default Platforms Description DISPLAY :0 Display used by X or Wayland GPIO_GID 997 gpio group ID on Raspberry Pi HIVEMIND_CONFIG_FOLDER ~/hivemind/config HiveMind configuration directory HIVEMIND_CONFIG_PHAL_FOLDER ~/hivemind/config/phal HiveMind PHAL configuration directory HIVEMIND_SHARE_FOLDER ~/hivemind/share HiveMind shared directory HIVEMIND_USER hivemind User running in the container I2C_GID 994 i2c group ID on Raspberry Pi INPUT_GID 102 input group ID OVOS_CONFIG_FOLDER ~/ovos/config OVOS configureation directory OVOS_CONFIG_PHAL_FOLDER ~/ovos/config/phal OVOS PHAL configureation directory OVOS_SHARE_FOLDER ~/ovos/share OVOS shared directory OVOS_USER ovos User running in the container PULL_POLICY always Policy to pull Docker images RENDER_GID 106 render group ID SPI_GID 995 spi group ID on Raspberry Pi TMP_FOLDER ~/ovos/tmp OVOS temporary directory TZ America/Montreal Timezone to set in the container VERSION alpha Container image tag to pull VIDEO_GID 44 video group ID XDG_RUNTIME_DIR /run/user/1000 Path to XDG runtime directory Do not change OVOS_USER or HIVEMIND_USER
The OVOS_USER and HIVEMIND_USER variables should not be changed except if you build your own container images which a different one.
"},{"location":"getting-started/docker/composition/#how-to-get-the-gid","title":"How to get the GID?","text":"The getent command could be used in order to get the GID of gpio and render groups.
Raspberry PiLinux getent group gpio\ngetent group render\ngetent group video\ngetent group input\ngetent group i2c\ngetent group spi\ngetent group render\ngetent group video\ngetent group input\nThe XDG_RUNTIME_DIR variables requires a UID, this UID is the unique ID of the current user which will run the docker compose or podman-compose command.
LinuxWindows WSL2 echo $UID\necho $UID\nXDG Base Directory
Mac OS doesn't leverage XDG_RUNTIME_DIR variable as there is no support of XDG Base Directory on Mac OS.
"},{"location":"getting-started/docker/debug/","title":"Debugging","text":""},{"location":"getting-started/docker/debug/#debugging","title":"Debugging","text":""},{"location":"getting-started/docker/debug/#enable-debug-mode","title":"Enable debug mode","text":"First thing's first, enable the Open Voice OS's debug mode in ~/ovos/config/mycroft.conf to get more verbosity from the logs.
Restart containers
All containers will have to be restarted to receive the configuration change.
docker restart --time 0 $(docker container list --all --filter 'name=ovos' --filter 'name=hivemind' --quiet)\n{\n \"debug\": true,\n \"log_level\": \"DEBUG\"\n}\nNote
The commands below don't have to be executed in the same order as they are presented, free free to run them in the order you want!
"},{"location":"getting-started/docker/debug/#all-containers-logs","title":"All containers logs","text":"Access all the container logs at the same time, run the following command (make sure it matches the docker compose or podman-compose command you run to deploy the stack).
DockerPodman docker compose --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml --env-file .env logs --follow --tail 200\npodman-compose --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml --env-file .env logs --follow --tail 200\nAccess the logs of a specific container.
DockerPodman docker logs --follow --tail 200 ovos_audio\npodman logs --follow --tail 200 ovos_audio\nExecute a command inside a container without going into it.
DockerPodman docker exec --tty --interactive ovos_audio pactl info\npodman exec --tty --interactive ovos_audio pactl info\nGo inside a container and run multiple commands (where sh is the available shell in there).
DockerPodman docker exec --tty --interactive ovos_audio sh\npodman exec --tty --interactive ovos_audio sh\nMake sure the mycroft.conf configuration file is JSON valid by using the jq command.
jq command
In order to use the jq command, the package should be installed on your operating system.
cat ~/ovos/config/mycroft.conf | jq\nIf the configuration file is not valid JSON, jq will return something like this:
parse error: Expected another key-value pair at line 81, column 3\nGet the CPU, memory and I/O consumption per container.
DockerPodman docker stats --all --no-trunc\npodman stats --all --no-trunc\nGet the disk usage per volumes.
DockerPodman docker system df\npodman system df\nPre-build images
Open Voice OS provides pre-build images available on Docker Hub. These images are referenced by default within the docker-compose.*.yml files.
Open Voice OS is a sofisticated piece of software which has several components. These components have been split into containers to provide a better isolation and a microservices approach.
GUI images size
The GUI container images are larger than the other images as they need many QT libraries and GStreamer plugins in order to provide all the features supported by the voice assistant.
"},{"location":"getting-started/docker/images/#supported-cpu-architectures","title":"Supported CPU architectures","text":"Container images could be used for different CPU architectures using the multi-platform images feature.
CPU architecture Description amd64 Such as AMD and Intel processors aarch64 Such as Raspberry Pi 64-bit SoC armv7l Such as Raspberry Pi 32-bit SoC (not supported because of onnxruntime1 )"},{"location":"getting-started/docker/images/#containers","title":"Containers","text":"The list below is not exhaustive and doesn't mention anything about skill containers, but it is a fair list of the main components currently supported in ovos-docker.
Container Description ovos_messagebus Read more about ovos-messagebus ovos_phal Read more about ovos-phal ovos_phal_admin Read more about ovos-phal admin variant ovos_audio Read more about ovos-audio ovos_listener Read more about ovos-listener ovos_core Read more about ovos-core ovos_cli Read more about ovos-cli ovos_gui_websocket Read more about ovos-gui-messagebus ovos_gui Read more about ovos-gui hivemind_listener Read more about hivemind-listener hivemind_cli Read more about hivemind-cli"},{"location":"getting-started/docker/images/#tags","title":"Tags","text":"Container image tags allows you to deploy a specific version of Open Voice OS, it could be an untested version based on nigthly build or a stable version.
Image tag Description alpha Nightly build based on alpha releases from PyPi 0.0.8a Nightly build based on alpha releases from PyPi stable Build at every new stable release 0.0.8 Build at every new stable release Stable release
As Open Voice OS doesn't have a stable release for version 0.0.8 which has been designed to work with containers, there is no stable or 0.0.8 tags available yet.
"},{"location":"getting-started/docker/images/#volumes","title":"Volumes","text":"To allow data persistence, Docker or Podman volumes are required, they will prevent downloading the requirements everytime the containers are re-created.
Volume Description ovos_gui_file Share QML files from skills between the GUI message bus and the GUI client ovos_listener_records Wake words and utterances recorded samples ovos_local_state Moslty used to store logs from the different components ovos_models Models downloaded by precise-lite wake word plugin ovos_nltk Punkt Python package required by NLTK ovos_tts_cache .wav and .pho files acting as cache from TTS transcription ovos_vosk Models downloaded by VOSK during the initial boot ovos_listener_records allows you to store samples of wake words and utterances which could help you to build or improve models.
Enable samples recording
By default the recording features are disabled, \"record_wake_words\": true and \"save_utterances\": true will have to be added to the listener section of mycroft.conf to enable these capabilities.
~/ovos/config/mycroft.conf{\n\"listener\": {\n \"record_wake_words\": true,\n \"save_utterances\": true\n }\n}\nBut first thing's first you need to have Open Voice OS's containers up and running. Follow the guide.
https://github.com/microsoft/onnxruntime/issues/15337 \u21a9
"},{"location":"getting-started/docker/update/","title":"Update Open Voice OS","text":""},{"location":"getting-started/docker/update/#update-open-voice-os","title":"Update Open Voice OS","text":"Exact same command
In order to update the deployed stack (services and volumes), you must use the exact same command that has been used during the initial stack deployment.
The easiest and quickest way to update an Open Voice OS stack already deployed by docker compose or podman-compose is; of course to use docker compose or podman-compose as well.
Podman users
If you are running Podman instead of Docker, replace docker compose with podman-compose.
Raspberry PiLinuxMac OSWindows WSL2 docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml up --detach\ndocker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml up --detach\ndocker compose --project-name ovos --file docker-compose.macos.yml --file docker-compose.skills.yml --env-file .env up --detach\ndocker compose --project-name ovos --file docker-compose.windows.yml --file docker-compose.skills.yml up --detach\nBecause the pull_policy option of each service is set to always, everytime that a new image is uploaded with the same tag docker compose or podman-compose will pull-it and re-create the container based on this new image.
Change the version
If you want to change the image's tag to deploy, update the .env file with the right one. The alpha tag images are rebuilt every nights with the latest commits from the dev branch.
"},{"location":"getting-started/docker/installation/basic/","title":"Core components","text":""},{"location":"getting-started/docker/installation/basic/#install-open-voice-os","title":"Install Open Voice OS","text":"This section covers the installation of the core components only.
Only core components
Keep following the documentation if you want to install some pre-selected skills, HiveMind or even the GUI.
"},{"location":"getting-started/docker/installation/basic/#deploy-the-stack","title":"Deploy the stack","text":"Before running the docker compose or podman-compose commands, please read this section first.
Podman users
If you are running Podman instead of Docker, replace docker compose with podman-compose.
Raspberry PiLinuxMac OSWindows WSL2 docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml up --detach\ndocker compose --project-name ovos --file docker-compose.yml up --detach\ndocker compose --project-name ovos --file docker-compose.macos.yml --env-file .env up --detach\ndocker compose --project-name ovos --file docker-compose.windows.yml up --detach\nDepending your Internet speed, your Wi-Fi or Ethernet connection speed and your hardware (I/O), the whole process could take several minutes.
Hardware Time Raspberry Pi 3B+ with USB drive ~20 minutes Raspberry Pi 4B with USB drive ~3 minutes MacBook Air i7 Early 2015 with SSD ~2.5 minutes AMD Ryzen 7 5800 with NVMe drive ~45 seconds Resources overhead
To reduce the potential ressources overhead due to the image downloads and extractions, the --parallel x option could be added to the command in order to process the images by batch of x (where x is an integer).
"},{"location":"getting-started/docker/installation/basic/#containers-status","title":"Containers status","text":"At this point of the installation, here are the containers that should be up and running.
DockerPodman docker container list --all --filter 'name=ovos'\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n219eb6254d32 smartgic/ovos-listener-dinkum:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_listener\n31f5d5e7a1ec smartgic/ovos-audio:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_audio\n05e94905b867 smartgic/ovos-core:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_core\nd256c2e7b6f3 smartgic/ovos-phal:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_phal\na4db13a597a4 smartgic/ovos-phal-admin:alpha \"/bin/bash /usr/loca\u2026\" 25 hours ago Up 8 hours ovos_phal_admin\nd157740c9965 smartgic/ovos-messagebus:alpha \"/bin/bash -c ovos-m\u2026\" 25 hours ago Up 8 hours (healthy) ovos_messagebus\n6e3536dcfae5 smartgic/ovos-cli:alpha \"sleep infinity\" 25 hours ago Up 8 hours ovos_cli\npodman container list --all --filter 'name=ovos'\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n219eb6254d32 smartgic/ovos-listener-dinkum:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_listener\n31f5d5e7a1ec smartgic/ovos-audio:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_audio\n05e94905b867 smartgic/ovos-core:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_core\nd256c2e7b6f3 smartgic/ovos-phal:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_phal\na4db13a597a4 smartgic/ovos-phal-admin:alpha \"/bin/bash /usr/loca\u2026\" 25 hours ago Up 8 hours ovos_phal_admin\nd157740c9965 smartgic/ovos-messagebus:alpha \"/bin/bash -c ovos-m\u2026\" 25 hours ago Up 8 hours (healthy) ovos_messagebus\n6e3536dcfae5 smartgic/ovos-cli:alpha \"sleep infinity\" 25 hours ago Up 8 hours ovos_cli\n~/ovos/config/mycroft.conf configuration file is mounted into each containers as a read-only volume.
First I configure then I deploy
Before deploying the services and volumes, it is recommended to set the OVOS's configuration to make sure the services initial start has the correct settings such as the lang for example.
"},{"location":"getting-started/docker/installation/configuration/#initial-configuration","title":"Initial configuration","text":"This configuration is very basic, it instructs the Open Voice OS instance to run in English as main language.
~/ovos/config/mycroft.conf{\n \"play_wav_cmdline\": \"aplay %1\",\n \"lang\": \"en-us\",\n \"listener\": {\n \"VAD\": {\n \"module\": \"ovos-vad-plugin-silero\"\n }\n }\n}\nBy default, the Open Voice OS services will write their logs into a file under ~/.local directory, these files are not rotated or compressed which could lead to a disk space issue.
The solution is to add these lines into the ~/ovos/config/mycroft.conf file (create the file if it does not exist), this will tell the services to redirect their logs to the container stdout.
~/ovos/config/mycroft.conf{\n \"logs\": {\n \"path\": \"stdout\"\n },\n \"play_wav_cmdline\": \"aplay %1\",\n \"lang\": \"en-us\",\n \"listener\": {\n \"VAD\": {\n \"module\": \"ovos-vad-plugin-silero\"\n }\n }\n}\nServices already deployed
If the services have been already deployed and the ~/ovos/config/mycroft.conf has changed, then you will have to restart the containers impacted by the change(s).
"},{"location":"getting-started/docker/installation/configuration/#custom-asoundrc-for-alsa","title":"Custom .asoundrc for ALSA","text":"Sometime a custom .asoundrc file migth be required, a common example is when a voice HAT (Hardware Attached on Top) such as Google AIY Voice Hat is connected to a Raspberry Pi, a custom .asoundrc might be required to make it works with ALSA.
In order to pass this custom .asoundrc file to the containers, the file must be created within the ~/ovos/config/ directory and named asoundrc (with no .).
Only for the containers using sound
The custom .asoundrc file will be passed only to the containers who leverage the audio stack; ovos_listener, ovos_phal, ovos_audio, ovos_core.
~/ovos/config/asoundrc# Configuration for Google AIY Voice Hat V1\noptions snd_rpi_googlemihat_soundcard index=0\n\npcm.softvol {\n type softvol\n slave.pcm dmix\n control {\n name Master\n card 0\n }\n}\n\npcm.micboost {\n type route\n slave.pcm dsnoop\n ttable {\n 0.0 30.0\n 1.1 30.0\n }\n}\n\npcm.!default {\n type asym\n playback.pcm \"plug:softvol\"\n capture.pcm \"plug:micboost\"\n}\n\nctl.!default {\n type hw\n card 0\n}\nServices already deployed
If the services have been already deployed and the ~/ovos/config/asoundrc has changed, then you will have to restart the containers impacted by the change(s).
"},{"location":"getting-started/docker/installation/gui/","title":"GUI","text":""},{"location":"getting-started/docker/installation/gui/#install-the-open-voice-os-gui","title":"Install the Open Voice OS GUI","text":"For Linux eyes only
The GUI is currently available only on Linux operating system, not on Mac OS or Windows.
The Open Voice OS GUI supports two types of system execution:
Using X or Wayland display servers Using EGLFS which doesn't require any display server which is perfect for headless installation When using EGLFS, the DISPLAY variable from the .env composition environment file must be removed or commented as if present the X or Wayland display servers will be tried first and result in an ovos_gui container in error.
Hardware accelerated on Raspberry Pi 4 and 5
Raspberry Pi 4 and 5 will leverage the GPU hardware acceleration which will provide a smoother experience.
If not running on a Raspberry Pi 4 or 5 then the CPU might be used to render the GUI which will result in a high CPU consumption and a poor user exprience.
"},{"location":"getting-started/docker/installation/gui/#configuration","title":"Configuration","text":"The ovos-gui-messagebus component must be configured in order to receive the QML files from the skill containers. Because of these file transfers, the ovos-message-bus component must be configured to allow bigger payload.
~/ovos/config/mycroft.conf{\n \"logs\": {\n \"path\": \"stdout\"\n },\n \"play_wav_cmdline\": \"aplay %1\",\n \"lang\": \"en-us\",\n \"listener\": {\n \"VAD\": {\n \"module\": \"ovos-vad-plugin-silero\"\n }\n },\n \"gui\": {\n \"extension\": \"ovos-gui-plugin-shell-companion\",\n \"gui_file_host_path\": \"/home/ovos/.cache/gui_files\"\n },\n \"websocket\": {\n \"max_msg_size\": 100\n }\n}\nTip
You can skip this section if your are using EGLFS and go to GUI services deployment.
In order to allow only the ovos_gui container to access to the X or Wayland display server, you will have to allow the container (based on its hostname) to connect to the display session.
export DISPLAY=\":0\"\nxhost +local:ovos_gui\nThis command is not permanent, when your operating system will reboot you will have to run the command again. To make it permanent systemd should be leveraged as a user service.
Raspberry PiLinux mkdir -p ~/.config/systemd/user\nmkdir -p ~/.config/systemd/user\nCreate the xhost.service unit file into the ~/.config/systemd/user directory.
~/.config/systemd/user/xhost.service[Unit]\nDescription=Allow ovos_gui container to use X from user session\n\n[Service]\nType=oneshot\nEnvironment=\"DISPLAY=:0\"\nExecStart=/usr/bin/xhost +local:ovos_gui\nExecStop=/usr/bin/xhost -local:ovos_gui\nRemainAfterExit=yes\nRestart=on-failure\nRestartSec=5s\n\n[Install]\nWantedBy=default.target\nEnable and start the new xhost.service systemd service.
Raspberry PiLinux systemctl --user enable xhost.service\nsystemctl --user start xhost.service\nsystemctl --user enable xhost.service\nsystemctl --user start xhost.service\nThe xhost command is part of the x11-xserver-utils package on Debian based distributions such as Raspberry Pi OS.
"},{"location":"getting-started/docker/installation/gui/#gui-services-deployment","title":"GUI services deployment","text":"Podman users
If you are running Podman instead of Docker, replace docker compose with podman-compose.
Raspberry PiLinux docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml --file docker-compose.gui.yml --file docker-compose.raspberrypi.gui.yml up --detach\ndocker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml --file docker-compose.gui.yml up --detach\nBefore going further, please make sure to refer to this section as the following commands could defer depending your setup.
"},{"location":"getting-started/docker/installation/requirements/#get-the-ovos-docker-sources","title":"Get the ovos-docker sources","text":"The ~/hivemind directory is only required if you plan to use HiveMind.
All git clone https://github.com/OpenVoiceOS/ovos-docker.git ~/ovos-docker\nmkdir -p ~/ovos/{config/phal,share,tmp} ~/hivemind/{config/phal,share}\nchown ${USER}:${USER} -R ~/ovos ~/hivemind\ncd ~/ovos-docker/compose\nBecause some containers require /run/user/1000 to be mounted, systemd should be instructed to log the user during the boot process and make /run/user/1000 directory available before the containers start.
Raspberry PiLinux sudo loginctl enable-linger $USER\nsudo loginctl enable-linger $USER\n.env file is a strong requirement
Please make sure to read and understand this section as if you don't then the deployment migth fail.
The composer requires an environment file in order to deploy the services and volumes with the correct settings for your setup.
alpha version by default
As mentioned in this section, the current default VERSION (tag) is alpha.
The example files start with a . (dot) which means they are hidden, use the ls -a command to list all the files included the hidden ones.
Below is an example of .env for Linux (not Raspberry Pi), please read this section for more details about what these variables do.
.envDISPLAY=:0\nHIVEMIND_CONFIG_FOLDER=~/hivemind/config\nHIVEMIND_CONFIG_PHAL_FOLDER=~/hivemind/config/phal\nHIVEMIND_SHARE_FOLDER=~/hivemind/share\nHIVEMIND_USER=hivemind\nINPUT_GID=102\nOVOS_CONFIG_FOLDER=~/ovos/config\nOVOS_CONFIG_PHAL_FOLDER=~/ovos/config/phal\nOVOS_SHARE_FOLDER=~/ovos/share\nOVOS_USER=ovos\nPULL_POLICY=always\nTMP_FOLDER=~/ovos/tmp\nTZ=America/Montreal\nVERSION=alpha\nVIDEO_GID=44\nXDG_RUNTIME_DIR=/run/user/1000\ncp .env-raspberrypi .env\ncp .env.example .env\ncp .env.example .env\ncp .env.example .env\nExamples are provided, please make sure to select the right one and to set the proper values.
"},{"location":"getting-started/docker/installation/requirements/#i2c-and-spi-on-raspberry-pi","title":"I2C and SPI on Raspberry Pi","text":"The Raspberry Pi board supports I2C, I2S and SPI buses. These three buses must be enabled in order to allow the containers below to start:
ovos_coreovos_phalovos_phal_admin Follow the steps below to enable I2C, I2S and SPI.
Raspberry Pi echo \"dtparam=i2c_arm=on\" | sudo tee -a /boot/config.txt\necho \"dtparam=i2s=on\" | sudo tee -a /boot/config.txt\necho \"dtparam=spi=on\" | sudo tee -a /boot/config.txt\necho \"i2c-dev\" | sudo tee /etc/modules-load.d/i2c.conf\nsudo reboot\nTwo different methods are supported by ovos-docker to install Open Voice OS's skills, each of them having pros and cons .
Slow hardware
When running Open Voice OS on slow hardware such as Raspberry Pi 3B+, it is recommended to install skills using the \"As part of ovos_core container\" method in order to reduce the memory consumption.
"},{"location":"getting-started/docker/installation/skills/#as-part-of-ovos_core-container","title":"As part of ovos_core container","text":"The first method is to use a skills.list file within the ~/ovos/config/ directory, this file acts as a Python requirements.txt file.
When ovos_core container starts, it will look for a skills.list file and install the skills defined in there.
Skill requirements
The skill has to be compatible with the pip install method which requires a setup.py file.
skills.listovos-skill-stop # Latest skill version on PyPi\novos-skill-volume==0.0.1 # Specific skill version on PyPi\ngit+https://github.com/OpenVoiceOS/skill-ovos-wikipedia.git@fix/whatever # Specific skill's branch on GitHub\nIf the ovos_core container is wiped for any reasons (like an update), the skill(s) will be automatically reprovisioned.
Not only for skills
skills.list file could be used as well to install extra Python librairies, e.g., SoCo, RPi.GPIO. Just make sure to avoid empty lines.
The main advantage of this method is the simplicity but the downside will be more Python dependencies (libraries) within the ovos_core container, potential conflicts across them, a lack of isolation and a slower start of the container.
"},{"location":"getting-started/docker/installation/skills/#as-standalone-container-recommended","title":"As standalone container (recommended)","text":"The second method is to leverage the ovos-workshop component by running a skill as standalone, it means the skill will not be part of ovos_core container but it will be running inside its own container.
The main advantage is that each skill is isolated which provide more flexibility about Python dependencies (libraries), packages. It is easier to update and more secure but the downside will be that more system resources will be consumed and a container image has to be built for each skill.
Podman users
If you are running Podman instead of Docker, replace docker compose with podman-compose.
Raspberry PiLinuxMac OSWindows WSL2 docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml up --detach\ndocker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml up --detach\ndocker compose --project-name ovos --file docker-compose.macos.yml --file docker-compose.skills.yml --env-file .env up --detach\ndocker compose --project-name ovos --file docker-compose.windows.yml --file docker-compose.skills.yml up --detach\nDepending your Internet speed, your Wi-Fi or Ethernet connection speed and your hardware (I/O), the whole process could take several minutes.
Hardware Time Raspberry Pi 3B+ with USB drive ~12 minutes Raspberry Pi 4B with USB drive ~48 seconds MacBook Air i7 Early 2015 with SSD ~50 seconds AMD Ryzen 7 5800 with NVMe drive ~15 seconds Resources overhead
To reduce the potential ressources overhead due to the image downloads and extractions, the --parallel x option could be added to the command in order to process the images by batch of x (where x is an integer).
If the ovos_core container is restarted or even deleted, the skill containers will automatically register again to it.
"},{"location":"getting-started/docker/installation/skills/#containers-status","title":"Containers status","text":"At this point of the installation, here are the containers that should be up and running.
DockerPodman docker container list --all --filter 'name=ovos'\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n1446b87d7a32 smartgic/ovos-skill-volume:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_volume\n7ad46a871661 smartgic/ovos-skill-wikipedia:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_wikipedia\nb43b8cf31a43 smartgic/ovos-skill-fallback-unknown:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_fallback_unknown\nf27d3fceecec smartgic/ovos-skill-alerts:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_alerts\n30b70c9e72ef smartgic/ovos-skill-hello-world:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_hello_world\nf42175c6d7b8 smartgic/ovos-skill-weather:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_weather\n0ae42a59fb0b smartgic/ovos-skill-stop:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_stop\n5760fb22deb9 smartgic/ovos-skill-date-time:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_date_time\n73f4d4b0a091 smartgic/ovos-skill-personal:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_personal\n219eb6254d32 smartgic/ovos-listener-dinkum:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_listener\n31f5d5e7a1ec smartgic/ovos-audio:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_audio\n05e94905b867 smartgic/ovos-core:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_core\nd256c2e7b6f3 smartgic/ovos-phal:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_phal\na4db13a597a4 smartgic/ovos-phal-admin:alpha \"/bin/bash /usr/loca\u2026\" 25 hours ago Up 8 hours ovos_phal_admin\nd157740c9965 smartgic/ovos-messagebus:alpha \"/bin/bash -c ovos-m\u2026\" 25 hours ago Up 8 hours (healthy) ovos_messagebus\n6e3536dcfae5 smartgic/ovos-cli:alpha \"sleep infinity\" 25 hours ago Up 8 hours ovos_cli\npodman container list --all --filter 'name=ovos'\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n1446b87d7a32 smartgic/ovos-skill-volume:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_volume\n7ad46a871661 smartgic/ovos-skill-wikipedia:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_wikipedia\nb43b8cf31a43 smartgic/ovos-skill-fallback-unknown:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_fallback_unknown\nf27d3fceecec smartgic/ovos-skill-alerts:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_alerts\n30b70c9e72ef smartgic/ovos-skill-hello-world:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_hello_world\nf42175c6d7b8 smartgic/ovos-skill-weather:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_weather\n0ae42a59fb0b smartgic/ovos-skill-stop:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_stop\n5760fb22deb9 smartgic/ovos-skill-date-time:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_date_time\n73f4d4b0a091 smartgic/ovos-skill-personal:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_personal\n219eb6254d32 smartgic/ovos-listener-dinkum:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_listener\n31f5d5e7a1ec smartgic/ovos-audio:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_audio\n05e94905b867 smartgic/ovos-core:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_core\nd256c2e7b6f3 smartgic/ovos-phal:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_phal\na4db13a597a4 smartgic/ovos-phal-admin:alpha \"/bin/bash /usr/loca\u2026\" 25 hours ago Up 8 hours ovos_phal_admin\nd157740c9965 smartgic/ovos-messagebus:alpha \"/bin/bash -c ovos-m\u2026\" 25 hours ago Up 8 hours (healthy) ovos_messagebus\n6e3536dcfae5 smartgic/ovos-cli:alpha \"sleep infinity\" 25 hours ago Up 8 hours ovos_cli\nA microhpone plugin allows you to use a specific sound protocol in order to get voice samples from your microphone. Depending the operating system you are running on, you will have to choose the correct plugin.
Note
The microhpone plugins are handled by the ovos_listener container.
The ovos_listener container comes with few pre-installed microphone plugins such as:
ovos-microphone-plugin-alsa is using pyalsaaudio Python library (default)ovos-microphone-plugin-sounddevice is using sounddevice Python library If the existing microphone plugins are not enough then you can install yours by following the same principle as for the STT plugins by adding a listener.list file within the ~/ovos/config/ directory, this file acts as a Python requirements.txt file.
Plugins requirements
These plugins have to be compatible with the pip install method which requires a setup.py file.
When the ovos_listener container starts, it will look for this file and install the plugins defined in there.
~/ovos/config/listener.listovos-microphone-plugin-pyaudio==0.2.0a1 # Specific plugin version on PyPi\novos-microphone-plugin-arecord # Latest plugin version on PyPi\ngit+https://github.com/OpenVoiceOS/ovos-microphone-plugin-socket.git@fix/whatever # Specific branch of a plugin on GitHub\nThe ovos_listener container must be restarted if a change occurs in the listener.list file.
DockerPodman docker restart ovos_listener\npodman restart ovos_listener\nHere are the two main plugins to use per platform.
Plugin Platforms ovos-microphone-plugin-alsa ovos-microphone-plugin-sounddevice Choose the correct plugin
If a wrong plugin is used, the listener will not be able to hear you which means that you will not be able to interact with your Open Voice OS instance.
"},{"location":"getting-started/docker/plugins/phal/","title":"PHAL","text":""},{"location":"getting-started/docker/plugins/phal/#phal-plugins","title":"PHAL plugins","text":"The Plugin based Hardware Abstraction Layer plugins allow you to interact with system components such as Wi-Fi, GPIO, NetworkManager, etc... but not only.
Note
The PHAL plugins are handled by the ovos_phal and ovos_phal_admin containers.
ovos_phal_admin is a privileged container
The ovos_phal_admin purpose is to run plugins that require accesses to some devices, files or services.
Plugins installed in this container have to be enabled into ~/ovos/config/mycroft.conf in order to get loaded, this acts as an extra layer of security.
The ovos_phal container comes with few pre-installed PHAL plugins such as:
ovos-PHAL-plugin-alsa controls system volume with ALSAovos-PHAL-plugin-system handles bus events to interact with the operating system If the existing PHAL plugins are not enough then you can install yours by following the same principle as for the STT plugins by adding a phal.list or phal_admin.list files within the ~/ovos/config/ directory, this file acts as a Python requirements.txt file.
Plugins requirements
These plugins have to be compatible with the pip install method which requires a setup.py file.
When the ovos_phal or ovos_phal_admin containers start, they will look for these files and install the skpluginsills defined in there.
~/ovos/config/phal.list or ~/ovos/config/phal_admin.listovos-phal-plugin-ipgeo==0.0.1 # Specific plugin version on PyPi\novos-PHAL-plugin-pulse # Latest plugin version on PyPi\ngit+https://github.com/OpenVoiceOS/ovos-PHAL-plugin-homeassistant.git@fix/whatever # Specific branch of a plugin on GitHub\nThe ovos_phal or ovos_phal_admin containers must be restarted if a change occurs in the phal.list or phal_admin.lis files.
DockerPodman docker restart ovos_phal ovos_phal_admin\npodman restart ovos_phal ovos_phal_admin\nThe Speech-To-Text plugins allow you to connect Open Voice OS with different STT servers, it could be FasterWhisper, VOSK, Google Translate, Deepgram, etc... Each of these STT providers will have different languages support, precision and performances.
Note
The Speech-To-Text plugins are handled by the ovos_listener container.
The ovos_listener container comes with few pre-installed STT plugins such as:
ovos-stt-plugin-server allows you to reach an external STT serviceovos-stt-plugin-vosk is an offline STT service If the existing STT plugins are not enough then you can install yours by following the same principle as for the microphone plugins by adding a listener.list file within the ~/ovos/config/ directory, this file acts as a Python requirements.txt file.
Plugins requirements
These plugins have to be compatible with the pip install method which requires a setup.py file.
When the ovos_listener container starts, it will look for this file and install the plugins defined in there.
~/ovos/config/listener.listovos-stt-plugin-vosk==0.2.0a1 # Specific plugin version on PyPi\novos-stt-plugin-server # Latest plugin version on PyPi\ngit+https://github.com/OpenVoiceOS/ovos-stt-plugin-chromium.git@fix/whatever # Specific branch of a plugin on GitHub\nThe ovos_listener container must be restarted if a change occurs in the listener.list file.
DockerPodman docker restart ovos_listener\npodman restart ovos_listener\nThe Text-To-Speech plugins allow you to connect Open Voice OS with different TTS servers, it could be Piper, Coqui, Amazon Polly, Mimic, etc... Each of these TTS providers will have different voices and languages.
Note
The Text-To-Speech plugins are handled by the ovos_audio container.
The ovos_audio container comes with few pre-installed TTS plugins such as:
ovos-tts-plugin-mimic is the original Mycroft AI TTS with the iconic Alan Pope's voiceovos-tts-plugin-mimic2 is the cloud based version hosted on Mycroft AI infrastructureovos-tts-plugin-mimic3-server is the latest Mycroft AI TTS engineovos-tts-plugin-server allows you to reach an external TTS service If the existing TTS plugins are not enough then you can install yours by following the same principle as for the skills by adding an audio.list file within the ~/ovos/config/ directory, this file acts as a Python requirements.txt file.
Plugins requirements
These plugins have to be compatible with the pip install method which requires a setup.py file.
When the ovos_audio container starts, it will look for this file and install the plugins defined in there.
~/ovos/config/audio.listovos-tts-plugin-marytts==0.0.1a1 # Specific plugin version on PyPi\nneon-tts-plugin-mozilla-remote # Latest plugin version on PyPi\ngit+https://github.com/NeonGeckoCom/neon-tts-plugin-polly.git@fix/whatever # Specific branch of a plugin on GitHub\nThe ovos_audio container must be restarted if a change occurs in the audio.list file.
DockerPodman docker restart ovos_audio\npodman restart ovos_audio\nIn order to run TensorFlow used by few Open Voice OS components, the CPU must support AVX (Advanced Vector Extensions) instruction set for x86 processors or SIMD (Single Instruction, Multiple Data) instruction set for ARM processors.
LinuxMac OS grep -E -i --color \"avx|simd\" /proc/cpuinfo\nsysctl -a | grep -E -i --color \"avx|simd\"\nIf the command does not return an output then your CPU doesn't meet the requirements for TensorFlow.
AVX or SIMD instruction set missing
Because the instruction set is missing does not mean that Open Voice OS can't run on your hardware, it simply means that Precise wake word engine or anything else using TensorFlow will not run on it.
"},{"location":"getting-started/docker/prerequisites/engine/","title":"Container engine","text":""},{"location":"getting-started/docker/prerequisites/engine/#container-engine","title":"Container engine","text":""},{"location":"getting-started/docker/prerequisites/engine/#installation","title":"Installation","text":"As we are leveraging containers, a container engine such as Docker or Podman is required (only one of them should be installed), as well as their composer.
If you are not familiar with what a container engine or a composer are then please refer to this section first as these fundamentals must be understood.
"},{"location":"getting-started/docker/prerequisites/engine/#versions","title":"Versions","text":"When running on Linux, please make sure to not use Docker Desktop but prefer Docker Engine as it is a better choice in our case. Docker Desktop runs a virtual machine which doesn't have access to the same devices as the host has, due to this limitation the /dev/snd device will not be usable and this will prevent the usage of speakers and microphone.
docker-compose versus docker compose
As mentioned by Docker, from July 2023 Compose V1 (docker-compose) will not received updates anymore which makes it deprecated and replaced by Compose V2 (docker compose) directly embedded into the docker command line.
Either you choose to install Docker or Podman and their composer on Linux, Mac OS or Windows, please refer to the official documentation1 .
Minimum required versions
In order to get the latest features supported by ovos-docker, please make sure to install a recent version of Docker (>= 24.x.x) or Podman (>= 4.3.x) for your operating system.
"},{"location":"getting-started/docker/prerequisites/engine/#dont-be-root-be-a-user","title":"Don't be root, be a user","text":"You should not run docker command as root user or using the sudo command, if so then you will get some error messages such as Permission denied and some containers could restart in a loop.
To allow a simple user to execute the docker command, make sure to add the user to the docker group.
Linux sudo usermod -a -G docker $USER\nOnce added to the docker group you will have to logout from the current session (graphical or SSH) in order to get the group added to your user once you reconnect.
Once reconnected, run the following command to ensure the docker has been appened to your $USER.
Linux id\nuid=1000(foobar) gid=1000(foobar) groups=1000(foobar),973(docker)\nThe GID could differ compare to your setup.
"},{"location":"getting-started/docker/prerequisites/engine/#validation","title":"Validation","text":"DockerPodman docker system info\ndocker container list\npodman system info\npodman container list\n Docker official documentation or Podman official documentation.\u00a0\u21a9
"},{"location":"getting-started/docker/prerequisites/sound/","title":"Sound system","text":""},{"location":"getting-started/docker/prerequisites/sound/#sound-system","title":"Sound system","text":"PulseAudio is a requirement and has to be up and running on the host (not inside the containers) to expose a socket (for communication) and a cookie (for authentication) to allow the containers to have access to the microphone (input device) and speakers (output device).
On modern Linux distribution, PipeWire now handles the sound stack on the system.
Sound server auto-detection
ovos-docker supports both native PulseAudio and PipeWire, the containers will automatically detect which sound server is running on the operating system.
"},{"location":"getting-started/docker/prerequisites/sound/#mac-os-and-windows","title":"Mac OS and Windows","text":"If you are running an operating system other Linux such as Mac OS or Windows, then PulseAudio will have to be installed to act as a gateway between the containers and the OS.
Mac OSWindows WSL2 brew install pulseaudio\nbrew services stop pulseaudio\nsed -i \"\" \"s/#load-module module-native-protocol-tcp/load-module module-native-protocol-tcp/g\" $(brew ls pulseaudio | grep default.pa$)\nbrew services start pulseaudio\nsudo apt install pulseaudio\nThe user running the containers must be part of the audio system group (depending the Linux distribution).
PulseAudio files permissions
Check the permissions for ~/.config/pulse/ and /run/user/1000/pulse directories, they should belong to the user running the stack (where 1000 is your user ID), not to root user.
If you are running on Mac OS, there is no /run/user/1000/ directory.
"},{"location":"getting-started/docker/prerequisites/sound/#validation","title":"Validation","text":"pactl is a PulseAudio command shipped with the pulseaudio-utils package and pw-cli is a PipeWire command shipped with pipewire-utils or pipewire-bin depending your distribution.
These commands provide information about the status of PulseAudio or PipeWire.
PulseAudioPipeWire pactl info\npw-cli info\nAt least one of the sources (microphones/audio input) returned, should match the Default Source line from the pactl info command or the Audio/Source line from the wpctl status command.
PulseAudioPipeWire pactl list sources short\nwpctl status | grep Audio/Source\nAt least one of the sinks (speakers/audio output) returned, should match the Default Sink line from the pactl info command or the Audio/Sink line from the wpctl status command.
PulseAudioPipeWire pactl list sinks short\nwpctl status | grep Audio/Sink\nIn order to secure your Open Voice OS instance, few more steps are required and few concepts must be understood.
"},{"location":"getting-started/docker/security/hardening/#apparmor","title":"AppArmor","text":"AppArmor and SELinux are examples of Mandatory Access Control (MAC) systems. These systems differ from other security controls which are generally called Discretionary Access Control (DAC) systems in that, generally, the user can't change their operation.
AppArmor packages
AppArmor must be installed on your system before going further. Please refer to your Linux distribution documentation to install it.
"},{"location":"getting-started/docker/security/hardening/#enable-apparmor","title":"Enable AppArmor","text":"Raspberry Pi OSDebian & Ubuntu /boot/cmdline.txtapparmor=1 security=apparmor\napparmor=1 security=apparmor\nSystem must be rebooted to instruct the kernel to load AppArmor during the boot sequence. Once rebooted, check the AppArmor status using the aa-status command.
Raspberry Pi OSDebian & Ubuntu sudo aa-status\nsudo aa-status\nAppArmor and Podman support1
AppArmor support for Podman is not yet fully functional.
Docker applies the docker-default AppArmor profile to new containers. In Docker 1.13 and later this profile is created in tmpfs and then loaded into the kernel.
The container engine should now be aware of apparmor as an available security option.
docker system info | grep -i apparmor\nAll the containers except ovos_phal_admin should now be confined with the docker-default AppArmor profile.
docker container list --quiet --all --filter \"name=ovos\" | xargs docker inspect --format \"{{ .Name }}: AppArmorProfile={{ .AppArmorProfile }}\"\n/ovos_skill_volume: AppArmorProfile=docker-default\n/ovos_skill_wikipedia: AppArmorProfile=docker-default\n/ovos_skill_fallback_unknown: AppArmorProfile=docker-default\n/ovos_skill_alerts: AppArmorProfile=docker-default\n/ovos_skill_hello_world: AppArmorProfile=docker-default\n/ovos_skill_weather: AppArmorProfile=docker-default\n/ovos_skill_stop: AppArmorProfile=docker-default\n/ovos_skill_date_time: AppArmorProfile=docker-default\n/ovos_skill_personal: AppArmorProfile=docker-default\n/ovos_listener: AppArmorProfile=docker-default\n/ovos_audio: AppArmorProfile=docker-default\n/ovos_core: AppArmorProfile=docker-default\n/ovos_phal: AppArmorProfile=docker-default\n/ovos_phal_admin: AppArmorProfile=unconfined\n/ovos_messagebus: AppArmorProfile=docker-default\n/ovos_cli: AppArmorProfile=docker-default\novos_phal_admin container is not confined
The ovos_phal_admin container is not confined as it runs as a privileged container.
"},{"location":"getting-started/docker/security/hardening/#message-bus","title":"Message bus","text":"By default, the message bus is listening on address 0.0.0.0 and port 8181 because the ovos_messagebus is created using the --network host option. This could be a security issue as an external device could connect to the message bus and send and/or read messages.
Why using --network host?
Some Open Voice OS skills such as Home Assistant or Sonos require access to your private network in order to communicate with your IoT devices.
To prevent potential security issues, it is recommended to use a firewall the port 8181.
iptables will be demonstrated as an example but if firewalld or ufw services are used, then make sure to be compliant with your distribution.
Linux sudo iptables -A INPUT -p tcp -s localhost --dport 8181 -j ACCEPT\nsudo iptables iptables -A INPUT -p tcp --dport 8181 -j DROP\nThis will allow connections to port 8181 only from localhost (internal).
Keep your ports closed
Keep in mind to firewall any other ports which should not be exposed outside of the host by using the same IPTables method.
If you really need to connect an external application to the message bus, we recommend to use HiveMind to ensure a proper security exposure.
Enable rootless AppArmor for Podman \u21a9
"},{"location":"getting-started/docker/security/hivemind/","title":"HiveMind","text":""},{"location":"getting-started/docker/security/hivemind/#hivemind-to-the-rescue","title":"HiveMind to the rescue","text":""},{"location":"getting-started/docker/security/hivemind/#what-is-hivemind","title":"What is HiveMind?","text":"HiveMind is a community-developed superset or extension of Open Voice OS, the open-source voice operating system.
With HiveMind, you can extend one (or more, but usually just one!) instance of Open Voice OS to as many devices as you want, including devices that can't ordinarily run Open Voice OS!
Official documentation
What it means, is that HiveMind allows external connections to the message bus by using a secured protocol.
Fulfill the requirements first
Before going further, please make sure that all the requirements are fulfilled.
A composition file is available in order to deploy hivemind_listener and hivemind_cli services.
Podman users
If you are running Podman instead of Docker, replace docker compose with podman-compose.
Raspberry PiLinuxMac OSWindows WSL2 docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml up --detach\ndocker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml up --detach\ndocker compose --project-name ovos --file docker-compose.macos.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml --env-file .env up --detach\ndocker compose --project-name ovos --file docker-compose.windows.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml up --detach\nFor more information about how to authenticate with the HiveMind listener, please read the HiveMind-core repository documentation.
Once the HiveMind containers are up and running, the HiveMind command line allows you to add client, to list them, to delete them, etc...
DockerPodman docker exec --interactive --tty hivemind_cli hivemind-core --help\npodman exec --interactive --tty hivemind_cli hivemind-core --help\nPort 5678 must be open
In order to to reach the HiveMind listener, the port 5678 has to be open on the host. Please make sure your firewall allows the connection to this port or the clients will not be able to connect to it.
"},{"location":"getting-started/docker/security/hivemind/#containers-status","title":"Containers status","text":"At this point of the installation, here are the containers that should be up and running.
DockerPodman docker container list --all --filter 'name=ovos' --filter 'name=hivemind'\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n4e2d45799de8 smartgic/hivemind-cli:alpha \"sleep infinity\" 16 minutes ago Up 16 minutes hivemind_cli\n612a9ea32405 smartgic/hivemind-listener:alpha \"hivemind-core listen\" 16 minutes ago Up 16 minutes hivemind_listener\n1446b87d7a32 smartgic/ovos-skill-volume:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_volume\n7ad46a871661 smartgic/ovos-skill-wikipedia:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_wikipedia\nb43b8cf31a43 smartgic/ovos-skill-fallback-unknown:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_fallback_unknown\nf27d3fceecec smartgic/ovos-skill-alerts:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_alerts\n30b70c9e72ef smartgic/ovos-skill-hello-world:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_hello_world\nf42175c6d7b8 smartgic/ovos-skill-weather:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_weather\n0ae42a59fb0b smartgic/ovos-skill-stop:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_stop\n5760fb22deb9 smartgic/ovos-skill-date-time:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_date_time\n73f4d4b0a091 smartgic/ovos-skill-personal:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_personal\n219eb6254d32 smartgic/ovos-listener-dinkum:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_listener\n31f5d5e7a1ec smartgic/ovos-audio:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_audio\n05e94905b867 smartgic/ovos-core:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_core\nd256c2e7b6f3 smartgic/ovos-phal:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_phal\na4db13a597a4 smartgic/ovos-phal-admin:alpha \"/bin/bash /usr/loca\u2026\" 25 hours ago Up 8 hours ovos_phal_admin\nd157740c9965 smartgic/ovos-messagebus:alpha \"/bin/bash -c ovos-m\u2026\" 25 hours ago Up 8 hours (healthy) ovos_messagebus\n6e3536dcfae5 smartgic/ovos-cli:alpha \"sleep infinity\" 25 hours ago Up 8 hours ovos_cli\npodman container list --all --filter 'name=ovos'\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n4e2d45799de8 smartgic/hivemind-cli:alpha \"sleep infinity\" 16 minutes ago Up 16 minutes hivemind_cli\n612a9ea32405 smartgic/hivemind-listener:alpha \"hivemind-core listen\" 16 minutes ago Up 16 minutes hivemind_listener\n1446b87d7a32 smartgic/ovos-skill-volume:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_volume\n7ad46a871661 smartgic/ovos-skill-wikipedia:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_wikipedia\nb43b8cf31a43 smartgic/ovos-skill-fallback-unknown:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_fallback_unknown\nf27d3fceecec smartgic/ovos-skill-alerts:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_alerts\n30b70c9e72ef smartgic/ovos-skill-hello-world:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_hello_world\nf42175c6d7b8 smartgic/ovos-skill-weather:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_weather\n0ae42a59fb0b smartgic/ovos-skill-stop:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_stop\n5760fb22deb9 smartgic/ovos-skill-date-time:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_date_time\n73f4d4b0a091 smartgic/ovos-skill-personal:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_personal\n219eb6254d32 smartgic/ovos-listener-dinkum:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_listener\n31f5d5e7a1ec smartgic/ovos-audio:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_audio\n05e94905b867 smartgic/ovos-core:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_core\nd256c2e7b6f3 smartgic/ovos-phal:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_phal\na4db13a597a4 smartgic/ovos-phal-admin:alpha \"/bin/bash /usr/loca\u2026\" 25 hours ago Up 8 hours ovos_phal_admin\nd157740c9965 smartgic/ovos-messagebus:alpha \"/bin/bash -c ovos-m\u2026\" 25 hours ago Up 8 hours (healthy) ovos_messagebus\n6e3536dcfae5 smartgic/ovos-cli:alpha \"sleep infinity\" 25 hours ago Up 8 hours ovos_cli\novos-docker is one of the fastest ways to get started with Open Voice OS.
"},{"location":"#quickstart","title":"Quickstart","text":"A nice, simple and intuitive way to install Open Voice OS and/or HiveMind using Bash, Whiptail (Newt) and Ansible.
curl, git and sudo packages must be installed before running the installer.
sh -c \"curl -s https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh -o installer.sh && chmod +x installer.sh && sudo ./installer.sh && rm installer.sh\"\nThen follow the instructions displayed on screen then you will be all set !
"},{"location":"#getting-started","title":"Getting started","text":"Want to give Open Voice OS a try? Open Voice OS is an open source software that runs where you want it to, whether it\u2019s on your own hardware or one of the dedicated Mark 1 or Mark II.
Docker
arm64 x86_64
Use container engine such as Docker or Podman and their composer to run a complete, secure, isolated and \"easy to update\" instance of Open Voice OS!
Getting started with Docker
"},{"location":"quickstart/","title":"Quickstart","text":""},{"location":"quickstart/#quickstart","title":"Quickstart","text":"A nice, simple and intuitive way to install Open Voice OS and/or HiveMind using Bash, Whiptail (Newt) and Ansible.
curl, git and sudo packages must be installed before running the installer.
sh -c \"curl -s https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh -o installer.sh && chmod +x installer.sh && sudo ./installer.sh && rm installer.sh\"\nThen follow the instructions displayed on screen then you will be all set !
"},{"location":"about/what-is-it/","title":"What is it?","text":""},{"location":"about/what-is-it/#what-is-open-voice-os","title":"What is Open Voice OS?","text":"Open Voice OS is a free and open source personal assistant and smart speaker that offers a powerful and flexible alternative to proprietary solutions like Amazon\u2122 Alexa\u2122, Google Assistant\u2122, Microsoft Cortana\u2122 or Apple's Siri\u2122.
At the same time, it is also an open virtual assistant platform that enables developers and organizations to create custom voice-controlled applications. With its cutting-edge technology and user-friendly design, Open Voice OS is revolutionizing the way we interact with technology.
The platform provides a comprehensive suite of features that makes it easy to deploy voice-based applications for a wide range of use cases, including home automation, entertainment, education, and more. With natural language processing, multi-device compatibility, a customizable UI, robust APIs, and a focus on privacy and security, Open Voice OS delivers a highly responsive and accurate experience for users.
Open Voice OS is the perfect choice for anyone who wants a personal assistant and smart speaker that gives them complete control over their data and the ability to customize their experience.
In addition to its voice capabilities, Open Voice OS also features a touch-screen GUI made using QT and the KDE frameworks, providing an intuitive and user-friendly interface. And with its open source nature, anyone with technical skills can contribute to the platform and help shape its future.
"},{"location":"about/why-use-ovos/","title":"Why use OVOS?","text":""},{"location":"about/why-use-ovos/#why-use-ovos","title":"Why use OVOS?","text":"Whether you prefer voice commands or a more traditional touch interface, Open Voice OS has you covered, and the option to run the platform fully offline gives you complete control over your data and ensures that your information is never shared with third parties.
With its powerful and flexible features, Open Voice OS is the ideal choice for anyone who wants a voice-controlled virtual assistant and smart speaker that offers complete control and customization. Whether you\u2019re a software developer, data scientist, or just someone with a passion for technology, be sure to check out Open Voice OS today!
"},{"location":"about/why-use-ovos/#multi-device-compatibility","title":"Multi-device compatibility","text":"Open Voice OS can be integrated with a wide range of devices making it easy for you to access and control your virtual assistant no matter where you are.
Smart speakers Smartphones System on a chip (SoC) Laptops Televisions "},{"location":"about/why-use-ovos/#customizable-ui","title":"Customizable UI","text":"With its easy-to-use GUI interface, Open Voice OS allows developers to create custom interfaces that match their specific brand and style. Whether you\u2019re a business looking to integrate voice control into your product offerings, or a home user who wants a unique interface that matches your personal style, Open Voice OS has you covered.
"},{"location":"about/why-use-ovos/#robust-modular","title":"Robust & Modular","text":"Open Voice OS leverages the power of skills and plugins to create a robust and modular virtual assistant platform, offering unparalleled customization and extension capabilities.
"},{"location":"about/why-use-ovos/#fully-offline","title":"Fully offline","text":"Open Voice OS can run without the use of any online Text-To-Speech (TTS) or Speech-To-Text (STT) services, so you don\u2019t have to rely on anyone keeping their servers up or recording your requests.
"},{"location":"about/why-use-ovos/#privacy-and-security","title":"Privacy and security","text":"Open Voice OS is designed with privacy and security in mind. Whether you\u2019re concerned about the security of your personal information or the privacy of your voice commands, Open Voice OS provides peace of mind.
"},{"location":"about/glossary/components/","title":"Components","text":""},{"location":"about/glossary/components/#components","title":"Components","text":"Open Voice OS is very modular which means instead of a big monolith block of code, multiple projects exist around the OVOS ecosystem with each of them having their own role to play in order to deliver the best and fastest experience.
"},{"location":"about/glossary/components/#ovos-audio","title":"ovos-audio","text":"The audio service is responsible for loading Text-To-Speech and audio plugins.
All audio playback (sounds played on the speakers) is handled by this service by leveraging the sound server/service from the system where its running.
"},{"location":"about/glossary/components/#ovos-common-play","title":"ovos-common-play","text":"OVOS Common Play (OCP) is a full-fledged voice media player packaged as an audio plugin.
OCP handles the whole voice integration and playback functionality, it also integrates with external players via Media Player Remote Interfacing Specification (MPRIS).
"},{"location":"about/glossary/components/#ovos-config","title":"ovos-config","text":"Helper package to interact with OVOS configuration. A small tool is included to quickly show, get or set config values.
"},{"location":"about/glossary/components/#ovos-core","title":"ovos-core","text":"The skills service is responsible for loading skills and intent parsers, all user queries are handled by the skills service.
This is the brains of the device. Without it, you would have some cool software that does not work together. It controls the skills service and directs intents to the right skill.
"},{"location":"about/glossary/components/#ovos-classifiers","title":"ovos-classifiers","text":"Base implementations for Natural language processing (NPL) tasks, from baseline heuristics to classic machine learning models that run everywhere.
"},{"location":"about/glossary/components/#ovos-gui","title":"ovos-gui","text":"OVOS uses the standard Mycroft GUI framework, you can find the official documentation here.
The GUI is an open source visual and display framework running on top of KDE Plasma Technology and built using Kirigami a lightweight user interface framework for convergent applications which are empowered by QT.
Component dependency
This component depends on ovos-gui-messagebus.
"},{"location":"about/glossary/components/#ovos-gui-messagebus","title":"ovos-gui-messagebus","text":"GUI messagebus service, manages GUI state and implements the GUI protocol.
The GUI service provides a websocket for gui clients to connect to, it is responsible for implementing the gui protocol under ovos-core.
GUI clients (the application that actually draws the GUI) connect to this service.
"},{"location":"about/glossary/components/#ovos-listener","title":"ovos-listener","text":"The listener (also known as speech) is responsible for loading STT, VAD and wake word plugins. Speech is transcribed into text (intent) and forwarded to the core service.
The newest listener that OVOS uses is ovos-dinkum-listener. It is a version of the listener from the Mycroft Dinkum software for the Mark 2 modified for use with OVOS.
"},{"location":"about/glossary/components/#ovos-messagebus","title":"ovos-messagebus","text":"The message bus service provides a websocket where all internal events travel, you can think of the bus service as Open Voice OS's nervous system.
Internal usage only
The bus is considered as an internal and private websocket, external clients should not connect directly to it. Please check HiveMind for more information. For more detail please go to the System Hardening section
"},{"location":"about/glossary/components/#ovos-phal","title":"ovos-phal","text":"Plugin based Hardware Abstraction Layer is a wrapper for software system level abstraction, where based on the environment either through known configuration or via fingerprinting, only specific plugins load to interface with the system and specific hardware.
A PHAL plugin can provide anything from hardware integrations (ReSpeaker, Mark1, Mark2, etc...) or system integrations (Network-Manager, OVOS Shell, etc...).
Any number of plugins providing functionality can be loaded and validated at runtime, plugins can be system integrations to handle things like reboot and shutdown, or hardware drivers such as Mycroft Mark2 plugin.
PHAL admin variant
In addition of the initial PHAL service, PHAL admin is running as root or as a priviledged user. This variant allows PHAL admin to perform actions which require more privileges such as reboot for example.
"},{"location":"about/glossary/components/#ovos-plugin-manager","title":"ovos-plugin-manager","text":"OPM is the OVOS Plugin Manager, this base package provides arbitrary plugins to the OVOS ecosystem. OPM plugins import their base classes from OPM making them portable and independent of ovos-core, plugins can be used in a standalone projects.
By using OPM you can ensure a standard interface to plugins and easily make them configurable in your project.
"},{"location":"about/glossary/components/#ovos-shell","title":"ovos-shell","text":"OVOS Shell is the Open Voice OS client implementation of the ovos-gui library, basically it represents the OVOS graphical layer on top of Mycroft GUI.
Component dependency
This component depends on ovos-gui.
"},{"location":"about/glossary/components/#ovos-utils","title":"ovos-utils","text":"Just a collection of simple utilities and functions for use across the components from the OVOS ecosystem.
"},{"location":"about/glossary/components/#ovos-workshop","title":"ovos-workshop","text":"Workshop contains skill base classes and supporting tools to build skills and applications for Open Voice OS systems.
"},{"location":"about/glossary/components/#padacioso","title":"padacioso","text":"A lightweight, dead-simple intent parser which aim to replace the current intent parser; Padatious.
"},{"location":"about/glossary/terms/","title":"Terms","text":""},{"location":"about/glossary/terms/#glossary","title":"Glossary","text":"Use our Glossary to learn more about the specialist terms that we use in natural language processing generally, and more specifically with Open Voice OS software.
"},{"location":"about/glossary/terms/#fallback","title":"Fallback","text":"A skill that is designated to be a 'catch-all' when Open Voice OS cannot interpret the intent from an utterance.
"},{"location":"about/glossary/terms/#hivemind","title":"HiveMind","text":"HiveMind is a community-developed superset or extension of Open Voice OS the open-source voice operating system.
With HiveMind, you can extend an instance of Open Voice OS to as many devices as you want, including devices that can't ordinarily run Open Voice OS!
HiveMind could be considered as an external Open Voice OS component leaving its \"own\" life under its \"own\" lifecycle.
"},{"location":"about/glossary/terms/#hotword","title":"Hotword","text":"See wake word.
"},{"location":"about/glossary/terms/#intent","title":"Intent","text":"When a user speaks an utterance to Open Voice OS, Open Voice OS tries to interpret the intent of the utterance, and match the intent with a skill.
"},{"location":"about/glossary/terms/#playback","title":"Playback","text":"Playback is the audio output going through the speakers, for example when asking What's the temperature?, OVOS will speaks to you using the playback capability.
"},{"location":"about/glossary/terms/#plugin","title":"Plugin","text":"A plugin allows you to install \"small bricks\" of functionnalities using OVOS Plugin Manager in order to make your voice assistant more capable.
Open Voice OS uses many plugins in many different areas:
Wake word plugin VAD plugins Microphone plugins PHAL plugins TTS plugins STT plugins etc... "},{"location":"about/glossary/terms/#skill","title":"Skill","text":"When Open Voice OS hears the wake word, then an utterance, Open Voice OS will try to find a skill that matches the utterance. The skill might fetch some data, or play some audio, or speak, or display some information.
If Open Voice OS can't find a skill that matches the utterance, he will tell you he doesn't understand and fallback (when configured).
"},{"location":"about/glossary/terms/#speech-to-text-stt","title":"Speech-To-Text (STT)","text":"Speech-To-Text is what converts your voice into a text which becomes a commands that OVOS recognizes, then converts to an intent that is used to activate skills.
Several options are available each with different attributes and supported languages. Some can be run on device, others need an internet connection to work.
"},{"location":"about/glossary/terms/#text-to-speech-tts","title":"Text-To-Speech (TTS)","text":"Text-To-Speech is responsible for converting text into audio for playback (verbal response from OVOS).
Several options are available each with different attributes and supported languages. Some can be run on device, others need an internet connection to work.
"},{"location":"about/glossary/terms/#utterance","title":"Utterance","text":"An utterance is how you interact with Open Voice OS. An utterance is a command or question - like What's the weather like in Kansas City? or Tell me about the Pembroke Welsh Corgi.
"},{"location":"about/glossary/terms/#vad","title":"VAD","text":"Voice Activity Detection is used by the listener to determine when a user stopped speaking, this indicates the voice command is ready to be executed.
"},{"location":"about/glossary/terms/#wake-word","title":"Wake Word","text":"The wake word is the phrase or word you use to (wake up) tell Open Voice OS you're about to issue a command.
"},{"location":"getting-started/docker/","title":"Docker or Podman","text":""},{"location":"getting-started/docker/#docker-or-podman","title":"Docker or Podman","text":"Before going further, here are quick and simple definitions of what a container is and what a composer is, these definitions are important and must be well understood before starting.
Two engines, same definition
Both of the definitions described below are valid for either Docker or Podman.
"},{"location":"getting-started/docker/#container-definition","title":"Container definition","text":"A container is a standard unit of software that packages up code and all its dependencies so the application runs quickly and reliably from one computing environment to another. A container image is a lightweight, standalone, executable package of software that includes everything needed to run an application.
Initial source
"},{"location":"getting-started/docker/#composer-definition","title":"Composer definition","text":"A composer is a tool for defining and running multi-container container applications. With Compose, you use a YAML file to configure your application\u2019s services. Then, with a single command, you create and start all the services from your configuration.
Initial source
"},{"location":"getting-started/docker/cli/","title":"OVOS command line","text":""},{"location":"getting-started/docker/cli/#open-voice-os-command-line","title":"Open Voice OS command line","text":"The command line allows you to send a message (but not only) directly to the message bus by using the ovos-cli-client command from the ovo_cli container.
Skill interactions
The command line doesn't support any action related to skills other than :skills as this setup is running inside containers. Please read the skill section to manage skills.
"},{"location":"getting-started/docker/cli/#ovos-cli-client","title":"ovos-cli-client","text":"ovos-cli-client is deprecated
Please read https://github.com/OpenVoiceOS/ovos-cli-client/issues/14 for more information.
Interact directly with the ncurses OVOS client interface.
DockerPodman docker exec --interactive --tty ovos_cli ovos-cli-client\npodman exec --interactive --tty ovos_cli ovos-cli-client\nTo display or manage the current configuration, the ovos-config command could be used.
read-write access to the configuration
The ovos_cli container is the only one having read-write access to the mycroft.conf configuration file.
DockerPodman docker exec --interactive --tty ovos_cli ovos-config show\npodman exec --interactive --tty ovos_cli ovos-config show\nvim as default editor
vim and nano editors are available within the ovos-cli image, vim has been set as default.
"},{"location":"getting-started/docker/cli/#ovos-speak","title":"ovos-speak","text":"An easy way to make Open Voice OS speaks is to run the ovos-speak command.
DockerPodman docker exec --interactive --tty ovos_cli ovos-speak \"hello world\"\npodman exec --interactive --tty ovos_cli ovos-speak \"hello world\"\nNeon Mana (Messagebus Application for Neon AI) provides tools for interacting with the message bus.
DockerPodman docker exec --interactive --tty ovos_cli mana --help\npodman exec --interactive --tty ovos_cli mana --help\nThe easiest and quickest way to deploy Open Voice OS containers is to use a composer such as docker composer or podman-compose.
"},{"location":"getting-started/docker/composition/#composition-files","title":"Composition files","text":"Composition files provide an easy way to provision the stack (services and volumes) with the required options and configuration for each of the services.
Compose file Platforms Description docker-compose.yml Install core components (except the GUI) docker-compose.gui.yml Install GUI components docker-compose.skills.yml Install pre-defined skills docker-compose.hivemind.yml Install HiveMind components docker-compose.macos.yml Install core components (except the GUI) docker-compose.windows.yml Install core components (except the GUI) docker-compose.raspberrypi.yml Add GPIO support to ovos_core component docker-compose.raspberrypi.gui.yml Add /dev/vchiq to ovos_gui component"},{"location":"getting-started/docker/composition/#environment-files","title":"Environment files","text":"A Docker or Podman environment file contains lines about environment variables that are usable by the Docker or Podman command line. It is a convenient way to pass many environment variables to a single command.
Environment file Platforms Description .env Set of variables used by the composition files .env-raspberrypi Add GPIO_GID, I2C_GID and SPI_GID variables Some variables might need to be tuned to match your setup such as the TZ, XDG_RUNTIME_DIR, etc...
Variable Default Platforms Description DISPLAY :0 Display used by X or Wayland GPIO_GID 997 gpio group ID on Raspberry Pi HIVEMIND_CONFIG_FOLDER ~/hivemind/config HiveMind configuration directory HIVEMIND_CONFIG_PHAL_FOLDER ~/hivemind/config/phal HiveMind PHAL configuration directory HIVEMIND_SHARE_FOLDER ~/hivemind/share HiveMind shared directory HIVEMIND_USER hivemind User running in the container I2C_GID 994 i2c group ID on Raspberry Pi INPUT_GID 102 input group ID OVOS_CONFIG_FOLDER ~/ovos/config OVOS configureation directory OVOS_CONFIG_PHAL_FOLDER ~/ovos/config/phal OVOS PHAL configureation directory OVOS_SHARE_FOLDER ~/ovos/share OVOS shared directory OVOS_USER ovos User running in the container PULL_POLICY always Policy to pull Docker images RENDER_GID 106 render group ID SPI_GID 995 spi group ID on Raspberry Pi TMP_FOLDER ~/ovos/tmp OVOS temporary directory TZ America/Montreal Timezone to set in the container VERSION alpha Container image tag to pull VIDEO_GID 44 video group ID XDG_RUNTIME_DIR /run/user/1000 Path to XDG runtime directory Do not change OVOS_USER or HIVEMIND_USER
The OVOS_USER and HIVEMIND_USER variables should not be changed except if you build your own container images which a different one.
"},{"location":"getting-started/docker/composition/#how-to-get-the-gid","title":"How to get the GID?","text":"The getent command could be used in order to get the GID of gpio and render groups.
Raspberry PiLinux getent group gpio\ngetent group render\ngetent group video\ngetent group input\ngetent group i2c\ngetent group spi\ngetent group render\ngetent group video\ngetent group input\nThe XDG_RUNTIME_DIR variables requires a UID, this UID is the unique ID of the current user which will run the docker compose or podman-compose command.
LinuxWindows WSL2 echo $UID\necho $UID\nXDG Base Directory
Mac OS doesn't leverage XDG_RUNTIME_DIR variable as there is no support of XDG Base Directory on Mac OS.
"},{"location":"getting-started/docker/debug/","title":"Debugging","text":""},{"location":"getting-started/docker/debug/#debugging","title":"Debugging","text":""},{"location":"getting-started/docker/debug/#enable-debug-mode","title":"Enable debug mode","text":"First thing's first, enable the Open Voice OS's debug mode in ~/ovos/config/mycroft.conf to get more verbosity from the logs.
Restart containers
All containers will have to be restarted to receive the configuration change.
docker restart --time 0 $(docker container list --all --filter 'name=ovos' --filter 'name=hivemind' --quiet)\n{\n \"debug\": true,\n \"log_level\": \"DEBUG\"\n}\nNote
The commands below don't have to be executed in the same order as they are presented, free free to run them in the order you want!
"},{"location":"getting-started/docker/debug/#all-containers-logs","title":"All containers logs","text":"Access all the container logs at the same time, run the following command (make sure it matches the docker compose or podman-compose command you run to deploy the stack).
DockerPodman docker compose --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml --env-file .env logs --follow --tail 200\npodman-compose --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml --env-file .env logs --follow --tail 200\nAccess the logs of a specific container.
DockerPodman docker logs --follow --tail 200 ovos_audio\npodman logs --follow --tail 200 ovos_audio\nExecute a command inside a container without going into it.
DockerPodman docker exec --tty --interactive ovos_audio pactl info\npodman exec --tty --interactive ovos_audio pactl info\nGo inside a container and run multiple commands (where sh is the available shell in there).
DockerPodman docker exec --tty --interactive ovos_audio sh\npodman exec --tty --interactive ovos_audio sh\nMake sure the mycroft.conf configuration file is JSON valid by using the jq command.
jq command
In order to use the jq command, the package should be installed on your operating system.
cat ~/ovos/config/mycroft.conf | jq\nIf the configuration file is not valid JSON, jq will return something like this:
parse error: Expected another key-value pair at line 81, column 3\nGet the CPU, memory and I/O consumption per container.
DockerPodman docker stats --all --no-trunc\npodman stats --all --no-trunc\nGet the disk usage per volumes.
DockerPodman docker system df\npodman system df\nPre-build images
Open Voice OS provides pre-build images available on Docker Hub. These images are referenced by default within the docker-compose.*.yml files.
Open Voice OS is a sofisticated piece of software which has several components. These components have been split into containers to provide a better isolation and a microservices approach.
GUI images size
The GUI container images are larger than the other images as they need many QT libraries and GStreamer plugins in order to provide all the features supported by the voice assistant.
"},{"location":"getting-started/docker/images/#supported-cpu-architectures","title":"Supported CPU architectures","text":"Container images could be used for different CPU architectures using the multi-platform images feature.
CPU architecture Description amd64 Such as AMD and Intel processors aarch64 Such as Raspberry Pi 64-bit SoC armv7l Such as Raspberry Pi 32-bit SoC (not supported because of onnxruntime1 )"},{"location":"getting-started/docker/images/#containers","title":"Containers","text":"The list below is not exhaustive and doesn't mention anything about skill containers, but it is a fair list of the main components currently supported in ovos-docker.
Container Description ovos_messagebus Read more about ovos-messagebus ovos_phal Read more about ovos-phal ovos_phal_admin Read more about ovos-phal admin variant ovos_audio Read more about ovos-audio ovos_listener Read more about ovos-listener ovos_core Read more about ovos-core ovos_cli Read more about ovos-cli ovos_gui_websocket Read more about ovos-gui-messagebus ovos_gui Read more about ovos-gui hivemind_listener Read more about hivemind-listener hivemind_cli Read more about hivemind-cli"},{"location":"getting-started/docker/images/#tags","title":"Tags","text":"Container image tags allows you to deploy a specific version of Open Voice OS, it could be an untested version based on nigthly build or a stable version.
Image tag Description alpha Nightly build based on alpha releases from PyPi 0.0.8a Nightly build based on alpha releases from PyPi stable Build at every new stable release 0.0.8 Build at every new stable release Stable release
As Open Voice OS doesn't have a stable release for version 0.0.8 which has been designed to work with containers, there is no stable or 0.0.8 tags available yet.
"},{"location":"getting-started/docker/images/#volumes","title":"Volumes","text":"To allow data persistence, Docker or Podman volumes are required, they will prevent downloading the requirements everytime the containers are re-created.
Volume Description ovos_gui_file Share QML files from skills between the GUI message bus and the GUI client ovos_listener_records Wake words and utterances recorded samples ovos_local_state Moslty used to store logs from the different components ovos_models Models downloaded by precise-lite wake word plugin ovos_nltk Punkt Python package required by NLTK ovos_tts_cache .wav and .pho files acting as cache from TTS transcription ovos_vosk Models downloaded by VOSK during the initial boot ovos_listener_records allows you to store samples of wake words and utterances which could help you to build or improve models.
Enable samples recording
By default the recording features are disabled, \"record_wake_words\": true and \"save_utterances\": true will have to be added to the listener section of mycroft.conf to enable these capabilities.
~/ovos/config/mycroft.conf{\n\"listener\": {\n \"record_wake_words\": true,\n \"save_utterances\": true\n }\n}\nBut first thing's first you need to have Open Voice OS's containers up and running. Follow the guide.
https://github.com/microsoft/onnxruntime/issues/15337 \u21a9
"},{"location":"getting-started/docker/update/","title":"Update Open Voice OS","text":""},{"location":"getting-started/docker/update/#update-open-voice-os","title":"Update Open Voice OS","text":"Exact same command
In order to update the deployed stack (services and volumes), you must use the exact same command that has been used during the initial stack deployment.
The easiest and quickest way to update an Open Voice OS stack already deployed by docker compose or podman-compose is; of course to use docker compose or podman-compose as well.
Podman users
If you are running Podman instead of Docker, replace docker compose with podman-compose.
Raspberry PiLinuxMac OSWindows WSL2 docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml up --detach\ndocker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml up --detach\ndocker compose --project-name ovos --file docker-compose.macos.yml --file docker-compose.skills.yml --env-file .env up --detach\ndocker compose --project-name ovos --file docker-compose.windows.yml --file docker-compose.skills.yml up --detach\nBecause the pull_policy option of each service is set to always, everytime that a new image is uploaded with the same tag docker compose or podman-compose will pull-it and re-create the container based on this new image.
Change the version
If you want to change the image's tag to deploy, update the .env file with the right one. The alpha tag images are rebuilt every nights with the latest commits from the dev branch.
"},{"location":"getting-started/docker/installation/basic/","title":"Core components","text":""},{"location":"getting-started/docker/installation/basic/#install-open-voice-os","title":"Install Open Voice OS","text":"This section covers the installation of the core components only.
Only core components
Keep following the documentation if you want to install some pre-selected skills, HiveMind or even the GUI.
"},{"location":"getting-started/docker/installation/basic/#deploy-the-stack","title":"Deploy the stack","text":"Before running the docker compose or podman-compose commands, please read this section first.
Podman users
If you are running Podman instead of Docker, replace docker compose with podman-compose.
Raspberry PiLinuxMac OSWindows WSL2 docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml up --detach\ndocker compose --project-name ovos --file docker-compose.yml up --detach\ndocker compose --project-name ovos --file docker-compose.macos.yml --env-file .env up --detach\ndocker compose --project-name ovos --file docker-compose.windows.yml up --detach\nDepending your Internet speed, your Wi-Fi or Ethernet connection speed and your hardware (I/O), the whole process could take several minutes.
Hardware Time Raspberry Pi 3B+ with USB drive ~20 minutes Raspberry Pi 4B with USB drive ~3 minutes MacBook Air i7 Early 2015 with SSD ~2.5 minutes AMD Ryzen 7 5800 with NVMe drive ~45 seconds Resources overhead
To reduce the potential ressources overhead due to the image downloads and extractions, the --parallel x option could be added to the command in order to process the images by batch of x (where x is an integer).
"},{"location":"getting-started/docker/installation/basic/#containers-status","title":"Containers status","text":"At this point of the installation, here are the containers that should be up and running.
DockerPodman docker container list --all --filter 'name=ovos'\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n219eb6254d32 smartgic/ovos-listener-dinkum:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_listener\n31f5d5e7a1ec smartgic/ovos-audio:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_audio\n05e94905b867 smartgic/ovos-core:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_core\nd256c2e7b6f3 smartgic/ovos-phal:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_phal\na4db13a597a4 smartgic/ovos-phal-admin:alpha \"/bin/bash /usr/loca\u2026\" 25 hours ago Up 8 hours ovos_phal_admin\nd157740c9965 smartgic/ovos-messagebus:alpha \"/bin/bash -c ovos-m\u2026\" 25 hours ago Up 8 hours (healthy) ovos_messagebus\n6e3536dcfae5 smartgic/ovos-cli:alpha \"sleep infinity\" 25 hours ago Up 8 hours ovos_cli\npodman container list --all --filter 'name=ovos'\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n219eb6254d32 smartgic/ovos-listener-dinkum:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_listener\n31f5d5e7a1ec smartgic/ovos-audio:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_audio\n05e94905b867 smartgic/ovos-core:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_core\nd256c2e7b6f3 smartgic/ovos-phal:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_phal\na4db13a597a4 smartgic/ovos-phal-admin:alpha \"/bin/bash /usr/loca\u2026\" 25 hours ago Up 8 hours ovos_phal_admin\nd157740c9965 smartgic/ovos-messagebus:alpha \"/bin/bash -c ovos-m\u2026\" 25 hours ago Up 8 hours (healthy) ovos_messagebus\n6e3536dcfae5 smartgic/ovos-cli:alpha \"sleep infinity\" 25 hours ago Up 8 hours ovos_cli\n~/ovos/config/mycroft.conf configuration file is mounted into each containers as a read-only volume.
First I configure then I deploy
Before deploying the services and volumes, it is recommended to set the OVOS's configuration to make sure the services initial start has the correct settings such as the lang for example.
"},{"location":"getting-started/docker/installation/configuration/#initial-configuration","title":"Initial configuration","text":"This configuration is very basic, it instructs the Open Voice OS instance to run in English as main language.
~/ovos/config/mycroft.conf{\n \"play_wav_cmdline\": \"aplay %1\",\n \"lang\": \"en-us\",\n \"listener\": {\n \"VAD\": {\n \"module\": \"ovos-vad-plugin-silero\"\n }\n }\n}\nBy default, the Open Voice OS services will write their logs into a file under ~/.local/state/mycroft directory but since we are running containers, we can leverage the docker logs or podman logs commands.
The solution is to add these lines into the ~/ovos/config/mycroft.conf file (create the file if it does not exist), this will tell the services to redirect their logs to the container stdout.
~/ovos/config/mycroft.conf{\n \"logs\": {\n \"path\": \"stdout\"\n },\n \"play_wav_cmdline\": \"aplay %1\",\n \"lang\": \"en-us\",\n \"listener\": {\n \"VAD\": {\n \"module\": \"ovos-vad-plugin-silero\"\n }\n }\n}\nDuring debug session, it might be useful to retrieve information from the different component using the ovos-logs command, this command is looking for log files from the ~/.local/state/mycroft directory. If needed, then remove the following lines from the ~/ovos/config/mycroft.conf file.
~/ovos/config/mycroft.conf{\n \"logs\": {\n \"path\": \"stdout\"\n }\n}\nServices already deployed
If the services have been already deployed and the ~/ovos/config/mycroft.conf has changed, then you will have to restart the containers impacted by the change(s).
"},{"location":"getting-started/docker/installation/configuration/#custom-asoundrc-for-alsa","title":"Custom .asoundrc for ALSA","text":"Sometime a custom .asoundrc file migth be required, a common example is when a voice HAT (Hardware Attached on Top) such as Google AIY Voice Hat is connected to a Raspberry Pi, a custom .asoundrc might be required to make it works with ALSA.
In order to pass this custom .asoundrc file to the containers, the file must be created within the ~/ovos/config/ directory and named asoundrc (with no .).
Only for the containers using sound
The custom .asoundrc file will be passed only to the containers who leverage the audio stack; ovos_listener, ovos_phal, ovos_audio, ovos_core.
~/ovos/config/asoundrc# Configuration for Google AIY Voice Hat V1\noptions snd_rpi_googlemihat_soundcard index=0\n\npcm.softvol {\n type softvol\n slave.pcm dmix\n control {\n name Master\n card 0\n }\n}\n\npcm.micboost {\n type route\n slave.pcm dsnoop\n ttable {\n 0.0 30.0\n 1.1 30.0\n }\n}\n\npcm.!default {\n type asym\n playback.pcm \"plug:softvol\"\n capture.pcm \"plug:micboost\"\n}\n\nctl.!default {\n type hw\n card 0\n}\nServices already deployed
If the services have been already deployed and the ~/ovos/config/asoundrc has changed, then you will have to restart the containers impacted by the change(s).
"},{"location":"getting-started/docker/installation/gui/","title":"GUI","text":""},{"location":"getting-started/docker/installation/gui/#install-the-open-voice-os-gui","title":"Install the Open Voice OS GUI","text":"For Linux eyes only
The GUI is currently available only on Linux operating system, not on Mac OS or Windows.
The Open Voice OS GUI supports two types of system execution:
Using X or Wayland display servers Using EGLFS which doesn't require any display server which is perfect for headless installation When using EGLFS, the DISPLAY variable from the .env composition environment file must be removed or commented as if present the X or Wayland display servers will be tried first and result in an ovos_gui container in error.
Hardware accelerated on Raspberry Pi 4 and 5
Raspberry Pi 4 and 5 will leverage the GPU hardware acceleration which will provide a smoother experience.
If not running on a Raspberry Pi 4 or 5 then the CPU might be used to render the GUI which will result in a high CPU consumption and a poor user exprience.
"},{"location":"getting-started/docker/installation/gui/#configuration","title":"Configuration","text":"The ovos-gui-messagebus component must be configured in order to receive the QML files from the skill containers. Because of these file transfers, the ovos-message-bus component must be configured to allow bigger payload.
~/ovos/config/mycroft.conf{\n \"logs\": {\n \"path\": \"stdout\"\n },\n \"play_wav_cmdline\": \"aplay %1\",\n \"lang\": \"en-us\",\n \"listener\": {\n \"VAD\": {\n \"module\": \"ovos-vad-plugin-silero\"\n }\n },\n \"gui\": {\n \"extension\": \"ovos-gui-plugin-shell-companion\",\n \"gui_file_host_path\": \"/home/ovos/.cache/gui_files\"\n },\n \"websocket\": {\n \"max_msg_size\": 100\n }\n}\nTip
You can skip this section if your are using EGLFS and go to GUI services deployment.
In order to allow only the ovos_gui container to access to the X or Wayland display server, you will have to allow the container (based on its hostname) to connect to the display session.
export DISPLAY=\":0\"\nxhost +local:ovos_gui\nThis command is not permanent, when your operating system will reboot you will have to run the command again. To make it permanent systemd should be leveraged as a user service.
Raspberry PiLinux mkdir -p ~/.config/systemd/user\nmkdir -p ~/.config/systemd/user\nCreate the xhost.service unit file into the ~/.config/systemd/user directory.
~/.config/systemd/user/xhost.service[Unit]\nDescription=Allow ovos_gui container to use X from user session\n\n[Service]\nType=oneshot\nEnvironment=\"DISPLAY=:0\"\nExecStart=/usr/bin/xhost +local:ovos_gui\nExecStop=/usr/bin/xhost -local:ovos_gui\nRemainAfterExit=yes\nRestart=on-failure\nRestartSec=5s\n\n[Install]\nWantedBy=default.target\nEnable and start the new xhost.service systemd service.
Raspberry PiLinux systemctl --user enable xhost.service\nsystemctl --user start xhost.service\nsystemctl --user enable xhost.service\nsystemctl --user start xhost.service\nThe xhost command is part of the x11-xserver-utils package on Debian based distributions such as Raspberry Pi OS.
"},{"location":"getting-started/docker/installation/gui/#gui-services-deployment","title":"GUI services deployment","text":"Podman users
If you are running Podman instead of Docker, replace docker compose with podman-compose.
Raspberry PiLinux docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml --file docker-compose.gui.yml --file docker-compose.raspberrypi.gui.yml up --detach\ndocker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml --file docker-compose.gui.yml up --detach\nBefore going further, please make sure to refer to this section as the following commands could defer depending your setup.
"},{"location":"getting-started/docker/installation/requirements/#get-the-ovos-docker-sources","title":"Get the ovos-docker sources","text":"The ~/hivemind directory is only required if you plan to use HiveMind.
All git clone https://github.com/OpenVoiceOS/ovos-docker.git ~/ovos-docker\nmkdir -p ~/ovos/{config/phal,share,tmp} ~/hivemind/{config/phal,share}\nchown ${USER}:${USER} -R ~/ovos ~/hivemind\ncd ~/ovos-docker/compose\nBecause some containers require /run/user/1000 to be mounted, systemd should be instructed to log the user during the boot process and make /run/user/1000 directory available before the containers start.
Raspberry PiLinux sudo loginctl enable-linger $USER\nsudo loginctl enable-linger $USER\n.env file is a strong requirement
Please make sure to read and understand this section as if you don't then the deployment migth fail.
The composer requires an environment file in order to deploy the services and volumes with the correct settings for your setup.
alpha version by default
As mentioned in this section, the current default VERSION (tag) is alpha.
The example files start with a . (dot) which means they are hidden, use the ls -a command to list all the files included the hidden ones.
Below is an example of .env for Linux (not Raspberry Pi), please read this section for more details about what these variables do.
.envDISPLAY=:0\nHIVEMIND_CONFIG_FOLDER=~/hivemind/config\nHIVEMIND_CONFIG_PHAL_FOLDER=~/hivemind/config/phal\nHIVEMIND_SHARE_FOLDER=~/hivemind/share\nHIVEMIND_USER=hivemind\nINPUT_GID=102\nOVOS_CONFIG_FOLDER=~/ovos/config\nOVOS_CONFIG_PHAL_FOLDER=~/ovos/config/phal\nOVOS_SHARE_FOLDER=~/ovos/share\nOVOS_USER=ovos\nPULL_POLICY=always\nTMP_FOLDER=~/ovos/tmp\nTZ=America/Montreal\nVERSION=alpha\nVIDEO_GID=44\nXDG_RUNTIME_DIR=/run/user/1000\ncp .env-raspberrypi .env\ncp .env.example .env\ncp .env.example .env\ncp .env.example .env\nExamples are provided, please make sure to select the right one and to set the proper values.
"},{"location":"getting-started/docker/installation/requirements/#i2c-and-spi-on-raspberry-pi","title":"I2C and SPI on Raspberry Pi","text":"The Raspberry Pi board supports I2C, I2S and SPI buses. These three buses must be enabled in order to allow the containers below to start:
ovos_coreovos_phalovos_phal_admin Follow the steps below to enable I2C, I2S and SPI.
Raspberry Pi echo \"dtparam=i2c_arm=on\" | sudo tee -a /boot/config.txt\necho \"dtparam=i2s=on\" | sudo tee -a /boot/config.txt\necho \"dtparam=spi=on\" | sudo tee -a /boot/config.txt\necho \"i2c-dev\" | sudo tee /etc/modules-load.d/i2c.conf\nsudo reboot\nTwo different methods are supported by ovos-docker to install Open Voice OS's skills, each of them having pros and cons .
Slow hardware
When running Open Voice OS on slow hardware such as Raspberry Pi 3B+, it is recommended to install skills using the \"As part of ovos_core container\" method in order to reduce the memory consumption.
"},{"location":"getting-started/docker/installation/skills/#as-part-of-ovos_core-container","title":"As part of ovos_core container","text":"The first method is to use a skills.list file within the ~/ovos/config/ directory, this file acts as a Python requirements.txt file.
When ovos_core container starts, it will look for a skills.list file and install the skills defined in there.
Skill requirements
The skill has to be compatible with the pip install method which requires a setup.py file.
skills.listovos-skill-stop # Latest skill version on PyPi\novos-skill-volume==0.0.1 # Specific skill version on PyPi\ngit+https://github.com/OpenVoiceOS/skill-ovos-wikipedia.git@fix/whatever # Specific skill's branch on GitHub\nIf the ovos_core container is wiped for any reasons (like an update), the skill(s) will be automatically reprovisioned.
Not only for skills
skills.list file could be used as well to install extra Python librairies, e.g., SoCo, RPi.GPIO. Just make sure to avoid empty lines.
The main advantage of this method is the simplicity but the downside will be more Python dependencies (libraries) within the ovos_core container, potential conflicts across them, a lack of isolation and a slower start of the container.
"},{"location":"getting-started/docker/installation/skills/#as-standalone-container-recommended","title":"As standalone container (recommended)","text":"The second method is to leverage the ovos-workshop component by running a skill as standalone, it means the skill will not be part of ovos_core container but it will be running inside its own container.
The main advantage is that each skill is isolated which provide more flexibility about Python dependencies (libraries), packages. It is easier to update and more secure but the downside will be that more system resources will be consumed and a container image has to be built for each skill.
Podman users
If you are running Podman instead of Docker, replace docker compose with podman-compose.
Raspberry PiLinuxMac OSWindows WSL2 docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml up --detach\ndocker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml up --detach\ndocker compose --project-name ovos --file docker-compose.macos.yml --file docker-compose.skills.yml --env-file .env up --detach\ndocker compose --project-name ovos --file docker-compose.windows.yml --file docker-compose.skills.yml up --detach\nDepending your Internet speed, your Wi-Fi or Ethernet connection speed and your hardware (I/O), the whole process could take several minutes.
Hardware Time Raspberry Pi 3B+ with USB drive ~12 minutes Raspberry Pi 4B with USB drive ~48 seconds MacBook Air i7 Early 2015 with SSD ~50 seconds AMD Ryzen 7 5800 with NVMe drive ~15 seconds Resources overhead
To reduce the potential ressources overhead due to the image downloads and extractions, the --parallel x option could be added to the command in order to process the images by batch of x (where x is an integer).
If the ovos_core container is restarted or even deleted, the skill containers will automatically register again to it.
"},{"location":"getting-started/docker/installation/skills/#containers-status","title":"Containers status","text":"At this point of the installation, here are the containers that should be up and running.
DockerPodman docker container list --all --filter 'name=ovos'\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n1446b87d7a32 smartgic/ovos-skill-volume:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_volume\n7ad46a871661 smartgic/ovos-skill-wikipedia:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_wikipedia\nb43b8cf31a43 smartgic/ovos-skill-fallback-unknown:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_fallback_unknown\nf27d3fceecec smartgic/ovos-skill-alerts:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_alerts\n30b70c9e72ef smartgic/ovos-skill-hello-world:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_hello_world\nf42175c6d7b8 smartgic/ovos-skill-weather:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_weather\n0ae42a59fb0b smartgic/ovos-skill-stop:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_stop\n5760fb22deb9 smartgic/ovos-skill-date-time:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_date_time\n73f4d4b0a091 smartgic/ovos-skill-personal:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_personal\n219eb6254d32 smartgic/ovos-listener-dinkum:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_listener\n31f5d5e7a1ec smartgic/ovos-audio:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_audio\n05e94905b867 smartgic/ovos-core:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_core\nd256c2e7b6f3 smartgic/ovos-phal:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_phal\na4db13a597a4 smartgic/ovos-phal-admin:alpha \"/bin/bash /usr/loca\u2026\" 25 hours ago Up 8 hours ovos_phal_admin\nd157740c9965 smartgic/ovos-messagebus:alpha \"/bin/bash -c ovos-m\u2026\" 25 hours ago Up 8 hours (healthy) ovos_messagebus\n6e3536dcfae5 smartgic/ovos-cli:alpha \"sleep infinity\" 25 hours ago Up 8 hours ovos_cli\npodman container list --all --filter 'name=ovos'\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n1446b87d7a32 smartgic/ovos-skill-volume:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_volume\n7ad46a871661 smartgic/ovos-skill-wikipedia:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_wikipedia\nb43b8cf31a43 smartgic/ovos-skill-fallback-unknown:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_fallback_unknown\nf27d3fceecec smartgic/ovos-skill-alerts:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_alerts\n30b70c9e72ef smartgic/ovos-skill-hello-world:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_hello_world\nf42175c6d7b8 smartgic/ovos-skill-weather:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_weather\n0ae42a59fb0b smartgic/ovos-skill-stop:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_stop\n5760fb22deb9 smartgic/ovos-skill-date-time:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_date_time\n73f4d4b0a091 smartgic/ovos-skill-personal:alpha \"ovos-skill-launcher\u2026\" 18 hours ago Up 8 hours ovos_skill_personal\n219eb6254d32 smartgic/ovos-listener-dinkum:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_listener\n31f5d5e7a1ec smartgic/ovos-audio:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_audio\n05e94905b867 smartgic/ovos-core:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_core\nd256c2e7b6f3 smartgic/ovos-phal:alpha \"/bin/bash /usr/loca\u2026\" 18 hours ago Up 8 hours ovos_phal\na4db13a597a4 smartgic/ovos-phal-admin:alpha \"/bin/bash /usr/loca\u2026\" 25 hours ago Up 8 hours ovos_phal_admin\nd157740c9965 smartgic/ovos-messagebus:alpha \"/bin/bash -c ovos-m\u2026\" 25 hours ago Up 8 hours (healthy) ovos_messagebus\n6e3536dcfae5 smartgic/ovos-cli:alpha \"sleep infinity\" 25 hours ago Up 8 hours ovos_cli\nA microhpone plugin allows you to use a specific sound protocol in order to get voice samples from your microphone. Depending the operating system you are running on, you will have to choose the correct plugin.
Note
The microhpone plugins are handled by the ovos_listener container.
The ovos_listener container comes with few pre-installed microphone plugins such as:
ovos-microphone-plugin-alsa is using pyalsaaudio Python library (default)ovos-microphone-plugin-sounddevice is using sounddevice Python library If the existing microphone plugins are not enough then you can install yours by following the same principle as for the STT plugins by adding a listener.list file within the ~/ovos/config/ directory, this file acts as a Python requirements.txt file.
Plugins requirements
These plugins have to be compatible with the pip install method which requires a setup.py file.
When the ovos_listener container starts, it will look for this file and install the plugins defined in there.
~/ovos/config/listener.listovos-microphone-plugin-pyaudio==0.2.0a1 # Specific plugin version on PyPi\novos-microphone-plugin-arecord # Latest plugin version on PyPi\ngit+https://github.com/OpenVoiceOS/ovos-microphone-plugin-socket.git@fix/whatever # Specific branch of a plugin on GitHub\nThe ovos_listener container must be restarted if a change occurs in the listener.list file.
DockerPodman docker restart ovos_listener\npodman restart ovos_listener\nHere are the two main plugins to use per platform.
Plugin Platforms ovos-microphone-plugin-alsa ovos-microphone-plugin-sounddevice Choose the correct plugin
If a wrong plugin is used, the listener will not be able to hear you which means that you will not be able to interact with your Open Voice OS instance.
"},{"location":"getting-started/docker/plugins/phal/","title":"PHAL","text":""},{"location":"getting-started/docker/plugins/phal/#phal-plugins","title":"PHAL plugins","text":"The Plugin based Hardware Abstraction Layer plugins allow you to interact with system components such as Wi-Fi, GPIO, NetworkManager, etc... but not only.
Note
The PHAL plugins are handled by the ovos_phal and ovos_phal_admin containers.
ovos_phal_admin is a privileged container
The ovos_phal_admin purpose is to run plugins that require accesses to some devices, files or services.
Plugins installed in this container have to be enabled into ~/ovos/config/mycroft.conf in order to get loaded, this acts as an extra layer of security.
The ovos_phal container comes with few pre-installed PHAL plugins such as:
ovos-PHAL-plugin-alsa controls system volume with ALSAovos-PHAL-plugin-system handles bus events to interact with the operating system If the existing PHAL plugins are not enough then you can install yours by following the same principle as for the STT plugins by adding a phal.list or phal_admin.list files within the ~/ovos/config/ directory, this file acts as a Python requirements.txt file.
Plugins requirements
These plugins have to be compatible with the pip install method which requires a setup.py file.
When the ovos_phal or ovos_phal_admin containers start, they will look for these files and install the skpluginsills defined in there.
~/ovos/config/phal.list or ~/ovos/config/phal_admin.listovos-phal-plugin-ipgeo==0.0.1 # Specific plugin version on PyPi\novos-PHAL-plugin-pulse # Latest plugin version on PyPi\ngit+https://github.com/OpenVoiceOS/ovos-PHAL-plugin-homeassistant.git@fix/whatever # Specific branch of a plugin on GitHub\nThe ovos_phal or ovos_phal_admin containers must be restarted if a change occurs in the phal.list or phal_admin.lis files.
DockerPodman docker restart ovos_phal ovos_phal_admin\npodman restart ovos_phal ovos_phal_admin\nThe Speech-To-Text plugins allow you to connect Open Voice OS with different STT servers, it could be FasterWhisper, VOSK, Google Translate, Deepgram, etc... Each of these STT providers will have different languages support, precision and performances.
Note
The Speech-To-Text plugins are handled by the ovos_listener container.
The ovos_listener container comes with few pre-installed STT plugins such as:
ovos-stt-plugin-server allows you to reach an external STT serviceovos-stt-plugin-vosk is an offline STT service If the existing STT plugins are not enough then you can install yours by following the same principle as for the microphone plugins by adding a listener.list file within the ~/ovos/config/ directory, this file acts as a Python requirements.txt file.
Plugins requirements
These plugins have to be compatible with the pip install method which requires a setup.py file.
When the ovos_listener container starts, it will look for this file and install the plugins defined in there.
~/ovos/config/listener.listovos-stt-plugin-vosk==0.2.0a1 # Specific plugin version on PyPi\novos-stt-plugin-server # Latest plugin version on PyPi\ngit+https://github.com/OpenVoiceOS/ovos-stt-plugin-chromium.git@fix/whatever # Specific branch of a plugin on GitHub\nThe ovos_listener container must be restarted if a change occurs in the listener.list file.
DockerPodman docker restart ovos_listener\npodman restart ovos_listener\nThe Text-To-Speech plugins allow you to connect Open Voice OS with different TTS servers, it could be Piper, Coqui, Amazon Polly, Mimic, etc... Each of these TTS providers will have different voices and languages.
Note
The Text-To-Speech plugins are handled by the ovos_audio container.
The ovos_audio container comes with few pre-installed TTS plugins such as:
ovos-tts-plugin-mimic is the original Mycroft AI TTS with the iconic Alan Pope's voiceovos-tts-plugin-mimic2 is the cloud based version hosted on Mycroft AI infrastructureovos-tts-plugin-mimic3-server is the latest Mycroft AI TTS engineovos-tts-plugin-server allows you to reach an external TTS service If the existing TTS plugins are not enough then you can install yours by following the same principle as for the skills by adding an audio.list file within the ~/ovos/config/ directory, this file acts as a Python requirements.txt file.
Plugins requirements
These plugins have to be compatible with the pip install method which requires a setup.py file.
When the ovos_audio container starts, it will look for this file and install the plugins defined in there.
~/ovos/config/audio.listovos-tts-plugin-marytts==0.0.1a1 # Specific plugin version on PyPi\nneon-tts-plugin-mozilla-remote # Latest plugin version on PyPi\ngit+https://github.com/NeonGeckoCom/neon-tts-plugin-polly.git@fix/whatever # Specific branch of a plugin on GitHub\nThe ovos_audio container must be restarted if a change occurs in the audio.list file.
DockerPodman docker restart ovos_audio\npodman restart ovos_audio\nIn order to run TensorFlow used by few Open Voice OS components, the CPU must support AVX (Advanced Vector Extensions) instruction set for x86 processors or SIMD (Single Instruction, Multiple Data) instruction set for ARM processors.
LinuxMac OS grep -E -i --color \"avx|simd\" /proc/cpuinfo\nsysctl -a | grep -E -i --color \"avx|simd\"\nIf the command does not return an output then your CPU doesn't meet the requirements for TensorFlow.
AVX or SIMD instruction set missing
Because the instruction set is missing does not mean that Open Voice OS can't run on your hardware, it simply means that Precise wake word engine or anything else using TensorFlow will not run on it.
"},{"location":"getting-started/docker/prerequisites/engine/","title":"Container engine","text":""},{"location":"getting-started/docker/prerequisites/engine/#container-engine","title":"Container engine","text":""},{"location":"getting-started/docker/prerequisites/engine/#installation","title":"Installation","text":"As we are leveraging containers, a container engine such as Docker or Podman is required (only one of them should be installed), as well as their composer.
If you are not familiar with what a container engine or a composer are then please refer to this section first as these fundamentals must be understood.
"},{"location":"getting-started/docker/prerequisites/engine/#versions","title":"Versions","text":"When running on Linux, please make sure to not use Docker Desktop but prefer Docker Engine as it is a better choice in our case. Docker Desktop runs a virtual machine which doesn't have access to the same devices as the host has, due to this limitation the /dev/snd device will not be usable and this will prevent the usage of speakers and microphone.
docker-compose versus docker compose
As mentioned by Docker, from July 2023 Compose V1 (docker-compose) will not received updates anymore which makes it deprecated and replaced by Compose V2 (docker compose) directly embedded into the docker command line.
Either you choose to install Docker or Podman and their composer on Linux, Mac OS or Windows, please refer to the official documentation1 .
Minimum required versions
In order to get the latest features supported by ovos-docker, please make sure to install a recent version of Docker (>= 24.x.x) or Podman (>= 4.3.x) for your operating system.
"},{"location":"getting-started/docker/prerequisites/engine/#dont-be-root-be-a-user","title":"Don't be root, be a user","text":"You should not run docker command as root user or using the sudo command, if so then you will get some error messages such as Permission denied and some containers could restart in a loop.
To allow a simple user to execute the docker command, make sure to add the user to the docker group.
Linux sudo usermod -a -G docker $USER\nOnce added to the docker group you will have to logout from the current session (graphical or SSH) in order to get the group added to your user once you reconnect.
Once reconnected, run the following command to ensure the docker has been appened to your $USER.
Linux id\nuid=1000(foobar) gid=1000(foobar) groups=1000(foobar),973(docker)\nThe GID could differ compare to your setup.
"},{"location":"getting-started/docker/prerequisites/engine/#validation","title":"Validation","text":"DockerPodman docker system info\ndocker container list\npodman system info\npodman container list\n Docker official documentation or Podman official documentation.\u00a0\u21a9
"},{"location":"getting-started/docker/prerequisites/sound/","title":"Sound system","text":""},{"location":"getting-started/docker/prerequisites/sound/#sound-system","title":"Sound system","text":"PulseAudio is a requirement and has to be up and running on the host (not inside the containers) to expose a socket (for communication) and a cookie (for authentication) to allow the containers to have access to the microphone (input device) and speakers (output device).
On modern Linux distribution, PipeWire now handles the sound stack on the system.
Sound server auto-detection
ovos-docker supports both native PulseAudio and PipeWire, the containers will automatically detect which sound server is running on the operating system.
"},{"location":"getting-started/docker/prerequisites/sound/#mac-os-and-windows","title":"Mac OS and Windows","text":"If you are running an operating system other Linux such as Mac OS or Windows, then PulseAudio will have to be installed to act as a gateway between the containers and the OS.
Mac OSWindows WSL2 brew install pulseaudio\nbrew services stop pulseaudio\nsed -i \"\" \"s/#load-module module-native-protocol-tcp/load-module module-native-protocol-tcp/g\" $(brew ls pulseaudio | grep default.pa$)\nbrew services start pulseaudio\nsudo apt install pulseaudio\nThe user running the containers must be part of the audio system group (depending the Linux distribution).
PulseAudio files permissions
Check the permissions for ~/.config/pulse/ and /run/user/1000/pulse directories, they should belong to the user running the stack (where 1000 is your user ID), not to root user.
If you are running on Mac OS, there is no /run/user/1000/ directory.
"},{"location":"getting-started/docker/prerequisites/sound/#validation","title":"Validation","text":"pactl is a PulseAudio command shipped with the pulseaudio-utils package and pw-cli is a PipeWire command shipped with pipewire-utils or pipewire-bin depending your distribution.
These commands provide information about the status of PulseAudio or PipeWire.
PulseAudioPipeWire pactl info\npw-cli info\nAt least one of the sources (microphones/audio input) returned, should match the Default Source line from the pactl info command or the Audio/Source line from the wpctl status command.
PulseAudioPipeWire pactl list sources short\nwpctl status | grep Audio/Source\nAt least one of the sinks (speakers/audio output) returned, should match the Default Sink line from the pactl info command or the Audio/Sink line from the wpctl status command.
PulseAudioPipeWire pactl list sinks short\nwpctl status | grep Audio/Sink\nIn order to secure your Open Voice OS instance, few more steps are required and few concepts must be understood.
"},{"location":"getting-started/docker/security/hardening/#apparmor","title":"AppArmor","text":"AppArmor and SELinux are examples of Mandatory Access Control (MAC) systems. These systems differ from other security controls which are generally called Discretionary Access Control (DAC) systems in that, generally, the user can't change their operation.
AppArmor packages
AppArmor must be installed on your system before going further. Please refer to your Linux distribution documentation to install it.
"},{"location":"getting-started/docker/security/hardening/#enable-apparmor","title":"Enable AppArmor","text":"Raspberry Pi OSDebian & Ubuntu /boot/cmdline.txtapparmor=1 security=apparmor\napparmor=1 security=apparmor\nSystem must be rebooted to instruct the kernel to load AppArmor during the boot sequence. Once rebooted, check the AppArmor status using the aa-status command.
Raspberry Pi OSDebian & Ubuntu sudo aa-status\nsudo aa-status\nAppArmor and Podman support1
AppArmor support for Podman is not yet fully functional.
Docker applies the docker-default AppArmor profile to new containers. In Docker 1.13 and later this profile is created in tmpfs and then loaded into the kernel.
The container engine should now be aware of apparmor as an available security option.
docker system info | grep -i apparmor\nAll the containers except ovos_phal_admin should now be confined with the docker-default AppArmor profile.
docker container list --quiet --all --filter \"name=ovos\" | xargs docker inspect --format \"{{ .Name }}: AppArmorProfile={{ .AppArmorProfile }}\"\n/ovos_skill_volume: AppArmorProfile=docker-default\n/ovos_skill_wikipedia: AppArmorProfile=docker-default\n/ovos_skill_fallback_unknown: AppArmorProfile=docker-default\n/ovos_skill_alerts: AppArmorProfile=docker-default\n/ovos_skill_hello_world: AppArmorProfile=docker-default\n/ovos_skill_weather: AppArmorProfile=docker-default\n/ovos_skill_stop: AppArmorProfile=docker-default\n/ovos_skill_date_time: AppArmorProfile=docker-default\n/ovos_skill_personal: AppArmorProfile=docker-default\n/ovos_listener: AppArmorProfile=docker-default\n/ovos_audio: AppArmorProfile=docker-default\n/ovos_core: AppArmorProfile=docker-default\n/ovos_phal: AppArmorProfile=docker-default\n/ovos_phal_admin: AppArmorProfile=unconfined\n/ovos_messagebus: AppArmorProfile=docker-default\n/ovos_cli: AppArmorProfile=docker-default\novos_phal_admin container is not confined
The ovos_phal_admin container is not confined as it runs as a privileged container.
"},{"location":"getting-started/docker/security/hardening/#message-bus","title":"Message bus","text":"By default, the message bus is listening on address 0.0.0.0 and port 8181 because the ovos_messagebus is created using the --network host option. This could be a security issue as an external device could connect to the message bus and send and/or read messages.
Why using --network host?
Some Open Voice OS skills such as Home Assistant or Sonos require access to your private network in order to communicate with your IoT devices.
To prevent potential security issues, it is recommended to use a firewall the port 8181.
iptables will be demonstrated as an example but if firewalld or ufw services are used, then make sure to be compliant with your distribution.
Linux sudo iptables -A INPUT -p tcp -s localhost --dport 8181 -j ACCEPT\nsudo iptables iptables -A INPUT -p tcp --dport 8181 -j DROP\nThis will allow connections to port 8181 only from localhost (internal).
Keep your ports closed
Keep in mind to firewall any other ports which should not be exposed outside of the host by using the same IPTables method.
If you really need to connect an external application to the message bus, we recommend to use HiveMind to ensure a proper security exposure.
Enable rootless AppArmor for Podman \u21a9
"},{"location":"getting-started/docker/security/hivemind/","title":"HiveMind","text":""},{"location":"getting-started/docker/security/hivemind/#hivemind-to-the-rescue","title":"HiveMind to the rescue","text":""},{"location":"getting-started/docker/security/hivemind/#what-is-hivemind","title":"What is HiveMind?","text":"HiveMind is a community-developed superset or extension of Open Voice OS, the open-source voice operating system.
With HiveMind, you can extend one (or more, but usually just one!) instance of Open Voice OS to as many devices as you want, including devices that can't ordinarily run Open Voice OS!
Official documentation
What it means, is that HiveMind allows external connections to the message bus by using a secured protocol.
Fulfill the requirements first
Before going further, please make sure that all the requirements are fulfilled.
A composition file is available in order to deploy hivemind_listener and hivemind_cli services.
Podman users
If you are running Podman instead of Docker, replace docker compose with podman-compose.
Raspberry PiLinuxMac OSWindows WSL2 docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml up --detach\ndocker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml up --detach\ndocker compose --project-name ovos --file docker-compose.macos.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml --env-file .env up --detach\ndocker compose --project-name ovos --file docker-compose.windows.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml up --detach\nFor more information about how to authenticate with the HiveMind listener, please read the HiveMind-core repository documentation.
Once the HiveMind containers are up and running, the HiveMind command line allows you to add client, to list them, to delete them, etc...
DockerPodman docker exec --interactive --tty hivemind_cli hivemind-core --help\npodman exec --interactive --tty hivemind_cli hivemind-core --help\nPort 5678 must be open
In order to to reach the HiveMind listener, the port 5678 has to be open on the host. Please make sure your firewall allows the connection to this port or the clients will not be able to connect to it.
"},{"location":"getting-started/docker/security/hivemind/#containers-status","title":"Containers status","text":"At this point of the installation, here are the containers that should be up and running.
DockerPodman docker container list --all --filter 'name=ovos' --filter 'name=hivemind'\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n4e2d45799de8 smartgic/hivemind-cli:alpha \"sleep infinity\" 16 minutes ago Up 16 minutes hivemind_cli\n612a9ea32405 smartgic/hivemind-listener:alpha \"hivemind-core listen\" 16 minutes ago Up 16 minutes hivemind_listener\n1446b87d7a32 smartgic/ovos-skill-volume:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_volume\n7ad46a871661 smartgic/ovos-skill-wikipedia:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_wikipedia\nb43b8cf31a43 smartgic/ovos-skill-fallback-unknown:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_fallback_unknown\nf27d3fceecec smartgic/ovos-skill-alerts:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_alerts\n30b70c9e72ef smartgic/ovos-skill-hello-world:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_hello_world\nf42175c6d7b8 smartgic/ovos-skill-weather:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_weather\n0ae42a59fb0b smartgic/ovos-skill-stop:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_stop\n5760fb22deb9 smartgic/ovos-skill-date-time:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_date_time\n73f4d4b0a091 smartgic/ovos-skill-personal:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_personal\n219eb6254d32 smartgic/ovos-listener-dinkum:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_listener\n31f5d5e7a1ec smartgic/ovos-audio:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_audio\n05e94905b867 smartgic/ovos-core:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_core\nd256c2e7b6f3 smartgic/ovos-phal:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_phal\na4db13a597a4 smartgic/ovos-phal-admin:alpha \"/bin/bash /usr/loca\u2026\" 25 hours ago Up 8 hours ovos_phal_admin\nd157740c9965 smartgic/ovos-messagebus:alpha \"/bin/bash -c ovos-m\u2026\" 25 hours ago Up 8 hours (healthy) ovos_messagebus\n6e3536dcfae5 smartgic/ovos-cli:alpha \"sleep infinity\" 25 hours ago Up 8 hours ovos_cli\npodman container list --all --filter 'name=ovos'\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n4e2d45799de8 smartgic/hivemind-cli:alpha \"sleep infinity\" 16 minutes ago Up 16 minutes hivemind_cli\n612a9ea32405 smartgic/hivemind-listener:alpha \"hivemind-core listen\" 16 minutes ago Up 16 minutes hivemind_listener\n1446b87d7a32 smartgic/ovos-skill-volume:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_volume\n7ad46a871661 smartgic/ovos-skill-wikipedia:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_wikipedia\nb43b8cf31a43 smartgic/ovos-skill-fallback-unknown:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_fallback_unknown\nf27d3fceecec smartgic/ovos-skill-alerts:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_alerts\n30b70c9e72ef smartgic/ovos-skill-hello-world:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_hello_world\nf42175c6d7b8 smartgic/ovos-skill-weather:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_weather\n0ae42a59fb0b smartgic/ovos-skill-stop:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_stop\n5760fb22deb9 smartgic/ovos-skill-date-time:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_date_time\n73f4d4b0a091 smartgic/ovos-skill-personal:alpha \"ovos-skill-launcher\u2026\" 19 hours ago Up 8 hours ovos_skill_personal\n219eb6254d32 smartgic/ovos-listener-dinkum:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_listener\n31f5d5e7a1ec smartgic/ovos-audio:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_audio\n05e94905b867 smartgic/ovos-core:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_core\nd256c2e7b6f3 smartgic/ovos-phal:alpha \"/bin/bash /usr/loca\u2026\" 19 hours ago Up 8 hours ovos_phal\na4db13a597a4 smartgic/ovos-phal-admin:alpha \"/bin/bash /usr/loca\u2026\" 25 hours ago Up 8 hours ovos_phal_admin\nd157740c9965 smartgic/ovos-messagebus:alpha \"/bin/bash -c ovos-m\u2026\" 25 hours ago Up 8 hours (healthy) ovos_messagebus\n6e3536dcfae5 smartgic/ovos-cli:alpha \"sleep infinity\" 25 hours ago Up 8 hours ovos_cli\n