INSTALL

Commbase Installation Guide
============================

Welcome to Commbase!

Introduction
=============

Thank you for choosing Commbase! This Installation Guide will walk you through the process of installing Commbase on your system. Whether you're a first-time user or upgrading to the latest version, this guide ensures a smooth installation experience.

Content
========

1. Installation

1.1. Set up your system repository sources

1.2. Update the system

1.3. Install Commbase

1.4. Set up your new app name and directory

1.5. Set up the HISTCONTROL environment variable

1.6. Set up the Commbase executable

2. Requisites and dependencies

2.1. Choose a Python version to install

2.2. Install Python

2.3. Install Python packages

2.4. Install Python in an Anaconda Python environment

2.5. Build the Commbase Conda environment from a YAML file

2.6. Install OpenAI's Whisper

2.7. Install the required system dependency packages

2.8. Install Oh My Tmux

3. Set up the voice and language

4. Set up audio capture

4.1. Setup steps

5. Next steps

1. Installation
================

In this document, we will use Debian GNU/Linux to demonstrate the installation steps, but you can use any of your preferred distros and have the same result.

Set up your system repository sources
--------------------------------------

Add the sources contrib and non-free in the file /etc/apt/sources

$ sudo nano /etc/apt/sources

Update the system
------------------

$ sudo apt-get update

You can also upgrade it like this:

$ sudo apt-get -u upgrade

Install Commbase
-----------------

Visit: https://github.com/mydroidandi/commbase

Download or clone the repository somewhere in your home directory:

$ cd $HOME

$ git clone git@github.com:mydroidandi/commbase.git

$ unzip commbase-main.zip

Set up your new app name and directory
---------------------------------------

Go to the directory scripts/configuration/ 

You will see the file set_app_root_directory_and_app_directory.sh there.

$ bash set_app_root_directory_and_app_directory.sh

The script prompts the user to enter the current location and name of the directory they want to rename, and also to enter a new name and location for the directory. It also appends the variable COMMBASE_APP_DIR in the files $HOME/.bashrc and $HOME/.zshrc

Notes about the difference between .bashrc and .bash_profile:

.bash_profile is read and executed when Bash is invoked as an interactive login shell, while .bashrc is executed as an interactive non-login shell.

When Bash is invoked as an interactive non-login shell, it reads and executes commands from ~/.bashrc, if that file exists, and is readable.

When invoked as an interactive login shell, Bash looks for the /etc/profile file, and if the file exists, it runs the commands listed in the file. Then Bash searches for ~/.bash_profile, ~/.bash_login, and ~/.profile files, in the listed order, and executes commands from the first readable file found.

In case of that your OS distribution does not use ~/.bashrc, add manually the variable $COMMBASE_APP_DIR and its value to your Bash Startup File(s).

Set up the HISTCONTROL environment variable
--------------------------------------------

The HISTCONTROL variable determines which commands are saved in the history file. If you set it to the value "ignoreboth", any command preceded by a space character will be excluded from the history.

Commbase uses HISTCONTROL to keep clean the commands' history during the rendering of the Commbase User Interface (UI).

To set up the HISTCONTROL environment variable, run the script scripts/configuration/append_function_no_history_to_bashrc.sh:

$ cd scripts/configuration

$ bash append_function_no_history_to_bashrc.sh

$ source append_function_no_history_to_bashrc.sh

$ exit

Reopen the terminal.

Note: Do not confuse this history file .bash_history with the file history/.app_history that is mentioned in the document User's Guide.

Set up the Commbase executable
-------------------------------

Go to the directory scripts/configuration/install_commbase_executable/ and execute the file install_commbase_executable.sh:

$ cd scripts/configuration/install_commbase_executable/

$ sudo bash install_commbase_executable.sh

A new commbase file should appear in the directory /usr/bin.

$ ls /usr/bin/commbase

Do not run the commbase just command yet. Remember that the command commbase opens an enhanced tmux session named Commbase-0. To avoid duplicate instances of Commbase running on the system, you need to completely close the program before rerunning it once more. Check out the User's Guide for more details regarding this topic.

2. Requisites and dependencies
===============================

Choose a Python version to install
-----------------------------------

In the next documentation sections, we present 3 alternatives to install the Commbase Python Environment:

1. Install Python, Install Python packages.

2. Install Python in an Anaconda Python environment.

3. Build the Commbase Conda environment from a YAML file.

