Sound Themer

Project Summary

• Built a configurable CLI tool for playing themed system sounds based on keyword input.
• Decouples sound naming from file structure, enabling a single interface across multiple themes.
• Designed for integration with system notifications and automation workflows.

Technical Challenges

• Abstracting over inconsistent filesystem layouts across themes.
• Designing a flexible mapping system without ambiguity.
• Maintaining a simple CLI without compromising high configurability.
• Handling multiple file extensions and nested directories efficiently.

Core Design

• Keyword-driven playback system:
  • sound_themer play <KEYWORD> resolves to a mapped sound file.
  • Falls back to direct filename matching if no mapping exists.
• Theme Abstraction Layer:
  • Each theme defines its own directory structure, file extensions, and naming scheme.
  • Ensures consistent CLI usage across incompatible sound packs.
• Runtime Flexibility:
  • Themes can be overridden via CLI flags without modifying the config.

Configuration System

• Uses TOML for human-readable, extensible configuration.
• Defines:
  • Active theme.
  • Theme directories and file extensions.
  • Keyword → filename mappings.
• Supports:
  • Nested directory structures.
  • Non-uniform naming conventions across sound themes.
• Mapping system enables:
  • Normalisation of inconsistent naming.
  • Reuse of the same commands across all themes.

Command Line Interface

• Built using Clap for structured command parsing.
• Supports:
  • Subcommands with built-in help output.
  • Command aliases (play → p, list → ls).
• Example usage:

  Command	Description
  sound_themer play <SOUND_NAME> sound_themer p <SOUND_NAME>	Plays a sound from the theme folder. Maps from SOUND_NAME to its associated value in the selected theme (if one exists).
  sound_themer list sound_themer ls	Lists the sound files in the currently selected theme's folder.
  sound_themer --⁠theme <THEME_NAME> <COMMAND> sound_themer -t <THEME_NAME> <COMMAND>	Overrides the theme which is selected in config.toml.

Extensibility

• New themes can be added without making code changes.
• Configuration-driven design supports:
  • Custom keyword dictionaries.
  • Arbitrary directory layouts.
  • Additional sound formats.
• Suitable for integration with:
  • Window managers.
  • Notification systems.
  • Automation scripts.

Example Config

# Name of the selected sound theme
theme_name = "freedesktop"

[[themes]]
# Name of the sound theme folder
name = "freedesktop"

# Extension on the sound files
sound_ext = "oga"

# Directories where the sounds are found
directories = ["stereo"]

# Provide a mapping between certain phrases and their respective sound file name
mapping = {
  audio-change = "audio-volume-change",
  login = "service-login",
  logout = "service-logout",
  message = "message",
  power-plug = "power-plug",
  power-unplug = "power-unplug",
  dialog-info = "dialog-information",
  dialog-warning = "dialog-warning",
  dialog-error = "dialog-error",
  screen-capture = "screen-capture",
  device-added = "device-added",
  device-removed = "device-removed",
  camera-shutter = "camera-shutter",
  trash-empty = "trash-empty",
  complete = "complete"
}