diff --git a/getting-started/docker/installation/gui/index.html b/getting-started/docker/installation/gui/index.html index b4dd8ce..f536f9d 100644 --- a/getting-started/docker/installation/gui/index.html +++ b/getting-started/docker/installation/gui/index.html @@ -1767,7 +1767,7 @@

xhost and display servers
export DISPLAY=":0"
 xhost +local:ovos_gui
-

This 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.

+

This 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.

@@ -1796,7 +1796,7 @@

xhost and display servers[Install] WantedBy=default.target

-

Enable and start the new xhost.service Systemd service

+

Enable and start the new xhost.service systemd service.

diff --git a/search/search_index.json b/search/search_index.json index dc23651..2c33fdd 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":"Getting started","text":""},{"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":"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\n
podman exec --interactive --tty ovos_cli ovos-cli-client\n
"},{"location":"getting-started/docker/cli/#ovos-config","title":"ovos-config","text":"

To 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\n
podman exec --interactive --tty ovos_cli ovos-config show\n

vim 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\"\n
podman exec --interactive --tty ovos_cli ovos-speak \"hello world\"\n
"},{"location":"getting-started/docker/cli/#mana","title":"mana","text":"

Neon Mana (Messagebus Application for Neon AI) provides tools for interacting with the message bus.

DockerPodman 
docker exec --interactive --tty ovos_cli mana --help\n
podman exec --interactive --tty ovos_cli mana --help\n
"},{"location":"getting-started/docker/composition/","title":"Composition","text":""},{"location":"getting-started/docker/composition/#composition-and-environment-files","title":"Composition and environment files","text":"

The 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 and RENDER_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_SHARE_FOLDER ~/hivemind/share HiveMind shared directory HIVEMIND_USER hivemind User running in the container INPUT_GID 102 input group ID OVOS_CONFIG_FOLDER ~/ovos/config OVOS 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 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 on Raspberry Pi OS.

Raspberry PiLinux 
getent group gpio\ngetent group render\ngetent group video\ngetent group input\n
getent group video\ngetent group input\n
"},{"location":"getting-started/docker/composition/#how-to-get-the-uid","title":"How to get the UID?","text":"

The 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\n
echo $UID\n

XDG 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.

~/ovos/config/mycroft.conf
{\n  \"debug\": true,\n  \"log_level\": \"DEBUG\"\n}\n

Note

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\n
podman-compose --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml --env-file .env logs --follow --tail 200\n
"},{"location":"getting-started/docker/debug/#specific-contaienr-logs","title":"Specific contaienr logs","text":"

Access the logs of a specific container.

DockerPodman 
docker logs --follow --tail 200 ovos_audio\n
podman logs --follow --tail 200 ovos_audio\n
"},{"location":"getting-started/docker/debug/#run-command-in-a-container","title":"Run command in a container","text":"

Execute a command inside a container without going into it.

DockerPodman 
docker exec --tty --interactive ovos_audio pactl info\n
podman exec --tty --interactive ovos_audio pactl info\n
"},{"location":"getting-started/docker/debug/#connect-inside-a-container","title":"Connect inside a container","text":"

Go inside a container and run multiple commands (where sh is the available shell in there).

DockerPodman 
docker exec --tty --interactive ovos_audio sh\n
podman exec --tty --interactive ovos_audio sh\n
"},{"location":"getting-started/docker/debug/#configuration-syntax-check","title":"Configuration syntax check","text":"

Make 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\n

If 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\n
"},{"location":"getting-started/docker/debug/#dockerpodman-consumption","title":"Docker/Podman consumption","text":"

Get the CPU, memory and I/O consumption per container.

DockerPodman 
docker stats --all --no-trunc\n
podman stats --all --no-trunc\n
"},{"location":"getting-started/docker/debug/#dockerpodman-volume-usage","title":"Docker/Podman volume usage","text":"

Get the disk usage per volumes.

DockerPodman 
docker system df\n
podman system df\n
"},{"location":"getting-started/docker/images/","title":"Images and volumes","text":""},{"location":"getting-started/docker/images/#images","title":"Images","text":"

Pre-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.

"},{"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_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}\n