From those alternatives, we recommend installing Python using the third option, Build the Commbase Conda environment from a YAML file, because there is no need to create a new Commbase environment from zero, in case of systems with multiple environments setups. You recreate and install the Commbase environment, packages, and packaging dependencies all at once. Also, you do not need to edit the file config/commbase.conf constant PYTHON_ENV_VERSION="python" to define your own or custom Python version that Commbase is going to use.

For the second and third alternatives given, in case you do not have Anaconda Python in your system but still want to use it to run Commbase, you can install Anaconda Python and then read the section "Install Python in an Anaconda Python environment" to choose if you are going to create any Anaconda Python Commbase environment such as "commbase_env" yourself or build it later on as it is shown in the section "Build the Commbase Conda environment from a YAML file". After its installation, your Anaconda Python version should be capable of installing or building your commbase_env environment. Otherwise, try to install a newer or older version of Anaconda Python and verify the Python versions it can install, run, and work with. The installation of Anaconda Python is beyond the scope of this documentation. For information on how to install Anaconda Python in your operating system, visit: https://docs.anaconda.com/free/anaconda/getting-started/install/

For the first alternative, in case you want to use your systems' or any other custom Python version, edit the file config/commbase.conf line with the variable PYTHON_ENV_VERSION="python" if required.

For example:

PYTHON_ENV_VERSION="python3.12"

In that way, Commbase will attempt to run using python3.12 from your OS instead of using the Anaconda Python environment commbase_env, which has and runs its own Python version.

Python 3.12 is the minimum Python version required to run all the Commbase software properly, in the system or in a virtual environment. A Python version higher than the one used in commbase_env could affect any skill script or any custom scripts you could make. In such cases, you could keep your custom Python version or Python environment version and manage the errors by yourself.

Install Python
---------------

In this section, we added an excellent alternative to standard Python installations. However, the method to install Python is your decision at the end of the day, and that choice is not going to affect how Commbase works. After the alternative "Build Python 3.12.1 on Debian 12 Bookworm", we put a subsection "Install Python 3.7" just for reference of installations of older Python versions on an older Debian GNU/Linux distribution.

- Build Python 3.12.1 on Debian 11, 12:

Check the current version:

$ apt info python3

Info: https://www.python.org/downloads/release/python-3121/

Download and extract the Python source code:

$ cd /tmp/

$ wget https://www.python.org/ftp/python/3.12.1/Python-3.12.1.tgz

$ tar -xzvf Python-3.12.1.tgz

$ cd Python-3.12.1/

Install the build tools:

$ sudo apt update

$ sudo apt install build-essential zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libreadline-dev libffi-dev

If you are prompted to install other dependencies, select yes.

Configure, make and make install:

$ ./configure --enable-optimizations

Run make. You can make the build using nproc, which returns the number of CPUs.

$ make -j `nproc`

Make install.

The default Python installation is /usr/bin. If you want to install Python under /usr/local/bin instead of overwriting the default, do this:

$ sudo make altinstall

This will install Python at /usr/local/bin/python3.12. To test the version, run this:

$ python3.12 -V

You will get this output:

Python 3.12.1

Make Python 3.12.1 the default version.

To make the default version of Python 3.12.1, run this:

$ sudo ln -s /usr/local/bin/python

Output:

ln: failed to create symbolic link './python': File exists

$ sudo ln -s /usr/local/bin/python3.12 /usr/local/bin/python

This creates a bunch of softlinks and links the latest Python to /usr/local/bin.

Test whether Python 3.12.1 is the default version:

$ ls -al /usr/local/bin/python

Output:

lrwxrwxrwx 1 root root 25 May 11 16:52 /usr/local/bin/python -> /usr/local/bin/python3.12

$ ls -al /etc/alternatives/python

Output:

ls: cannot access '/etc/alternatives/python': No such file or directory

$ /usr/local/bin/python3.12 -V

Output:

Python 3.12.1

$ python -V

The output will be:

Python 3.12.1

So, at this point, Python 3.12.1 has been set as the default version of Python.

Verify the pip version:

$ pip -V

Output:

[...] (python 3.9)

Upgrade the pip version:

$ whereis python

$ /usr/local/bin/python3.12 -m pip install --upgrade pip

$ pip3.12 install --upgrade pip

$  whereis pip

Check the new pip version:

$ pip3.12 -V

Output:

pip: /usr/bin/pip /usr/local/bin/pip3.12 /usr/share/man/man1/pip.1.gz

