PREFACE: This piece of software used to be called xbmcvc, because the software it was controlling was called XBMC back in the days. However, XBMC was renamed to Kodi in August 2014 and thus I decided to change the name of my program to kodivc, in an effort to steer away from legacy naming. In this document, unless explicitly stated otherwise, the names Kodi and XBMC (and their derivatives) can be used interchangeably. I am nevertheless sticking with Kodi to keep things up-to-date.

kodivc

kodivc is a program for controlling Kodi with simple voice commands. It uses CMU Sphinx for speech recognition.

Requirements

To use kodivc, the following libraries need to be installed on your system:

• pocketsphinx (version 0.6 or newer) along with its prerequisite, sphinxbase (both available at CMU Sphinx downloads)
• libcurl (shipped with cURL, should be present on most systems; if that's not your case, go to the libcurl homepage)

For kodivc to work, you need a Kodi version which supports JSON-RPC API version 3 or higher, which means any pre-11.0 (pre-Eden) or newer version should work. Older releases (including Dharma) are not supported.

Installation

Using PPA

NOTE: This installation method is only available for KodiBuntu, XBMCbuntu Gotham and Ubuntu versions 14.04 (Trusty Tahr) and newer.

You can install the latest version of kodivc by accessing your Kodi box:

• using a local console (press CTRL+ALT+F1 to switch from graphical mode to text mode; press CTRL+ALT+F7 to return to graphical mode)

• remotely, using SSH

and issuing the following commands:

sudo add-apt-repository -y universe
sudo add-apt-repository -y ppa:kempniu/kodivc
sudo apt-get update
sudo apt-get -y install kodivc

NOTE: Official pocketsphinx packages for Ubuntu 14.04 and newer are compiled with PulseAudio support enabled and ALSA support disabled. However, neither KodiBuntu nor XBMCbuntu use PulseAudio by default. To test kodivc with KodiBuntu or XBMCbuntu Gotham, you have to install and start PulseAudio. Here is a quick-and-dirty way to do it (for your own good, please don't do this on a system installed on a hard disk):

sudo rm -f /etc/apt/preferences.d/{libasound2-plugins,pulseaudio}.pref
sudo apt-get -y install pulseaudio
# for KodiBuntu
DISPLAY=:0 sudo -u kodi pulseaudio &
# for XBMCbuntu Gotham
DISPLAY=:0 sudo -u xbmc pulseaudio &

If you install KodiBuntu / XBMCbuntu Gotham on a hard disk, you'll have to properly configure PulseAudio and then configure Kodi to use PulseAudio as its sound sink (this is outside the scope of this document, but the Kodi wiki has some useful information).

Using Git

git clone https://github.com/kempniu/kodivc
cd kodivc
make
make install

NOTE: the user running kodivc should be allowed to access your sound card. On the Gentoo distribution, for instance, this is achieved by adding the user to the audio group.

Configuring Kodi

kodivc uses JSON-RPC via HTTP for passing commands to Kodi. In order for this to work, you need to go to the proper settings page in Kodi and turn on Allow remote control via HTTP (Allow control of Kodi via HTTP in Helix, Allow control of XBMC via HTTP in Gotham and older versions):

• in Eden, you'll find it under System -> Settings -> Network -> Services
• in Frodo and newer versions, you'll find it under System -> Settings -> Services -> Webserver

If you want to control your Kodi instance from another machine, make sure you also turn on Allow remote control by programs on other systems (Allow programs on other systems to control Kodi in Helix, Allow programs on other systems to control XBMC in Gotham and older versions):

• in Eden, you'll find it under System -> Settings -> Network -> Services
• in Frodo and newer versions, you'll find it under System -> Settings -> Services -> Remote control

NOTE: for the above settings to be available in Gotham and newer versions, the current settings level has to be at least Standard.

Usage

After a successful installation, you should be able to run kodivc by executing:

kodivc

At startup, kodivc will initialize the speech recognition library and, after successfully self-calibrating to properly tell silence and speech apart, it will start listening to your commands - if everything went fine, you should get the Ready for listening! message. From the moment you get that message just speak to the microphone (see below for valid commands) - that is all it takes to use the program.

If you are trying to control a Kodi instance installed on a different machine than the one you're running kodivc on (or your Kodi listens on a non-standard port), pass the correct hostname and port number to kodivc via the -H and -P command line switches, respectively. If you have set a username and a password for JSON-RPC in Kodi, pass them to kodivc via the -u and -p command line switches, respectively.

By default, kodivc will try to capture speech from the default audio device. If that doesn't work for you, you can specify the audio device you want to capture speech from using the -D command line switch.

By default, though only when controlling Kodi version 12 (Frodo) or newer, kodivc will display GUI notifications when it hears commands or changes its mode of operation. This behavior can be disabled by using the -n command line switch.

Please consult the usage message (run kodivc with the -h switch to view it) for an explanation of other command line switches.

Reading further, you'll come across the term "batch". kodivc listens to commands in batches. A batch starts when you start speaking and ends once a long enough period of silence has been detected. Every batch is reported on the command line, with a line like:

Heard: "COMMAND1 COMMAND2 ... COMMANDn"

Running in daemon mode

kodivc can also run in the background (in so called daemon mode) so that you don't have to have a terminal open to use it. To enable daemon mode, run kodivc with the -d command line switch. Note that when enabling the daemon mode, you'll almost certainly want to enable logging (using the -L command line switch) to a file or to syslog (check the usage message for details) to be able to read the messages output by kodivc. To cleanly shutdown the daemon, send a SIGINT signal to it. Another command line option that comes in handy when using daemon mode is the -r option which enables you to specify a file in which kodivc will save its PID after starting.

Locking

By default, kodivc locks itself after initializing to prevent accidental usage. Say "KODI" to unlock. This has to be the first command in a batch in order to work. Whatever you say afterwards will be executed immediately after unlocking. To lock kodivc, say "OKAY". The locking/unlocking feature can be disabled using the -l command line switch.

Normal mode

kodivc always starts in normal mode. This is the mode you'll probably use the most. Valid commands are:

Navigation commands

• UPWARDS
• DOWNWARDS
• LEFT
• RIGHT
• SELECT
• BACK
• HOME
• CONTEXT*
• WEATHER*
• PICTURES*
• TV*
• VIDEOS*
• MUSIC*
• PROGRAMS*
• SETTINGS*
• FAVORITES*

NOTE: Commands marked with an asterisk (*) are only available in Kodi 12 (Frodo) onwards.

Player commands

• PLAY
• PAUSE
• STOP
• MENU*
• PREVIOUS
• NEXT
• SHUFFLE
• UNSHUFFLE
• REPEAT [ ALL | ONE | OFF ]

NOTE: Commands marked with an asterisk (*) are only available in Kodi 12 (Frodo) onwards.

NOTE: In Kodi 12 (Frodo) onwards you can also say REPEAT without an argument to cycle through available modes.

Volume commands

• VOLUME [ TEN | TWENTY | THIRTY | FORTY | FIFTY | SIXTY | SEVENTY | EIGHTY | NINETY | MAX ]
• MUTE
• UNMUTE

Command repetition

Some commands can be executed multiple times by using one of the following multiplier commands:

• TWO
• THREE
• FOUR
• FIVE

Below is an exhaustive list of commands which can be used with a multiplier:

• UPWARDS
• DOWNWARDS
• LEFT
• RIGHT
• NEXT
• PREVIOUS

To use a multiplier, say it after the command, e.g. "NEXT FOUR" will skip four items ahead, "DOWNWARDS THREE RIGHT FIVE" will go down three times and then right five times etc.

Spelling mode (Frodo onwards only)

You can use the spelling mode to input letters and digits, e.g. when performing a search, renaming a movie/album etc. - generally when Kodi displays the onscreen keyboard. Please note, though, that kodivc will not switch to the spelling mode automatically. To enable the spelling mode, say "SPELL" while in normal mode. Switching back to normal mode is possible using three different commands:

• ACCEPT - closes the onscreen keyboard, accepting the provided input (similar to pressing the ENTER key)
• CANCEL - closes the onscreen keyboard, dismissing the provided input (similar to pressing the ESC key)
• NORMAL - switches to normal mode without closing the onscreen keyboard; this is useful if you want to input special characters which don't have a kodivc command counterpart

NOTE: Every mode switching command has to be the only command in a batch in order to work.

NOTE: The input field is automatically cleared whenever you enter the spelling mode. (Remember that when you initially spell some letters, then switch to normal mode to enter some fancy characters and then try to switch back to spelling mode.)

Letters

kodivc uses the NATO phonetic alphabet for spelling. The reason for that is that single letter recognition is very inaccurate, which shouldn't come as much of a surprise (how often do you spell your surname over the phone and people at the other end get it wrong?). NATO phonetic alphabet usage enables pocketsphinx to recognize the desired letters with much better accuracy. Here is a complete list of letter-related commands:

• ALPHA
• BRAVO
• CHARLIE
• DELTA
• ECHO
• FOXTROT
• GOLF
• HOTEL
• INDIA
• JULIET
• KILO
• LIMA
• MIKE
• NOVEMBER
• OSCAR
• PAPA
• QUEBEC
• ROMEO
• SIERRA
• TANGO
• UNIFORM
• VICTOR
• WHISKEY
• X-RAY
• YANKEE
• ZULU

Digits

• ZERO
• ONE
• TWO
• THREE
• FOUR
• FIVE
• SIX
• SEVEN
• EIGHT
• NINE

Other characters

• COLON
• COMMA
• DOT
• HYPHEN
• SPACE

Special commands

• CLEAR - clears the input field; this has to be the only command in a batch in order to work
• LOWER - switch to lower case input
• UPPER - switch to upper case input

Troubleshooting

• If you get the Ready for listening! message but nothing you say to the microphone results in a Heard: "COMMAND" type of line appearing, try the test mode: start kodivc with the -t command line switch, then enter space-separated commands in ALL CAPS, ending a batch by pressing ENTER. Example:

  LEFT TWO SELECT<ENTER>
  

  You'll probably also want to disable locking for testing, so add the -l switch to the command line as well.

  If your Kodi instance properly responds to commands entered in test mode, but doesn't react to anything you say, these are the most common causes of problems:

  • capturing from the wrong device,
  • capture levels set too low, too high (yes, overly high sensitivity is also a problem) or muted,
  • speaking too quietly.

• If after starting kodivc you see a series of odd lines among the normal ones, like below:

  Initializing, please wait...
   256x13 256x13 256x13
   256x13 256x13 256x13
  Ready for listening!
  

  just ignore them. It's a known issue with pocketsphinx 0.6. These lines shouldn't appear when using pocketsphinx 0.7 or newer.

• If after starting kodivc you get a Failed to open audio device message, you are probably facing one of two issues:

  • you're using a version of pocketsphinx which uses the PulseAudio backend, but PulseAudio server isn't started,
  • the user you're running kodivc as is not allowed to access the audio device you're trying to capture speech from; to confirm, try running kodivc as root - if it works fine, you're facing a permissions-related issue.

• If after starting kodivc you get an error saying Failed to calibrate voice activity detection, please check your mixer levels for capturing audio.

Language support

Currently kodivc only supports voice commands spoken in English. Additional languages may be added in the future.

Caveats

In normal mode, kodivc will perform a maximum of 5 actions at a time to avoid confusion. You can say more voice commands than that, but only the first five recognized commands will be executed.

Feedback

I'm always happy to hear feedback. If you encounter a problem with kodivc or you want to share an idea for a new feature, feel free to create an issue at GitHub. Here are some tips for creating a useful bug report:

• Be as exhaustive as possible.

• If possible, describe the steps required to reproduce the bug.

• Include version information for kodivc, sphinxbase and pocketsphinx in the report. In KodiBuntu / XBMCbuntu / Ubuntu you can use the following command to retrieve the relevant information:

  dpkg -s kodivc libsphinxbase1 libpocketsphinx1 | grep '\(Package\|Version\)'
  

  If you built kodivc from Git, please include the output of the following command in the report:

  kodivc -V
  

• If available (must be enabled explicitly using the -L command line switch), attach the log file to the report. If you didn't enable logging but you can still get hold of the messages output by kodivc to the console before the crash, please save them to a file and attach that file to the report.

• If you experienced a segfault, please generate a backtrace and attach it to the report. gdb is required to do that. In KodiBuntu / XBMCbuntu / Ubuntu you can install gdb by running the following command:

  sudo apt-get -y install gdb
  

  kodivc generates core dumps by default, so all that is required to generate a backtrace is running the following command after kodivc crashes:

  gdb --batch --se kodivc --core core -ex 'bt full' > kodivc-backtrace.txt 2>&1
  

  The backtrace will be written to file kodivc-backtrace.txt. Ensure your core dump is named core - it differs between systems and thus the core dump may be placed in a file like core.12345 or similar - just supply the proper core dump file name to gdb using the --core option. Please note that if the segfault happened while kodivc was running in daemon mode, the core dump will be placed in the /tmp directory.

If you don't have a GitHub account and you don't really want to create one, feel free to post in the kodivc thread at the Kodi forums or catch me on Twitter.