### Listing output example for aconnect -i -o Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aconnect.md Example output when listing ports without -l. Shows client and port lines with type, card, and port names. ```text client 14: 'ALSA' [type=kernel,card=1] 0 'HDA Intel ' 1 'HDA Intel MIDI ' ``` -------------------------------- ### Start alsamixer on second sound card with capture view and custom config Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsamixer.md Starts alsamixer on the second sound card (device index 1) with capture view and a custom configuration file. Use -f to specify the config file path. ```bash alsamixer -c 1 -V capture -f ~/.config/alsamixer.rc ``` -------------------------------- ### Config file example for -g option Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsaloop.md Example `-g` config file with one job per line. Lines are tokenized (whitespace separated, `'`/`"` quoting, `#` comment) and re-fed to the option parser with the same option set minus daemonizing. `parse_config_file()` in `alsaloop.c:657-736` enforces `MAX_ARGS` (128) words per line and returns `-EIO`/`-ENOMEM` on failures. ```text # job 1: 500 ms latency, high quality -P default -C default -t 500000 -S samplerate -A sincbest # job 2: 1 ms latency -P hw:1 -C hw:1 -t 1000 ``` -------------------------------- ### aseqdump raw view output example Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aseqdump.md Example raw view output from aseqdump. Shows the 'Waiting for data.' message and sample events with source client:port, event type, and parameters. ```text Waiting for data. 14:0 Clock 14:0 Note on 1, note 60, velocity 100 14:0 Note off 1, note 60, velocity 0 14:0 Control change 1, controller 7, value 100 14:0 Pitch bend 1, value 8192 System exclusive (hex) ... F0 43 7E 7F F7 ``` -------------------------------- ### Consumer setup with category code, copyright, original Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/iecset.md Sets consumer mode on device hw:1 with category code 0x00, copyright on, original on, and 44100 Hz sample rate. ```bash iecset -D hw:1 pro off cat 0x00 cop on ori on rat 44100 ``` -------------------------------- ### Run the alsaconf wizard Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsaconf.md Starts the interactive configuration wizard. Requires dialog or Xdialog (Xdialog when DISPLAY is set) for the wizard part. ```bash alsaconf ``` -------------------------------- ### alsamixer config file fragment (bind + theme + wheel) Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsamixer.md Example configuration file fragment showing bind, color, and set directives. Binds the 'k' key to CMD_MIXER_CONTROL_DOWN, sets the label color to red, and configures mouse wheel step and focus behavior. ```text bind mixer k CMD_MIXER_CONTROL_DOWN color label red set mouse_wheel_step 10 set mouse_wheel_focuses_control 1 ``` -------------------------------- ### Server bridging MIDI input to network Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aseqnet.md Starts aseqnet in server mode on port 45000, reading from the MIDI input of hw:0 and naming the client 'net-midi-server'. ```bash aseqnet -p 45000 -s hw:0 -n "net-midi-server" ``` -------------------------------- ### aplaymidi usage examples Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aplaymidi.md Example invocations of aplaymidi: playing to a numeric port, using a named port with a delay, and using the ALSA_OUTPUT_PORTS environment variable as a fallback for the port specification. ```bash aplaymidi -p 128:0 song.mid aplaymidi -p 'FLUID Synth' -d 2 *.mid ALSA_OUTPUT_PORTS=14:0 aplaymidi song.mid # pmidi-compatible env var ``` -------------------------------- ### GET https://www.alsa-project.org/alsa-info.sh Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/endpoints.md Downloads the server copy of the `alsa-info.sh` script for self-update. ```APIDOC ## GET https://www.alsa-project.org/alsa-info.sh ### Description Downloads the server copy of the `alsa-info.sh` script for self-update. The script compares the downloaded version with the local `SCRIPT_VERSION` and offers to overwrite the current script or download it to a separate file. ### Method GET ### Endpoint https://www.alsa-project.org/alsa-info.sh ### Request Example ``` wget -O $SHFILE https://www.alsa-project.org/alsa-info.sh ``` ### Response #### Success Response - **body** (script) - The latest version of the `alsa-info.sh` script. ### Related URL - **Changelog**: https://www.alsa-project.org/alsa-info.sh.changelog ``` -------------------------------- ### Test 5.1 speaker setup with speaker-test -Dplug:surround51 -c6 Source: https://github.com/alsa-project/alsa-utils/blob/master/speaker-test/readme.txt Tests a 5.1 speaker setup from three stereo jacks using the surround51 PCM device. ```shell ./speaker-test -Dplug:surround51 -c6 ``` -------------------------------- ### Test 4-speaker setup with speaker-test -Dplug:surround40 -c4 Source: https://github.com/alsa-project/alsa-utils/blob/master/speaker-test/readme.txt Tests a 4-speaker setup from two stereo jacks using the surround40 PCM device. ```shell ./speaker-test -Dplug:surround40 -c4 ``` -------------------------------- ### arecordmidi usage examples Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aplaymidi.md Example invocations of arecordmidi: recording with tempo, ticks, metronome, and time signature; and recording with split channels and a fixed event count. ```bash arecordmidi -p 128:0 -b 120 -t 96 -m 130:0 -i 4:4 take1.mid arecordmidi -p 'MAX' -s -n 1000 sampled.mid ``` -------------------------------- ### Set a variable and list valid values Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsaucm.md Set a UCM variable with `set` and list valid values with `list1`. The example sets `PlaybackMasterVolume` to 50 and lists `TransitionList`. ```bash alsaucm -c default set PlaybackMasterVolume 50 alsaucm -c default list1 TransitionList ``` -------------------------------- ### Export format environment variables Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsactl.md Example of the environment variables exported by `alsactl --export` for single and multiple sound cards. States are `active`, `skip`, and `waiting`; udev rules consume this interface via `alsactl --export restore $card`. ```text # single card: ALSA_CARD_NUMBER=0 ALSA_CARD_STATE=active # multiple cards: ALSA_CARD0_STATE=active ALSA_CARD1_STATE=waiting ``` -------------------------------- ### Error handling in non-interactive mode Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsaucm.md Check for failure of a UCM command in a non-interactive script. The example tests `get NonExistentIdent` and prints an error message with the exit code. ```bash if ! alsaucm -c default get NonExistentIdent >/dev/null; then echo "UCM identifier lookup failed (exit $?)" >&2 fi ``` -------------------------------- ### Query and print a card's UCM variable Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsaucm.md Use `alsaucm -c default get PlaybackMasterVolume` to retrieve a UCM variable. The output is shown as `PlaybackMasterVolume=30`. ```bash alsaucm -c default get PlaybackMasterVolume # -> PlaybackMasterVolume=30 ``` -------------------------------- ### Error handling for control lookup failure Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/amixer.md Error handling example for control lookup failure. Checks the exit status of amixer sget and prints a message to stderr if the control is missing. ```bash if ! amixer -D hw:5 sget NonExistentControl; then echo "control missing (exit status $?)" >&2 fi ``` -------------------------------- ### Batch script from stdin Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsaucm.md Run a batch script from stdin using `-b -`. The script lists cards, opens default, resets, and gets TransitionList. The `-n` flag avoids auto-open for listcards. ```bash echo 'listcards open default reset get TransitionList' | alsaucm -n -b - ``` -------------------------------- ### Basic playback with options Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aplay.md Plays a WAV file using the specified hardware device, CD-quality format, two channels, 44100 Hz sample rate, and WAV file type. ```bash aplay -D hw:0 -f cd -c 2 -r 44100 -t wav announcement.wav ``` -------------------------------- ### Working batch mode for list _devices Source: https://github.com/alsa-project/alsa-utils/blob/master/alsaucm/alsaucm.rst Runs `open`, `set _verb`, and `list _devices` in a single batch mode session, which works because the verb is set in the same execution. ```shell # alsaucm -n -b - < [command] Available options: -h,--help this help -c,--card NAME open card NAME -i,--interactive interactive mode -b,--batch FILE batch mode (use '-' for the stdin input) -n,--no-open do not open first card found Available commands: open NAME open card NAME reset reset sound card to default state reload reload configuration listcards list available cards dump FORMAT dump all config information (format: text,json) list IDENTIFIER list command, for items with value + comment list1 IDENTIFIER list command, for items without comments get IDENTIFIER get string value geti IDENTIFIER get integer value set IDENTIFIER VALUE set string value h,help help q,quit quit ``` -------------------------------- ### Mute front channels and verify Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/amixer.md Mutes front-left and front-right channels, then verifies the result with sget in quiet mode (-q). ```bash amixer -q sset Master frontleft,mute frontright,mute amixer sget Master ``` -------------------------------- ### Usage help text for nhlt-dmic-info Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/nhlt-dmic-info.md The declarative help table shown by the tool. Note the banner says 'nhtl-dmic-json' but the actual binary is 'nhlt-dmic-info'. ```text Usage: nhtl-dmic-json global options: -h,--help this help -v,--version print version of this program -f,--file NHLT file (default /sys/firmware/acpi/tables/NHLT) -o,--output output file ``` -------------------------------- ### Test right channel with sine wave Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/speaker-test.md Tests only the right channel (speaker 2) with a 1 kHz sine wave at 50% volume. The -s option selects the speaker, -f sets the frequency, and -S sets the volume percentage. ```bash speaker-test -s 2 -t sine -f 1000 -S 50 ``` -------------------------------- ### Fallback when wget is missing Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsa-info.md Checks for the presence of wget; if missing, falls back to generating a local report file without upload. This guards against environments where upload is not possible. ```bash if ! command -v wget >/dev/null; then alsa-info.sh --no-upload --output "$HOME/alsa-info.txt" fi ``` -------------------------------- ### Dump geometry from ACPI NHLT table Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/nhlt-dmic-info.md Command to read the NHLT table from the default firmware path and write the JSON report to /tmp/dmics.json. ```bash nhlt-dmic-info -f /sys/firmware/acpi/tables/NHLT -o /tmp/dmics.json ``` -------------------------------- ### aseqnet usage text Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aseqnet.md The exact usage text printed by aseqnet, showing command-line syntax and options. ```text aseqnet - network client/server on ALSA sequencer Copyright (C) 1999 Takashi Iwai usage: server mode: aseqnet [-options] client mode: aseqnet [-options] server_host options: -6,--ipv6 : use IPv6 TCP protocol -p,--port # : specify TCP port (digit or service name) -s,--source addr : read from given addr (client:port) -d,--dest addr : write to given addr (client:port) -n,--name value : use a specific midi process name -v, --verbose : print verbose messages -i, --info : print certain received events ``` -------------------------------- ### Test stereo output with speaker-test -Dplug:front -c2 Source: https://github.com/alsa-project/alsa-utils/blob/master/speaker-test/readme.txt Tests stereo sound from one stereo jack using the front PCM device. ```shell ./speaker-test -Dplug:front -c2 ``` -------------------------------- ### Standalone debug pass with --saveplay Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsabat.md Performs a standalone debug pass without analysis, saving the played audio to /tmp/played.wav. Useful for debugging playback only. ```bash alsabat -D hw:0 --standalone --saveplay=/tmp/played.wav ``` -------------------------------- ### Send a SysEx patch dump Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aseqsend.md Sends a SysEx patch dump from a file to a sequencer port. ```bash aseqsend -p 128:0 -s patch.syx ``` -------------------------------- ### aplaymidi2 usage text Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aplaymidi2.md Exact usage text for aplaymidi2, showing the command syntax and all available options. The -p option is required and defaults to the ALSA_OUTPUT_PORTS environment variable, otherwise an error is raised. The -d option sets a delay in seconds after playback, and -a forwards all UMP packets verbatim. ```text Usage: aplaymidi2 -p client:port[,...] [-d delay] midifile ... -h, --help this help -V, --version print current version -p, --port=client:port,... set port(s) to play to -d, --delay=seconds delay after song ends -s, --silent don't show texts -a, --passall pass all UMP packets as-is ``` -------------------------------- ### Error handling for config parse failure Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsaloop.md Demonstrates error handling for a config parse failure. The config file contains a typo ('defaul' instead of 'default'), and the script checks the exit status of alsaloop, printing the error message and exiting with failure. ```bash echo '-P default -C defaul' > /tmp/loops.conf # typo if ! alsaloop -g /tmp/loops.conf 2>/tmp/loops.err; then echo "alsaloop failed: $(cat /tmp/loops.err)" >&2 exit 1 fi ``` -------------------------------- ### Error handling with exit status Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aplay.md Checks the exit status of aplay and prints an error message to stderr if the device is unavailable, then exits with status 1. ```bash pcm="hw:99,0" # non-existent device if ! aplay -D "$pcm" -q /usr/share/sounds/alsa/test.wav; then echo "aplay failed: device $pcm unavailable" >&2 exit 1 fi ``` -------------------------------- ### Error handling for format/rate mismatch Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/axfer.md Shows error handling when format/rate mismatch occurs; the command fails because -f cd implies 44100 Hz while -r 48000 is specified. ```bash if ! axfer transfer capture -f cd -r 48000 -t wav /tmp/x.wav; then echo "axfer rejected the conflicting cd(44100) / 48000 combination" >&2 fi ``` -------------------------------- ### Route one port to another with aconnect Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aconnect.md Connects a sender port to a receiver port. Two equivalent forms are shown: numeric client:port pairs and named clients. ```bash aconnect 128:0 129:0 aconnect 'FLUID Synth' 'ALSA Mixer' ``` -------------------------------- ### aplaymidi usage text Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aplaymidi.md Exact usage text for the aplaymidi command, listing all options and their arguments. Use this to understand the command-line interface and required arguments. ```text Usage: aplaymidi -p client:port[,...] [-d delay] midifile ... -h, --help this help -V, --version print current version -l, --list list all possible output ports -p, --port=client:port,... set port(s) to play to -u, --ump=version UMP output (only version=1 is supported) -d, --delay=seconds delay after song ends ``` -------------------------------- ### Send SysEx dump and quit Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/amidi.md Two commands to send SysEx data and quit. The first sends the contents of patch.syx, the second sends the contents of dump.syx followed by the hex bytes F0 43 20 01 10 F7. Note that `--send` combined with `--send-hex` is an error, so these are separate invocations. ```bash amidi -p hw:0 -s patch.syx ``` ```bash amidi -s dump.syx --send-hex "F0 43 20 01 10 F7" ``` -------------------------------- ### One file per channel capture Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/axfer.md Captures 2-channel audio at 48000 Hz, writing one file per channel (ch1.wav, ch2.wav). ```bash axfer transfer capture -I -c 2 -t wav -r 48000 ch.wav ``` -------------------------------- ### alsamixer usage text Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/alsamixer.md Exact usage text printed by alsamixer's help. Lists all command-line options, their arguments, and the two option groups (useful and debugging). ```text Usage: alsamixer [options] Useful options: -h, --help this help -c, --card=NUMBER sound card number or id -D, --device=NAME mixer device name -m, --mouse enable mouse -M, --no-mouse disable mouse -f, --config=FILE configuration file -F, --no-config do not load configuration file -V, --view=MODE starting view mode: playback/capture/all -B, --black-background use black background color Debugging options: -g, --no-color toggle using of colors -a, --abstraction=NAME mixer abstraction level: none/basic ``` -------------------------------- ### SMPTE ST-2095 measurement loop Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/speaker-test.md Runs an SMPTE ST-2095 measurement loop with explicit period count. -P sets the number of periods, -b the buffer size, and -p the period size. ```bash speaker-test -t st2095 -c 2 -P 8 -b 200000 -p 20000 ``` -------------------------------- ### Error handling when port is in use Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aseqnet.md Checks the exit status of aseqnet and prints an error message if it fails, capturing stderr to a temporary file. ```bash if ! aseqnet -p 40002 2>/tmp/net.err; then echo "aseqnet failed: $(cat /tmp/net.err)" >&2 fi ``` -------------------------------- ### Disconnect and remove everything with aconnect Source: https://github.com/alsa-project/alsa-utils/blob/master/_autodocs/api-reference/aconnect.md Disconnects a specific pair and then removes all exported connections. ```bash aconnect -d 128:0 129:0 aconnect -x ```