From now on, you can use this new command pip3.12 to install most of your pip packages.

The command python -m pip install <PACKAGE> is used to ensure that the pip command is executed within the context of the specific Python interpreter specified by python.

In some cases, there may be multiple versions of Python installed on a system, and using python -m pip helps ensure that the correct pip module associated with the desired Python interpreter is used for package installation. This is particularly useful when you want to install packages for a specific Python version or in virtual environments.

- Install Python 3.7:

$ whereis python3.7

$ sudo apt-get update

$ apt-cache search python 3.7

$ sudo apt-get install python3.7

pip3.7:

$ /usr/bin/python3 -m pip install --upgrade pip

$ /usr/bin/python3.7 -m pip install --upgrade pip

Prints a list of installed pip packages:

$ pip list | more

$ pip3 list | more

$ pip3.7 list | more

Install many pip versions will allow you to choose a package version using the pip version. For example:

$ pip install subprocess.run

Or:

$ pip3 install subprocess.run

Install Python packages
------------------------

- Portaudio:

PyAudio requires Portaudio19 to install:

More information here: https://packages.debian.org/bullseye/portaudio19-dev

$ sudo apt-get update

$ apt-cache search portaudio

$ sudo apt-get install portaudio19-dev portaudio19-doc

- PyAudio:

PyAudio requires python3-pyaudio to install:

$ sudo apt install python3-pyaudio

More information here: https://pypi.org/project/PyAudio/

$ pip3.12 install pyaudio

- Subprocess.run:

More information here: https://pypi.org/project/subprocess.run/

$ pip3.12 install subprocess.run

- Sounddevice:

This package allows us to run test_microphone.py

$ pip3.12 install sounddevice

- Chardet:

$ pip3.12 install chardet

- Scikit-learn and scikit-learn-intelex (this last is optional):

$ pip3.12 install scikit-learn scikit-learn-intelex

- OpenCV:

It must be installed as Python package and also as a system package.

To install the Python OpenCV package:

$ pip3.12 install opencv-python

Steps to install OpenCV in Debian 11, 12:

Verify the current Debian version (The version limits the higher version that you can install of any package name):

$ cat /etc/issue

Verify the current Python version:

$ python -V

Update the sources list for the official Debian repos:

$ sudo apt-get update

Search the package in the official Debian repos (main):

$ apt-cache search opencv

Show the package version information:

$ apt-cache show python3-opencv

Install the package:

$ sudo apt-get install python3-opencv

Verify the package installation:

$ dpkg -l | grep opencv

- openai:

$ pip3.12 install openai

- aiohttp-cors

$ pip3.12 install aiohttp-cors

- typer:

$ pip3.12 install typer

- rich:

$ pip3.12 install rich

- cchardet:

This is giving an error and was installed using pip3 instead of pip3.12, as follows:

$ pip3 install cchardet

- SpeechRecognition:

$ pip3.12 install SpeechRecognition

- ffmpeg:

$ pip3.12 install ffmpeg

It requires the package ffmpeg. Install it like this:

$ sudo apt-get install ffmpeg

- flask:

$ pip3.12 install flask

- flask-cors:

$ pip3.12 install flask-cors

- flask-socketio:

$ pip3.12 install flask-socketio

- requests:

$ pip3.12 install requests

- simple-websocket:

$ pip3.12 install simple-websocket

- schedule:

$ pip3.12 install schedule

- pyttsx3:

$ pip3.12 install pyttsx3

- pydub:

$ pip3.12 install pydub

It requires the packages ffmpeg and python3-pydub. Install python3-pydub like this:

$ sudo apt-get install python3-pydub

- pytesseract:

$ pip3.12 install pytesseract

It requires the package tesseract-ocr. Install it like this:

$ sudo apt-get install tesseract-ocr

- pytest:

$ pip3.12 install pytest

Install Python in an Anaconda Python environment
-------------------------------------------------

With this alternative, you can skip using your current system Python (for example, Python 3.11) by installing 3.12 in an Anaconda Python environment for Commbase. Anaconda Python includes some well-optimized Python packages, so the speech recognition AI is supposed to work faster with Anaconda Python than with the official running Python. However, everything depends on many factors, such as package versions and system resource availability.

More information on Anaconda: https://www.anaconda.com/

After the installation of Anaconda Python, you should see the string "(base)" in the foobar.

