alsaucm(1)

📦
version 1.2.16 · 6 versions
, in arch rolling, fedora 44, ubuntu resolute

alsaucm(1) — ALSA Use Case Manager 🎛️✨

okay bestie, welcome to the General Commands Manual entry for alsaucm(1). this is the ALSA Use Case Manager, and it's literally your command-line bestie for making complex sound cards behave. no cap, it's giving “audio routing but make it understandable” energy. 💅

💖 Name 💖

alsaucm — ALSA Use Case Manager. short, iconic, to the point. 🫶

✨ SYNOPSIS ✨

alsaucm <options> [command]

🦋 DESCRIPTION 🦋

okay so alsaucm (the ALSA Use Case Manager) is a program for using the ALSA Use Case Interface (http://www.alsa-project.org/alsa-doc/alsa-lib/group__ucm.html) from the command line. yes, the command line. where the magic happens. ✨

On complex sound cards, setting up audio routes is not trivial, and mixer settings can conflict with one another — which can prevent the audio card from working at all. 😭 not the vibe.

The ALSA Use Case Manager is a mechanism for controlling complex audio hardware by establishing a relationship between hardware configurations and meaningful use cases that the end-user can relate to. it's basically matchmaking, but for hardware and vibes. 💖

The use case manager can also be used to switch between use cases when necessary, in a consistent way. slay. 👑

At a lower level, the use case manager works by configuring the sound card ALSA kcontrols to change the hardware digital and analog audio routing to match the requested device use case. yes, it's touching the kcontrols. respect. 🎛️

The use case manager kcontrol configurations are stored in easy to modify text files. An audio use case can be defined by a verb and device parameter. two little params, one cute pair. 🎀

The verb describes the use case action i.e. a phone call, listening to music, recording a conversation, etc. The device describes the physical audio capture and playback hardware i.e. headphones, phone handset, bluetooth headset, etc. periodt. 💅

💅 OPTIONS 💅

Available options: 🎀

  • -h, --help — this help. like, the help you need. ✨
  • -c, --card NAME — open card NAME. choose your card, bestie. 💳
  • -i, --interactive — interactive mode. tap in, live. 💬
  • -b, --batch FILE — batch mode (use '-' for the stdin input). yes, use '-' for the stdin input. 🍓
  • -n, --no-open — do not open first card found. respect the boundaries. 🙈

Available commands: 👑

  • open NAME — open card NAME. valid names are sound card names as listed in /usr/share/alsa/ucm. 💖
  • reset — reset sound card to default state. factory reset but for audio. 🔄
  • reload — reload configuration. refresh, bestie. 🌸
  • listcards — list available cards. show me the lineup. 🃏
  • list IDENTIFIER — list command, for items returning two entries (value+comment). the value of the IDENTIFIER argument can be:
    • _verbs — get verb list (in pair verb+comment)
    • _devices[/{verb}] — get list of supported devices (in pair device+comment)
    • _modifiers[/{verb}] — get list of supported modifiers (in pair modifier+comment)

The forms without the trailing /{verb} are valid only after a specific verb has been set. 🔥

  • list1 IDENTIFIER — list command, for lists returning one item per entry. the value of the IDENTIFIER argument can vary depending on the context, it can be:
    • TQ[/{verb}] — get list of Tone Quality identifiers
    • _enadevs — get list of enabled devices
    • _enamods — get list of enabled modifiers
    • _supporteddevs/{modifier}|{device}[/{verb}] — list of supported devices
    • _conflictingdevs/{modifier}|{device}[/{verb}] — list of conflicting devices
  • get IDENTIFIER — get string value. the value of the IDENTIFIER argument can be:
  • geti IDENTIFIER — get integer value. the value of the IDENTIFIER argument can be:
    • _devstatus/{device}
    • _modstatus/{device}
  • set IDENTIFIER VALUE — set string value. The value of the IDENTIFIER argument can be:
    • _verb — set the verb to VALUE
    • _enadev — enable the device specified by VALUE
    • _disdev — disable the device specified by VALUE
    • _swdev/{old_device} — switch device:
      • disable old_device and then enable the device specified by VALUE
      • if no device was enabled just return
    • _enamod — enable the modifier specified by VALUE
    • _dismod — disable the modifier specified by VALUE
    • _swmod/{old_modifier} — switch modifier:
      • disable old_modifier and then enable the modifier specified by VALUE
      • if no modifier was enabled just return

Note that the identifiers referring to devices and modifiers are valid only after setting a verb. 🫶

  • h, help — help
  • q, quit — quit

🌈 FILES 🌈

The master use case files for each supported sound card are in /usr/share/alsa/ucm. 💖

For example, the master use case file for the Pandaboard card is in /usr/share/alsa/ucm/PandaBoard/PandaBoard.conf, this file lists all the supported use cases, e.g.

SectionUseCase."HiFi" {
                File "hifi"
                Comment "Play HiFi quality Music."
}
...

Each use case defines a _verb, which is described in the file specified in the File directive, like above. 🎀

The HiFi verb above is described in /usr/share/alsa/ucm/PandaBoard/hifi. yes, same name, different file, iconic. ✨

For more details on the syntax of UCM files, see the alsa-lib source code: http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=src/ucm/parser.c

🌟 EXAMPLES OF USE 🌟

Some commands, like for instance list _devices, can only work after setting a _verb in the same execution, for instance this sequence doesn't work:

# alsaucm -c bytcr-rt5640 set _verb HiFi
# alsaucm -c bytcr-rt5640 list _devices

However this command does:

# alsaucm -n -b - <<EOM
open bytcr-rt5640
set _verb HiFi
list _devices
EOM

An example of setting the Speaker device for the HiFi verb of the bytcr-rt5640 card:

# alsaucm -n -b - <<EOM
open bytcr-rt5640
reset
set _verb HiFi
set _enadev Speaker
EOM

🧚 SEE ALSO 🧚

💀 BUGS 💀

None known. 💅 iconic, honestly.

🌸 Author 🌸

Antonio Ospite <ao2@ao2.it>

GPLv2+

okay that's the whole alsaucm(1) page! mwah 💋 — from the General Commands Manual, dated 2016-09-22, for alsaucm(1). byeee bestie! 🫶✨

📦 where this page comes from