But first thing's first you need to have Open Voice OS's containers up and running. Follow the guide.

  1. 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 podmand-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\n
docker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml up --detach\n
docker compose --project-name ovos --file docker-compose.macos.yml --file docker-compose.skills.yml --env-file .env up --detach\n
docker compose --project-name ovos --file docker-compose.windows.yml --file docker-compose.skills.yml  up --detach\n

Because 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 podmand-compose.

Raspberry PiLinuxMac OSWindows WSL2 
docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml up --detach\n
docker compose --project-name ovos --file docker-compose.yml up --detach\n
docker compose --project-name ovos --file docker-compose.macos.yml --env-file .env up --detach\n
docker compose --project-name ovos --file docker-compose.windows.yml up --detach\n

Depending 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\n
podman 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
"},{"location":"getting-started/docker/installation/configuration/","title":"Configuration","text":""},{"location":"getting-started/docker/installation/configuration/#open-voice-os-configuration","title":"Open Voice OS configuration","text":"

~/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}\n
"},{"location":"getting-started/docker/installation/configuration/#configure-the-logging","title":"Configure the logging","text":"

By 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}\n

Services 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/gui/","title":"GUI","text":""},{"location":"getting-started/docker/installation/gui/#install-the-open-voice-os-gui","title":"Install the Open Voice OS GUI","text":"

Linux only

The GUI is currently only available 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 only

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 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    \"idle_display_skill\": \"skill-ovos-homescreen.openvoiceos\",\n    \"generic\": {\n      \"homescreen_supported\": true\n    },\n    \"gui_file_host_path\": \"/home/ovos/.cache/gui_files\"\n  },\n  \"websocket\": {\n    \"max_msg_size\": 100\n  }\n}\n
"},{"location":"getting-started/docker/installation/gui/#xhost-and-display-servers","title":"xhost and display servers","text":"

Tip

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\n

This 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\n
mkdir -p ~/.config/systemd/user\n

Create 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\n

Enable and start the new xhost.service Systemd service

Raspberry PiLinux 
systemctl --user enable xhost.service\nsystemctl --user start xhost.service\n
systemctl --user enable xhost.service\nsystemctl --user start xhost.service\n

The 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 podmand-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\n
docker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml --file docker-compose.gui.yml up --detach\n
"},{"location":"getting-started/docker/installation/requirements/","title":"Requirements","text":""},{"location":"getting-started/docker/installation/requirements/#final-steps-before-the-run","title":"Final steps before the run","text":"

Before 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\nmkdir -p ~/ovos/{config,share,tmp} ~/hivemind/{config,share}\nchown ${USER}:${USER} -R ~/ovos ~/hivemind\ncd ~/ovos-docker/compose\n
"},{"location":"getting-started/docker/installation/requirements/#enable-user-manager","title":"Enable user manager","text":"

Because some containers require /run/user/1000 to be mounted, systemd should be instruct to log the user during the boot process and mak/run/user/1000 directory available before the containers start.

Raspberry PiLinux 
sudo loginctl enable-linger $USER\n
sudo loginctl enable-linger $USER\n
"},{"location":"getting-started/docker/installation/requirements/#set-the-environment-file","title":"Set the environment file","text":"

.env file is a strong requirement

Please make sure to read and understand this section as if you don't 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.

.env
DISPLAY=:0\nHIVEMIND_CONFIG_FOLDER=~/hivemind/config\nHIVEMIND_SHARE_FOLDER=~/hivemind/share\nHIVEMIND_USER=hivemind\nINPUT_GID=102\nOVOS_CONFIG_FOLDER=~/ovos/config\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\n
Raspberry PiLinuxMac OSWindows WSL2 
cp .env-raspberrypi .env\n
cp .env.example .env\n
cp .env.example .env\n
cp .env.example .env\n

Examples are provided, please make sure to select the right one and to set the proper values.