If your system has a single Python installation using Anaconda Python, and it is set up to run only in the Bash shell, you must enter the Bash shell before starting Commbase, anaconda-navigator, or any other Python script/program that cannot start with the current Python runtime preinstalled within your Operating System distribution.

Example of foobar before entering Bash:

USER-NAME@HOSTNAME:~$ bash

Example of foobar with Anaconda Python, identified by the string "(base)", after entering Bash:

(base) USER-NAME@HOSTNAME:~$

To install PyPi-like packages in the (base) in Anaconda Python, use the command "conda":

(base) USER-NAME@HOSTNAME:~$ conda install PACKAGE-NAME

If you want to create a new Anaconda Python (3.12.1) environment just for Commbase, you can use the default name commbase_env or customize it in the configuration file config/commbase.conf:

CONDA_ENV_NAME_IF_EXISTS="commbase_env"

To create the environment using the default name commbase_env do:

$ conda create -n commbase_env python=3.12.1

$ conda activate commbase_env

Now, (commbase_env) appears in the foobar.

Within the Anaconda Python environment "commbase_env" you can install Conda packages, instead of, for example, pip packages. Examples:

Install OpenCV version 4.6.0 whether available from the defaults channel to a particular Anaconda Python environment:

(commbase_env) $ conda install -c defaults opencv=4.6.0

Install the latest version of OpenCV, available from the conda-forge channel:

(commbase_env) $ conda conda-forge -c defaults opencv

Alternatively, to install PyPi-like packages in the (commbase_env) environment in Anaconda Python, use the command "pip", for example:

(commbase_env) $ pip install ipython

To verify the package was installed, in your terminal window or an Anaconda Python prompt, run:

(commbase_env) $ conda list | more

(commbase_env) $ conda list | grep ipython

To deactivate the current environment and go back to (base) use:

(commbase_env) $ conda deactivate

To deactivate any environment, use "deactivate" from another environment:

(base) $ conda deactivate commbase_env

$ conda deactivate base

Verify the Anaconda Python's Python version used:

(base) $ python --version

Build the Commbase Conda environment from a YAML file
------------------------------------------------------

Using YAML files is the simplest and probably the best way to install Python and the Python Commbase environment dependencies.
To simplify it even more, we put all together in a script you can run once.

If you want to remove a previous Commbase environment, if the environment you want to remove is the current active environment, deactivate it before running the script.

(commbase_env) $ conda deactivate

Run the config script:

$ bash scripts/configuration/build_conda_environment.sh

The script will remove any existent environment called commbase_env, recreate it and install it from the beginning using the file commbase_env.yaml in one step.

If your installation gets stuck when it is time to install the group of packages using pip (conda pip), do the following:

Press Ctrl + c to exit the installation. You will see a message like:

Installing pip dependencies: | failed

Preserve the portion of the environment packages already installed.

Verify the current status of the packages list:

$ conda activate commbase_env

Verify that there are conda packages but there are not pypi packages in the column that corresponds to the channel pypi.

$ conda list

$ conda list | grep pypi

Proceed to install OpenAI Whisper by following the steps of "To install Whisper for the Anaconda Python environment commbase_env:" in the section Install OpenAI's Whisper of this document.

Verify that Whisper is installed properly.

$ conda list | grep openai-whisper

Install the rest pip packages, individually, within the commmbase_env environment.

$ pip install daal

$ pip install daal4py

$ pip install opencv-python

$ pip install packaging

$ pip install pillow

$ pip install pyaudio

$ pip install pydub

$ pip install pytesseract

$ pip install pyttsx3

$ pip install schedule

$ pip install scikit-learn-intelex

$ pip install simple-websocket

$ pip install sounddevice

$ pip install speechrecognition

$ pip install subprocess-run

$ pip install tbb

$ pip install wsproto

Verify the new installed pypi packages in the conda environment:

$ conda list | grep pypi

And to count packages, you can use:

$ cat commbase_env.yaml | grep -v -e "channels:" -e "dependencies:" -e "- defaults" -e "pip:" -e "name: commbase_env" | wc -l

$ conda list | grep -v -e "#" | wc -l

The count of packages in your resultant commbase_env environment must be equal to the count of the file commbase_env.yaml packaged with Commbase.

Install OpenAI's Whisper
-------------------------

Install Whisper using a specific Git version tag. Replace <tag_name> with the actual tag name in git+https://github.com/openai/whisper.git@<tag_name>.

