Skip to content
Kando Logo Kando

Creating Sound Themes

banner

Kando allows you to create custom sound themes to make the menu even more fun to use. A sound theme is a collection of sound files which are played when certain events occur in the menu.

Sound Theme Locations

If you want to create a new sound theme, you should put a new subdirectory into the sound-themes directory. The location of this directory depends on your operating system:

%appdata%\kando\sound-themes\

If you are running Kando from the source code via npm start, it will also look for themes in the assets/sound-themes/ directory.

Anatomy of a Sound Theme

This section will give you an overview of the files you need to create a new sound theme. A sound theme directory must contain a theme.json5 file and can contain any number of sound files.

  • Directorykando
    • Directorysound-themes
      • Directorymy-theme
        • theme.json5
        • REUSE.toml
        • foo.mp3 You can put any number of sound files in your theme directory and name them whatever you like.

theme.json5 contains metadata about the theme and assigns sound files to certain events.

REUSE.toml is not strictly necessary, but it is recommended to include it in your theme directory. It contains information about the license of your theme.

Besides, you can put any sound files you like in your theme directory. Kando supports mp3, mpeg, opus, ogg, oga, wav, aac, caf, m4a, mp4, weba, webm, dolby, and flac files.

The theme.json5 File

Below you can have a look at a simple theme.json5 file. Besides the metadata, it contains a list of sound files which are played when certain events occur in the menu.

theme.json5
// SPDX-FileCopyrightText: Simon Schneegans <code@simonschneegans.de>
// SPDX-License-Identifier: CC0-1.0


{
  name: 'Default',
  author: 'Simon Schneegans',
  license: 'CC0-1.0',
  themeVersion: '1.0',


  // This theme was created for Kando's sound theme engine version 1.
  // Kando will use this to check if the theme is compatible with the
  // current version of Kando.
  engineVersion: 1,


  // This is a list of sound files which are played when certain events
  // occur in the menu.
  sounds: {
    openMenu: {
      file: "open.mp3",
    },
    closeMenu: {
      file: "close.mp3",
      volume: 0.5,
    },
    hoverItem: {
      file: "hover.mp3",
      minPitch: 0.9,
      maxPitch: 1.1,
    },
  },
}

Available Sound Events

The following events are available for sound themes. For each event, you can specify a sound file which is played when the event occurs. It is perfectly fine to reuse the same sound file for multiple events.

Event
Description
openMenuThis event is triggered when a menu is opened.
closeMenuThis event is triggered when a menu is closed without selecting an item.
hoverItemThis event is triggered when a leaf item is hovered with the mouse. That is an item which does not have any children and can be executed.
hoverParentThis event is triggered when the parent of the current center item is hovered with the mouse.
hoverSubmenuThis event is triggered when a submenu which could be opened is hovered with the mouse.
selectItemThis event is triggered when an action is executed by selecting an item.
selectParentThis event is triggered when the user navigates to the parent of the current center item.
selectSubmenuThis event is triggered when a submenu is opened.

Advanced Configuration

For each event, you can specify the volume of the sound file and the pitch of the sound file. This allows reusing the same sound file for multiple events while making them sound different. If you specify a minPitch and a maxPitch, Kando will play the sound file with a random pitch between these two values. You can set them to the same value to play the sound file with a fixed pitch.

theme.json5
// ...
hoverItem: {
  file: "hover.mp3",
  volume: 0.5,
  minPitch: 0.9,
  maxPitch: 1.1,
},
// ...

Adding Proper Credits

A theme usually builds upon the work of others. Therefore, it is important to give proper credit to the original authors!

To make sure that your theme is compliant with the licenses of the assets, it is highly recommended to follow the corresponding steps outlined in the menu-theme creation guide.

Distributing your Theme

You are invited to show your themes in Kando’s Discord Server! You can also contribute your themes to the Kando Sound Themes Repository by creating a pull request.