"},{"location":"getting-started/docker/installation/skills/","title":"Skills","text":""},{"location":"getting-started/docker/installation/skills/#howto-install-skills","title":"Howto install skills?","text":"

Two 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.list
ovos-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\n

If 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 are 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 podmand-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\n
docker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml up --detach\n
docker compose --project-name ovos --file docker-compose.macos.yml --file docker-compose.skills.yml --env-file .env up --detach\n
docker compose --project-name ovos --file docker-compose.windows.yml --file docker-compose.skills.yml up --detach\n

Depending 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\n
podman 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\n
"},{"location":"getting-started/docker/plugins/microphone/","title":"Microphone","text":""},{"location":"getting-started/docker/plugins/microphone/#microphone-plugins","title":"Microphone plugins","text":"

A 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.list
ovos-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\n

The ovos_listener container must be restarted if a change occurs in the listener.list file.

DockerPodman 
docker restart ovos_listener\n
podman restart ovos_listener\n
"},{"location":"getting-started/docker/plugins/microphone/#which-plugin-to-choose","title":"Which plugin to choose?","text":"

Here 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 ALSA
  • ovos-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.list
ovos-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\n

The 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\n
podman restart ovos_phal ovos_phal_admin\n
"},{"location":"getting-started/docker/plugins/stt/","title":"Speech-To-Text","text":""},{"location":"getting-started/docker/plugins/stt/#speech-to-text-plugins","title":"Speech-To-Text plugins","text":"

The 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 service
  • ovos-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.list
ovos-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\n

The ovos_listener container must be restarted if a change occurs in the listener.list file.

DockerPodman 
docker restart ovos_listener\n
podman restart ovos_listener\n
"},{"location":"getting-started/docker/plugins/tts/","title":"Text-To-Speech","text":""},{"location":"getting-started/docker/plugins/tts/#text-to-speech-plugins","title":"Text-To-Speech plugins","text":"

The 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 voice
  • ovos-tts-plugin-mimic2 is the cloud based version hosted on Mycroft AI infrastructure
  • ovos-tts-plugin-mimic3-server is the latest Mycroft AI TTS engine
  • ovos-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.list
ovos-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\n

The ovos_audio container must be restarted if a change occurs in the audio.list file.

DockerPodman 
docker restart ovos_audio\n
podman restart ovos_audio\n
"},{"location":"getting-started/docker/prerequisites/cpu/","title":"CPU instructions","text":""},{"location":"getting-started/docker/prerequisites/cpu/#cpu-instructions","title":"CPU instructions","text":"

In 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\n
sysctl -a | grep -E -i --color \"avx|simd\"\n

If 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\n

Once 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)\n

The GID could differ compare to your setup.

"},{"location":"getting-started/docker/prerequisites/engine/#validation","title":"Validation","text":"DockerPodman 
docker system info\ndocker container list\n
podman system info\npodman container list\n

  1. 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\n
sudo apt install pulseaudio\n
"},{"location":"getting-started/docker/prerequisites/sound/#permissions","title":"Permissions","text":"

The 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\n
pw-cli info\n
"},{"location":"getting-started/docker/prerequisites/sound/#list-microphones","title":"List microphones","text":"

At 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\n
wpctl status | grep Audio/Source\n
"},{"location":"getting-started/docker/prerequisites/sound/#list-speakers","title":"List speakers","text":"

At 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\n
wpctl status | grep Audio/Sink\n
"},{"location":"getting-started/docker/security/hardening/","title":"System hardening","text":""},{"location":"getting-started/docker/security/hardening/#basic-ovos-hardening","title":"Basic OVOS hardening","text":"

In 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.txt
apparmor=1 security=apparmor\n
/etc/default/grub.d/apparmor.cfg
apparmor=1 security=apparmor\n

System 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\n
sudo aa-status\n
"},{"location":"getting-started/docker/security/hardening/#apparmor-docker-profile","title":"AppArmor Docker profile","text":"

AppArmor 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\n

All 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\n

ovos_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\n

This 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.

  1. 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 podmand-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\n