To install Whisper for Python:

$ pip3.12 install git+https://github.com/openai/whisper.git@v20231117

If you have already installed Whisper for Python, but want to change to the Anaconda Python environment alternative, uninstall Whisper for Python and then then install it for the Anaconda environment:

$ pip3.12 list | grep  openai-whisper

$ pip3.12 uninstall openai-whisper

To install Whisper for the Anaconda Python environment commbase_env:

In an Anaconda Python environment, Whisper must be installed from its GitHub repository using pip. It should not be installed from the default Anaconda channel or the Python Package Index (PyPI, the Cheese Shop). This should be done after recreating the Commbase environment.

First, uninstall Whisper from the Anaconda Python's environment (this is just to remove the package listed in the commbase_env.yaml that comes with Commbase):

$ conda activate commbase_env

(commbase_env) $ conda uninstall openai-whisper

This will properly handle dependencies and remove the package along with its dependencies managed by Conda.

If you use 'pip uninstall package', it might not be aware of the dependencies managed by Conda, and you could potentially leave behind orphaned files or dependencies.

To maintain consistency and avoid potential issues, it's best to stick with the package manager used for installation when uninstalling.

Second, verify the list of packages in the Commbase environment file:

(commbase_env) $ cat commbase_env.yaml | grep whisper

Or use:

(commbase_env) $ conda list | grep openai-whisper

Third, install Whisper using the conda pip.

(commbase_env) $ pip install git+https://github.com/openai/whisper.git@v20231117

Install the required system dependency packages
------------------------------------------------

The names of the packages or the names of the commands mentioned in this section could change from OS distribution to distribution, or even from release to release.

In Debian, the DPKG packages that contain all the required commands can be installed using APT. APT manages and installs the package dependencies automatically.

List of required packages/commands:

- alsa-utils:

It contains the tools alsamixer and aplay.

In Debian-based systems, including Debian itself and its derivatives like Ubuntu, the alsa-utils package typically provides the arecord command.

- bash.

- bc.

- cpulimit.

- curl.

- dash:

It contains the sh command.

- espeak:

Espeak is an alternative to Festival and is required by pyttsx3 on Linux.

- festival.

- ffmpeg.

- figlet.

- gawk.

- gdebi.

- gnome-terminal:

Actually, it can be any of these Linux terminals: gnome-terminal, konsole, lxterminal, kitty, alacritty, wezterm, xterm, lxterm.

Note: More terminals can be added in the file src/client_skill.sh.

- git.

- jq.

- mpv.

- mplayer.

- netcat-traditional.

It contains the nc command.

- nmap.

- openssh-client.

The scp command is part of the OpenSSH package.

- openssh-server.

- openssl.

- portaudio19-dev:

It is seen in the section of PyAudio.

- procps.

It includes the command pkill.

- pulseaudio:

Some Linux configurations, such as the Gnome desktop environment, currently use Pipewire instead of PulseAudio by default. Commbase can normally be used with Pipewire or PulseAudio or both.

Install pulseaudio. This is required to have pactl available:

$ sudo apt-get install pulseaudio

pactl, which is the command-line interface for the PulseAudio sound server, can typically interact with devices managed by PipeWire. This interoperability is because PipeWire is designed to be compatible with PulseAudio APIs and commands, allowing tools like pactl to work with both PulseAudio and PipeWire.

However, it's essential to note that while pactl can often interact with PipeWire devices, there might be some limitations or differences in behavior compared to using it with PulseAudio directly.

In case you want to use Pipewire instead of PulseAudio, install Pipewire like this:

$ sudo apt-get install pipewire

You can have both PulseAudio and PipeWire installed on the same system. They can coexist, and you can choose which one to use as the default audio server based on your preferences or requirements.

If you want PipeWire to work with applications that rely on PulseAudio, you may want to install the PulseAudio compatibility layer for PipeWire:

$ sudo apt-get install pipewire-pulse

To determine whether your system is using PipeWire or PulseAudio:

$ pactl info | grep "Server Name"

To determine whether your system is using PipeWire or ALSA as the default audio server, you can check the status of the PipeWire service and ALSA Mixer.

For PipeWire, you can check if the PipeWire service is running:

$ systemctl --user restart pipewire

$ systemctl --user status pipewire

If the service is not working yet, this could require a system reboot.

$ systemctl reboot

