Joren/qbz

0 Fork 0

Files

T

vicrodh 7091c64d56 Add alsa-utils to all package formats with appropriate handling

AUR (Arch Linux):
- Added to optdepends: 'alsa-utils: Better ALSA device names and descriptions'
- Users get notification to install, but not required

Flatpak:
- Included alsa-utils module in bundle (builds from source)
- Version 1.2.12 from alsa-project.org
- Sandboxed environment can now execute aplay -L internally
- Disabled alsamixer and xmlto (not needed, reduces size)
- Users get real device descriptions automatically

Snap (future - not yet implemented):
- Created snapcraft.yaml template
- stage-packages includes alsa-utils
- Will be bundled when Snap support is implemented

AppImage (future - not yet implemented):
- Created README.md documenting dependencies
- AppImage uses host system commands (aplay from host)
- Users need to install alsa-utils on their system
- Fallback to CPAL works if not installed

Summary by format:
- .deb/.rpm: Recommends alsa-utils (auto-installed, can be removed)
- AUR: optdepends (user notified, optional)
- Flatpak: Bundled (always available)
- Snap: Will be bundled (future)
- AppImage: Host dependency (user installs)

2026-01-17 20:04:29 -06:00

README.md

Add alsa-utils to all package formats with appropriate handling

2026-01-17 20:04:29 -06:00

README.md

QBZ AppImage

About AppImage

AppImage is a portable format that bundles the application and its dependencies. However, it still uses system libraries and commands from the host system.

Dependencies

Required (Hard Dependencies)

The following must be installed on the host system for QBZ to work:

ALSA library (libasound2 on Debian/Ubuntu, alsa-lib on Arch)
GTK3 and WebKit2GTK
OpenSSL

These are typically already installed on most Linux distributions.

Optional (Recommended)

For the best experience, install these optional packages:

alsa-utils

Package names:

Debian/Ubuntu: alsa-utils
Fedora/RHEL: alsa-utils
Arch: alsa-utils

Why it's needed:

Provides the aplay command used by QBZ to enumerate ALSA devices
Without it, you'll see raw device names like front:CARD=CS201,DEV=0
With it, you'll see friendly names like "Cambridge Audio USB Front Output"

What happens without it:

ALSA Direct backend falls back to CPAL enumeration (still works)
Device names won't be as descriptive
All functionality works, just with less friendly UI

PipeWire/PulseAudio

For PipeWire:

pipewire-alsa - ALSA compatibility
pipewire-pulse - PulseAudio compatibility

For PulseAudio:

pulseaudio
pulseaudio-alsa

Why it's needed:

Required for PipeWire/PulseAudio audio backends
Required for DAC Passthrough feature (uses pw-metadata)

Building AppImage

TODO: Add build instructions using appimagetool or similar

Installation

Download the AppImage from releases
Make it executable: chmod +x QBZ-*.AppImage
Run: ./QBZ-*.AppImage

System Integration

To integrate with your desktop environment:

# Install optional tool for desktop integration
sudo apt install appimaged  # Debian/Ubuntu
# or
yay -S appimagelauncher     # Arch

# AppImage will automatically appear in your application menu

Troubleshooting

"No ALSA devices found"

Install alsa-utils:

sudo apt install alsa-utils  # Debian/Ubuntu
sudo dnf install alsa-utils  # Fedora
sudo pacman -S alsa-utils    # Arch

"DAC Passthrough not working"

Ensure PipeWire is running:

systemctl --user status pipewire

Install pw-metadata:

sudo apt install pipewire-bin  # Debian/Ubuntu (includes pw-metadata)