docker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml up --detach\n
docker compose --project-name ovos --file docker-compose.macos.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml --env-file .env up --detach\n
docker compose --project-name ovos --file docker-compose.windows.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml up --detach\n

For 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\n
podman exec --interactive --tty hivemind_cli hivemind-core --help\n

Port 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'\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
podman 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
"}]} \ No newline at end of file +{"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":"Getting started","text":""},{"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":"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\n
podman exec --interactive --tty ovos_cli ovos-cli-client\n
"},{"location":"getting-started/docker/cli/#ovos-config","title":"ovos-config","text":"

To 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\n
podman exec --interactive --tty ovos_cli ovos-config show\n

vim 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\"\n
podman exec --interactive --tty ovos_cli ovos-speak \"hello world\"\n
"},{"location":"getting-started/docker/cli/#mana","title":"mana","text":"

Neon Mana (Messagebus Application for Neon AI) provides tools for interacting with the message bus.

DockerPodman 
docker exec --interactive --tty ovos_cli mana --help\n
podman exec --interactive --tty ovos_cli mana --help\n
"},{"location":"getting-started/docker/composition/","title":"Composition","text":""},{"location":"getting-started/docker/composition/#composition-and-environment-files","title":"Composition and environment files","text":"

The 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 and RENDER_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_SHARE_FOLDER ~/hivemind/share HiveMind shared directory HIVEMIND_USER hivemind User running in the container INPUT_GID 102 input group ID OVOS_CONFIG_FOLDER ~/ovos/config OVOS 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 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 on Raspberry Pi OS.

Raspberry PiLinux 
getent group gpio\ngetent group render\ngetent group video\ngetent group input\n
getent group video\ngetent group input\n
"},{"location":"getting-started/docker/composition/#how-to-get-the-uid","title":"How to get the UID?","text":"

The 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\n
echo $UID\n

XDG 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.

~/ovos/config/mycroft.conf
{\n  \"debug\": true,\n  \"log_level\": \"DEBUG\"\n}\n

Note

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\n
podman-compose --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml --env-file .env logs --follow --tail 200\n
"},{"location":"getting-started/docker/debug/#specific-contaienr-logs","title":"Specific contaienr logs","text":"

Access the logs of a specific container.

DockerPodman 
docker logs --follow --tail 200 ovos_audio\n
podman logs --follow --tail 200 ovos_audio\n
"},{"location":"getting-started/docker/debug/#run-command-in-a-container","title":"Run command in a container","text":"

Execute a command inside a container without going into it.

DockerPodman 
docker exec --tty --interactive ovos_audio pactl info\n
podman exec --tty --interactive ovos_audio pactl info\n
"},{"location":"getting-started/docker/debug/#connect-inside-a-container","title":"Connect inside a container","text":"

Go inside a container and run multiple commands (where sh is the available shell in there).

DockerPodman 
docker exec --tty --interactive ovos_audio sh\n
podman exec --tty --interactive ovos_audio sh\n
"},{"location":"getting-started/docker/debug/#configuration-syntax-check","title":"Configuration syntax check","text":"

Make 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\n

If 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\n
"},{"location":"getting-started/docker/debug/#dockerpodman-consumption","title":"Docker/Podman consumption","text":"

Get the CPU, memory and I/O consumption per container.

DockerPodman 
docker stats --all --no-trunc\n
podman stats --all --no-trunc\n
"},{"location":"getting-started/docker/debug/#dockerpodman-volume-usage","title":"Docker/Podman volume usage","text":"

Get the disk usage per volumes.

DockerPodman 
docker system df\n
podman system df\n
"},{"location":"getting-started/docker/images/","title":"Images and volumes","text":""},{"location":"getting-started/docker/images/#images","title":"Images","text":"

Pre-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.

"},{"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_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}\n

But first thing's first you need to have Open Voice OS's containers up and running. Follow the guide.

  1. 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 podmand-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\n
docker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml up --detach\n
docker compose --project-name ovos --file docker-compose.macos.yml --file docker-compose.skills.yml --env-file .env up --detach\n
docker compose --project-name ovos --file docker-compose.windows.yml --file docker-compose.skills.yml  up --detach\n