For ALSA, you can check the status of the ALSA service or mixer. Note that ALSA doesn't have a centralized service like PipeWire or PulseAudio, but you can check the status of ALSA services or utilities:

$ sudo alsactl restore

This command restores the settings of the ALSA soundcard.

Additionally, you can check the ALSA Mixer settings:

$ alsamixer

- python3-opencv:

It is seen in the installation of OpenCV.

- rsync.

- sed.

- sox:

It includes the command play.

- sudo

- tar.

- tasksel:

Debian specific, optional.

- tesseract-ocr.

- tmux.

- unzip.

- uuid-runtime.

- wget.

- xbindkeys:

It is similar to xmodmap.

Install these packages from the official repositories for your distro. In summary, for Debian it would be like this:

$ sudo apt-get update; sudo apt-get install alsa-utils bash bc cpulimit curl dash espeak festival ffmpeg figlet gawk gdebi git jq mpv mplayer nmap openssh-client openssh-server openssl portaudio19-dev procps pulseaudio python3-opencv rsync sed sox sudo tar tasksel tesseract-ocr tmux unzip uuid-runtime wget xbindkeys

$ sudo apt-get install pipewire pipewire-pulse

$ sudo apt-get install gnome-terminal

Troubleshooting the package installation:

Packages unfound by their given names can be replaced in the source by their respective command line versions for your favorite OS distribution.

To verify that the command of a package is already in the system, type in the command and then press enter. For example:

$ awk

If you can list the command, it means that the application is installed.

If you want to know which alternative is currently set in case of meta-packages with more than one alternative, for example, awk:

$ update-alternatives --list awk

To change the alternative, use:

$ update-alternatives --config awk

Package Names and commands should be verified after the Commbase installation, during the Commbase configuration. To verify packages, you can use:

$ whereis <PACKAGE>

$ whereis <COMMAND>.

To verify that a package is present in the system:

$ dpkg -l | grep <PACKAGE-NAME>

Example:

$ dpkg -l | grep bash

To search for a particular package name or string in the official Debian repositories, considering that config file /etc/apt/sources.list includes the repositories "main", "contrib", and "non-free", use apt-cache, for example:

$ apt-cache search dash | grep "dash"

Install Oh My Tmux
-------------------

Clone it from GitHub and install it:

$ cd

$ git clone https://github.com/gpakosz/.tmux.git

$ ln -s -f .tmux/.tmux.conf

$ cp .tmux/.tmux.conf.local .


3. Set up the voice and language
=================================

When setting up the voice and language, you must consider the availability of the language in all the Commbase modules involved. The STT engine language, the TTS engine language, the LLMs used, the Commbase discourses and your Commbase app discourses must match the user language to make the system work properly. This step is necessary due to the complexity of the process, which involves configuring and fine-tuning the voice and language settings to align with your specific requirements and preferences.

Commbase's voice and language are set to en_us, English from the United States, by default. You will find the list of supported languages in the file: assets/docs/Supported_languages.md. Users can request additional languages through the official Commbase repository on GitHub, https://github.com/mydroidandi/commbase. Contributions to language support are also welcomed. Commbase app programmers might change their application's voice, language, and discourses to meet its requirements.

The word "discourse" can have several meanings depending on the context in which it is used. A list of types of discourse that can be hard-coded for Commbase apps are: answers, greetings, instructions, introductions, jokes, phrases, questions, quotations, speeches, statements, and talks.

In this section, you will overwrite en_us as the default voice and language.

Proceed with the default voice configuration like this:

Find out the index for the default TTS engine language setup, This TTS engine is commbase-tts-pyttsx3. It supports many languages and dialects, but the one you need is en_us for the assistant to sound like a speaker of English from the United States.

First, start Commbase:

$ commbase start

Then run the Commbase command to list all the voices available for the default TTS pyttsx3 in your very system.

$ commbase --list-pyttsx3-voices

By sending the output of the command to grep, it will output the details of voices where the name contains the string "english" including ID, Name, Languages, Gender, Age, and Index.

$ commbase --list-pyttsx3-voices | $COMMBASE_APP_DIR/bundles/libcommbase/libcommbase/routines/filter_pyttsx3_voices_by_language.sh english

There is also a command simplified for English:

$ commbase --filter-pyttsx3-english-voices

The command opens a list of all the English dialects. Scroll down the list until you find out the index for en_us English, and remember its number. Example:

Name: english-us
Languages: [b'\x02en-us']
Gender: male
Age: None
Index: 18

Open the configuration file config/commbase.conf.

$ nano config/commbase.conf

Find out the next voice variable:

TTS_PYTTSX3_LANGUAGE_INDEX="17"

Update the variable to the index number previously found.

Save the file changes.

Your Commbase assistant voice is set up.

Now, proceed with the default language configuration like this:

Run the script scripts/configuration/set_language.sh

Set the new language code to one of the codes available, for example, en_us.


4. Set up audio capture
========================

There are different ways to capture human voice and process it.

Leveraging Whisper in the context of a Speech-to-Text engine can contribute to the success by offering high accuracy, generalization across languages and accents, immediate performance, support from OpenAI, and the potential for ongoing improvements. These aspects can collectively help in overcoming some of the challenges associated with a high learning curve in STT applications.

Commbase bundles two Whisper-based STT engines to choose from: commbase-stt-whisper-proactive-p and commbase-stt-whisper-reactive-p. It is possible to keep an only STT engine or switch from one engine to another during the execution of the system, so every STT engine can be considered a mode, but that depends on your application design and configuration. Programmers are allowed to modify the code or fork entire engine repositories to create custom STT engine versions to suit specific use cases.

Every Commbase STT engine has its advantages and disadvantages.

The proactive STT engine continuously changes among 4 strokes: listening, active, processing, and stopped, which makes it more suitable for talkative devices that do not stop capturing and processing sound in time, for example, specific droids and robots. Its learning curve is higher compared to the simplified use of a rec button for the reactive STT engine. It has a customizable countdown timer to ensure that the engine takes pauses when the user is not using it, for saving system resources like power and GPU. This STT engine experience can be improved by hardware, for example: LED lightning, sounds, and other signals for the user. This mode can be considered insecure in the sense that anybody can tell your app voice commands at any time, including commands to turn off Commbase, reload STT engines, change language, and so on, unless you disable or program critical commands and skills to ask for user intervention before start running.