Because 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 podmand-compose.

Raspberry PiLinuxMac OSWindows WSL2 
docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml up --detach\n
docker compose --project-name ovos --file docker-compose.yml up --detach\n
docker compose --project-name ovos --file docker-compose.macos.yml --env-file .env up --detach\n
docker compose --project-name ovos --file docker-compose.windows.yml up --detach\n

Depending 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\n
podman 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
"},{"location":"getting-started/docker/installation/configuration/","title":"Configuration","text":""},{"location":"getting-started/docker/installation/configuration/#open-voice-os-configuration","title":"Open Voice OS configuration","text":"

~/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}\n
"},{"location":"getting-started/docker/installation/configuration/#configure-the-logging","title":"Configure the logging","text":"

By 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}\n

Services 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/gui/","title":"GUI","text":""},{"location":"getting-started/docker/installation/gui/#install-the-open-voice-os-gui","title":"Install the Open Voice OS GUI","text":"

Linux only

The GUI is currently only available 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 only

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 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    \"idle_display_skill\": \"skill-ovos-homescreen.openvoiceos\",\n    \"generic\": {\n      \"homescreen_supported\": true\n    },\n    \"gui_file_host_path\": \"/home/ovos/.cache/gui_files\"\n  },\n  \"websocket\": {\n    \"max_msg_size\": 100\n  }\n}\n
"},{"location":"getting-started/docker/installation/gui/#xhost-and-display-servers","title":"xhost and display servers","text":"

Tip

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\n

This 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\n
mkdir -p ~/.config/systemd/user\n

Create 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\n

Enable and start the new xhost.service systemd service.

Raspberry PiLinux 
systemctl --user enable xhost.service\nsystemctl --user start xhost.service\n
systemctl --user enable xhost.service\nsystemctl --user start xhost.service\n

The 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 podmand-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\n
docker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml --file docker-compose.gui.yml up --detach\n
"},{"location":"getting-started/docker/installation/requirements/","title":"Requirements","text":""},{"location":"getting-started/docker/installation/requirements/#final-steps-before-the-run","title":"Final steps before the run","text":"

Before 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\nmkdir -p ~/ovos/{config,share,tmp} ~/hivemind/{config,share}\nchown ${USER}:${USER} -R ~/ovos ~/hivemind\ncd ~/ovos-docker/compose\n
"},{"location":"getting-started/docker/installation/requirements/#enable-user-manager","title":"Enable user manager","text":"

Because some containers require /run/user/1000 to be mounted, systemd should be instruct to log the user during the boot process and mak/run/user/1000 directory available before the containers start.

Raspberry PiLinux 
sudo loginctl enable-linger $USER\n
sudo loginctl enable-linger $USER\n
"},{"location":"getting-started/docker/installation/requirements/#set-the-environment-file","title":"Set the environment file","text":"

.env file is a strong requirement

Please make sure to read and understand this section as if you don't 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.

.env
DISPLAY=:0\nHIVEMIND_CONFIG_FOLDER=~/hivemind/config\nHIVEMIND_SHARE_FOLDER=~/hivemind/share\nHIVEMIND_USER=hivemind\nINPUT_GID=102\nOVOS_CONFIG_FOLDER=~/ovos/config\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\n
Raspberry PiLinuxMac OSWindows WSL2 
cp .env-raspberrypi .env\n
cp .env.example .env\n
cp .env.example .env\n
cp .env.example .env\n

Examples are provided, please make sure to select the right one and to set the proper values.

"},{"location":"getting-started/docker/installation/skills/","title":"Skills","text":""},{"location":"getting-started/docker/installation/skills/#howto-install-skills","title":"Howto install skills?","text":"

Two 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.list
ovos-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\n

If 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 are 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 podmand-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\n
docker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml up --detach\n
docker compose --project-name ovos --file docker-compose.macos.yml --file docker-compose.skills.yml --env-file .env up --detach\n
docker compose --project-name ovos --file docker-compose.windows.yml --file docker-compose.skills.yml up --detach\n