The reactive STT engine requires the Commbase application to be actively open in the foreground and in focus. There is a keybinding you can set up to be able to send requests to the application running in the background, unfocused, without using a keyboard key (the information is in the User's Guide, in the section "4 Set Up Microphones and Audio Keybindings"). There is also an alternative setup that involves configuring the recorder-transmitter script reccomm.sh on a remote host. It's worth noting that this host isn't confined to being a traditional computer; it can also be, for example, an Android smartphone or a Raspberry Pi equipped with Wi-Fi. This mode can be considered secure by default, compared to the proactive mode, as users can select appropriate time windows to issue voice commands without disrupting Commbase's functionality with external noises or invalid commands spoken to the app by others within its active listening radio.

You will find more information about both STT engines in the User's Guide.

In this section, we are going to set up the audio for the reactive STT engine, which is the default. Its installation required to follow some steps, but you end up with a recorder-transmitter application that you use to start/stop capturing and processing sound by pressing a programmable keyboard key.

This method provides total control on the voice messaging sent to your application for processing, besides enhancing security and GPU usage management. This method allows users to send messages from another host to your application host, wirelessly and over the networks, without requiring to manufacture specific hardware like remotes, etc.

There are other ways to get your app remotely controlled with the reactive STT engine. One of the simplest, consists of using a Bluetooth keyboard instead of a wired keyboard.

You can also use a macro pad or make your own macro pad for your project, wired or wireless. A macro pad is a small programmable keypad that allows users to assign custom functions or macros to each key.

The reactive engine is the recommended STT to get started with Commbase and also for programmers to create their application skills.

Setup steps
------------

Follow the first 2 steps if you are going to use a separate host as the remote recorder-trasmitter:

1. Have a copy of the file bundles/commbase-recorder-transmitter-b/reccomm.sh or bundles/commbase-recorder-transmitter-s/reccomm.sh in the host that is going to work as remote for Commbase. You do not need the complete Commbase repo there if the host is going to work only as the remote recorder-transmitter.

2. Install the script as executable in the host that is going to work as remote for Commbase:

$ cd /usr/bin

For a device with Bash, do:

$ sudo ln -s /path/to/commbase/bundles/commbase-recorder-transmitter-b/reccomm.sh ./reccomm

For a device with Shell, as root user, do:

# ln -s /path/to/commbase/bundles/commbase-recorder-transmitter-s/reccomm.sh ./reccomm

The next steps are for both options: two hosts, one working as a remote, or a single host working as a locally installed remote and Commbase application:

3. Set the value of the variable REMOTE_HOST to the host that runs Commbase or Commbase client. If installing in the localhost, use the localhost IP address:

REMOTE_HOST="commbase@127.0.0.1"

4. Set the value of the variable DEST_PATH. Its value should be the path to send FILENAME="recording.wav" to in the host that is going to work as Commbase or Commbase client.

DEST_PATH="/home/<your_user_home>/commbase/bundles/commbase-stt-whisper-reactive-p/client_data/recording.wav"

5. Set the audio capture variables:

AUDIO_CAPTURE_DEVICE:

Example:

AUDIO_CAPTURE_DEVICE="hw:CARD=Microphone,DEV=0"

To find out the audio capture, list the available audio capture (recording) devices and their corresponding configurations with the next command:
$ arecord -L

Then select the input device parameter based on the output, for example:

 hw:CARD=Device_0,DEV=0
     USB Audio Device, USB Audio
     Direct hardware device without any conversions
     ...
 Hw:CARD=Device_1,DEV=0
     USB Audio Device, USB Audio 1
     Direct hardware device without any conversions
     ...

CARD_INDEX:

This variable is exclusively found in the commbase-recorder-transmitter-b/reccomm.sh file.

To obtain your card index, use the following command:

$ cat /proc/asound/cards

Look for the index of the card with a microphone (The same of the variable AUDIO_CAPTURE_DEVICE)

Example:

CARD_INDEX="0"

DEVICE_INDEX:

This variable is exclusively found in the commbase-recorder-transmitter-b/reccomm.sh file.

To obtain your device index, use the following command:

$ arecord -L

Example:

DEVICE_INDEX="0"

Checking Device Status:

If you want to verify which devices are in use, meaning those recording at the moment, you can use the following command to obtain a list of busy devices:

$ lsof /dev/snd/*

6. Setup the SSH connection from the ssh client (the host that is going to work as a remote for Commbase) to the ssh server host (the host that is going to work as Commbase or Commbase client) using the appropriate IP address. If installing in the localhost, use the localhost IP address:

$ ssh 127.0.0.1

7. To avoid entering the password every time scp is executed, you can use SSH keys for authentication. Here's how you can set it up:

7.1. Generate SSH Key Pair (if not already done).

Run the following command on the machine where the script is running:

$ ssh-keygen -t rsa

Press Enter for each prompt to use the default values (empty passphrase).

7.2. Copy Public Key to Remote Host.

Copy the public key to the remote host (the host with the Commbase application) by running:

$ ssh-copy-id commbase@127.0.0.1

If ssh-copy-id is not available on your system, you can manually copy the contents of the public key (~/.ssh/id_rsa.pub) to the remote host's ~/.ssh/authorized_keys file.

7.3. Ensure Proper Permissions on Remote Host.

Make sure the ~/.ssh directory on the remote host has the correct permissions:

$ chmod 700 ~/.ssh

$ chmod 600 ~/.ssh/authorized_keys

Now, when your script uses scp, it should not prompt for a password.

7.4. Additionally, you may want to check the following:

Ensure that the user running the script has the correct permissions to read the private key file (typically ~/.ssh/id_rsa).

Verify that the script is executed by the same user who owns the SSH key pair.

By setting up SSH key authentication, you should be able to perform passwordless scp transfers.

8. Verify that you can exit the recorder and then come back to it, in the host running Commbase:

Run Commbase for a first time:

$ commbase start

When you see the message "Press 'c' to start/stop recording: " on the down right pane, press 'q' to quit, and once in the terminal (the Commbase terminal), run the next command to enter the recorder again:

$ commbase recorder

If the recorder works, you can move on to the next section. To stop Commbase:

Press 'q' to return to the terminal.

$ commbase stop

5. Next steps
==============

If everything went well, now you can run the next command in a terminal to start the program:

$ commbase start

At this point, Commbase is ready to receive Commbase voice commands and Commbase terminal commands to assist you.

Verify that the microphone is open and tell Commbase to introduce himself/herself.

Say: "tell me about yourself"

Optionally, type the command in the terminal:

$ commbase "tell me about yourself"

The output should be the Commbase introduction.

From here, you can program new custom skills to customize your voice assistant or to create J.A.R.V.I.S. from Iron Man.

Check out the document User's Guide in the directory assets/docs/ for a complete list of options.