Depending 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\n
podman 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\n
"},{"location":"getting-started/docker/plugins/microphone/","title":"Microphone","text":""},{"location":"getting-started/docker/plugins/microphone/#microphone-plugins","title":"Microphone plugins","text":"

A 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.list
ovos-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\n

The ovos_listener container must be restarted if a change occurs in the listener.list file.

DockerPodman 
docker restart ovos_listener\n
podman restart ovos_listener\n
"},{"location":"getting-started/docker/plugins/microphone/#which-plugin-to-choose","title":"Which plugin to choose?","text":"

Here 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 ALSA
  • ovos-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.list
ovos-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\n

The 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\n
podman restart ovos_phal ovos_phal_admin\n
"},{"location":"getting-started/docker/plugins/stt/","title":"Speech-To-Text","text":""},{"location":"getting-started/docker/plugins/stt/#speech-to-text-plugins","title":"Speech-To-Text plugins","text":"

The 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 service
  • ovos-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.list
ovos-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\n

The ovos_listener container must be restarted if a change occurs in the listener.list file.

DockerPodman 
docker restart ovos_listener\n
podman restart ovos_listener\n
"},{"location":"getting-started/docker/plugins/tts/","title":"Text-To-Speech","text":""},{"location":"getting-started/docker/plugins/tts/#text-to-speech-plugins","title":"Text-To-Speech plugins","text":"

The 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 voice
  • ovos-tts-plugin-mimic2 is the cloud based version hosted on Mycroft AI infrastructure
  • ovos-tts-plugin-mimic3-server is the latest Mycroft AI TTS engine
  • ovos-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.list
ovos-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\n

The ovos_audio container must be restarted if a change occurs in the audio.list file.

DockerPodman 
docker restart ovos_audio\n
podman restart ovos_audio\n
"},{"location":"getting-started/docker/prerequisites/cpu/","title":"CPU instructions","text":""},{"location":"getting-started/docker/prerequisites/cpu/#cpu-instructions","title":"CPU instructions","text":"

In 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\n
sysctl -a | grep -E -i --color \"avx|simd\"\n

If 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\n

Once 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)\n

The GID could differ compare to your setup.

"},{"location":"getting-started/docker/prerequisites/engine/#validation","title":"Validation","text":"DockerPodman 
docker system info\ndocker container list\n
podman system info\npodman container list\n

  1. 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\n
sudo apt install pulseaudio\n
"},{"location":"getting-started/docker/prerequisites/sound/#permissions","title":"Permissions","text":"

The 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\n
pw-cli info\n
"},{"location":"getting-started/docker/prerequisites/sound/#list-microphones","title":"List microphones","text":"

At 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\n
wpctl status | grep Audio/Source\n
"},{"location":"getting-started/docker/prerequisites/sound/#list-speakers","title":"List speakers","text":"

At 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\n
wpctl status | grep Audio/Sink\n
"},{"location":"getting-started/docker/security/hardening/","title":"System hardening","text":""},{"location":"getting-started/docker/security/hardening/#basic-ovos-hardening","title":"Basic OVOS hardening","text":"

In 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.txt
apparmor=1 security=apparmor\n
/etc/default/grub.d/apparmor.cfg
apparmor=1 security=apparmor\n

System 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\n
sudo aa-status\n
"},{"location":"getting-started/docker/security/hardening/#apparmor-docker-profile","title":"AppArmor Docker profile","text":"

AppArmor 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\n

All 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\n

ovos_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\n

This 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.

  1. 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 podmand-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\n
docker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml up --detach\n
docker compose --project-name ovos --file docker-compose.macos.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml --env-file .env up --detach\n
docker compose --project-name ovos --file docker-compose.windows.yml --file docker-compose.skills.yml --file docker-compose.hivemind.yml up --detach\n

For 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\n
podman exec --interactive --tty hivemind_cli hivemind-core --help\n

Port 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'\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
podman 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
"}]} \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index 45c6b47..7d03613 100644 Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