- Implemented custom tooltip for StackIcon (similar to AudioOutputBadges)
- Shows 'Playing from', context name, and 'Click to navigate' hint
- Added onContextClick={handleContextNavigation} to ExpandedPlayer
- Fixed onClick prop not being passed, enabling navigation
cp
Added translations for:
- Autoplay behavior setting
- Continue within source / Play only selected track options
- Show context icon setting and tooltip
Both English and Spanish translations added.
Changed StackIcon tooltip to use native browser title (matches QualityBadge style).
Removed arrow indicator from context icon (cursor change is sufficient).
cp
Problem:
- Users updating from previous versions would crash on startup
- Table created with new column caused "no column named show_context_icon" error
- Existing users had old schema without the column
Solution:
- Step 1: Create table with old schema (backwards compatible)
- Step 2: Check if show_context_icon column exists using pragma_table_info
- Step 3: Add column ONLY if it doesn't exist (safe migration)
- Step 4: Insert default row
This ensures:
✅ New installs work (table created fresh)
✅ Existing users migrate seamlessly (column added, settings preserved)
✅ No data loss
✅ Idempotent (can run multiple times safely)
Tested scenarios:
- Fresh install (no DB) → creates table, adds column, inserts defaults
Result: id=1, autoplay_mode='continue', show_context_icon=1
- Existing DB without column → adds column, preserves user settings
Result: id=1, autoplay_mode='track_only' (preserved), show_context_icon=1
- Existing DB with column → no changes (idempotent)
Migration logs added for debugging.
cp
StackIcon Component:
- Now accepts onClick prop
- Changed from div to button element
- Added arrow (→) that appears on hover
- Tooltip text changed to "Click to go to: {source}"
- Visual feedback: hover background + active scale
Navigation Logic (+page.svelte):
- Added handleContextNavigation function
- Switch based on context_type:
- album → handleAlbumClick
- playlist → navigate + set selectedPlaylistId
- artist_top → handleArtistClick
- favorites → navigate to favorites
- home_list → navigate to home
- search → navigate to search
- Import getCurrentContext from playbackContextStore
UI Integration:
- ExpandedPlayer: Added onContextClick prop, passed to StackIcon
- FocusMode: Added onContextClick prop, passed to StackIcon
- Both receive handleContextNavigation callback
Phase 3.7 COMPLETE ✅
cp
Frontend:
- Add show_context_icon to PlaybackPreferences interface
- Add setShowContextIcon function to store
- StackIcon now subscribes to preferences and checks show_context_icon
- Icon hidden when setting is false (context still tracked)
UI (Settings → Playback):
- Add toggle: "Show track playing context in player"
- Tooltip with bilingual explanation (EN/ES)
- Default: enabled (true)
- Persists across restarts
Context tracking ALWAYS active regardless of icon visibility.
Phase 3.6 COMPLETE ✅
cp
Context creation:
- Creates 'home_list' context for Continue Listening section
- Uses 'continue_listening' as ID and 'Continue Listening' as label
- Tracks user's listening history in a context
- Stack icon will show "Playing from: Continue Listening"
Home view now fully integrated with context system.
cp
Context creation:
- Creates 'search' context when playing track from results
- Uses search query as ID and 'Search: {query}' as label
- Applies to both All tab (first 6) and Tracks tab (full list)
- Stack icon will show "Playing from: Search · {query}"
Search view now fully integrated with context system.
cp
Context creation:
- Creates 'favorites' context when playing track
- Uses 'favorites' as ID and 'Favorites' as label
- Uses filteredTracks for context (respects search/filter)
- Stack icon will show "Playing from: Favorites"
Favorites view now fully integrated with context system.
cp
Context creation:
- Creates 'artist_top' context when playing from Top Tracks
- Uses artist ID and name
- Passes track index from UI loop
- Stack icon will show "Playing from: Artist · {name}"
Artist view now fully integrated with context system.
cp
Context creation:
- Creates 'playlist' context when playing track
- Uses playlist ID and name
- Filters out local tracks (Qobuz tracks only in context)
- Finds track index in Qobuz tracks list
- Stack icon will show "Playing from: Playlist · {name}"
Playlist view now fully integrated with context system.
cp
Added createContextAndPlayDisplayTrack helper that:
- Creates playback context with provided type/id/label/tracks
- Calls handleDisplayTrackPlay to start playback
- Will be used by Playlist, Artist, Favorites, Home views
Next: Implement context creation in each view component internally
(following AlbumDetailView pattern but keeping logic in views)
cp
Stack icon now appears in artist/album area across all players:
- FocusMode: icon before artist (size 12px)
- MiniPlayer: icon at start of artist-album row (size 12px)
- Consistent sizing: 12px (compact players), 16px (expanded player)
- Visual hierarchy: Title → [icon] Artist · Album
All 4 players updated and consistent.
cp
Icon now appears before artist/album metadata instead of title.
Changes:
- NowPlayingBar: icon in song-meta row (size 12px)
- ExpandedPlayer: icon in new artist-album-row with separator (size 16px)
- Removed song-title-row wrapper (not needed)
- Icon placement: [icon] Artist · Album
Remaining: FocusMode and MiniPlayer (next commit)
cp
CRITICAL LOGIC FIX:
The autoplay setting was misunderstood. Corrected behavior:
BEFORE (wrong):
- Setting controls whether context is created
- 'continue' = create context
- 'track_only' = clear context
AFTER (correct):
- Context is ALWAYS created when playing from a source (album/playlist)
- Stack icon ALWAYS appears
- Setting only affects what happens at END of track:
- 'continue' = play next track in context
- 'track_only' = stop after current track
Why this makes sense:
- You're playing from an album = that's the context
- Stack icon shows the origin (informative)
- Setting controls continuation behavior (not context existence)
Also:
- Added logging to handleAutoplayModeChange
- Will investigate why setting doesn't persist
cp
UI Fix:
- Add :has(.radio-group) rule to allow flexible height
- Set align-items: flex-start for radio group rows
- Prevents radio buttons from being squashed
Logging Enhancement:
- Log autoplay_mode preference value
- Log track index and total tracks
- Log when no album tracks found
- Will help diagnose why context isn't being created
cp
CRITICAL FIX: Context was being cleared instead of created.
Root cause:
- AlbumDetailView had internal handlers but used parent's onTrackPlay
- Parent's handleAlbumTrackPlay had no context logic
- Result: context always cleared (default behavior)
Solution:
- Moved context creation logic to handleAlbumTrackPlay in +page.svelte
- Checks autoplay_mode preference
- Creates context if 'continue', clears if 'track_only'
- Removed duplicate logic from AlbumDetailView (was never executed)
Now when clicking a track:
1. handleAlbumTrackPlay checks preference
2. Creates/clears context accordingly
3. Stack icon should appear/disappear correctly
Test with default setting ('continue'):
- Click any track → should see context creation logs
- Stack icon should appear immediately
cp
- Replace onMount/onDestroy with $effect rune for better reactivity
- Add console logging to trace context changes
- Log when setPlaybackContext/clearPlaybackContext are called
- Log when StackIcon receives context updates
This will help debug why stack icon might not appear immediately.
To test:
1. Open browser console
2. Click a track in an album
3. Check logs for '[PlaybackContext]' and '[StackIcon]'
4. Verify context is being set and icon is receiving updates
cp
- Call initPlaybackContextStore() on app mount
- Call initPlaybackPreferences() on app mount
- Load backend state into frontend stores
- Phase 3 backend + UI complete
- Wiring for track actions pending (will be done per-page)
cp
- Add radio buttons: Continue within source / Play only selected track
- Load preference on settings mount
- Save changes immediately via handleAutoplayModeChange
- Styled with hover states and proper spacing
cp
- Add 'Play track only' option (clears context, single track)
- Add 'Play from here' option (sets context from current position)
- Update TrackMenu component with new actions
- Update TrackRow to pass new menu actions
- Backend integration ready for Phase 3 (settings + wiring)
cp
- Create StackIcon component with reactive context subscription
- Display Layers icon before track title when context exists
- Show tooltip with origin info on hover
- Add to: NowPlayingBar, ExpandedPlayer, FocusMode, MiniPlayer
- Icon hidden when no playback context (single track)
- Responsive sizing per player (14px-18px)
cp
- Add PlaybackContext module with ContextManager
- Context tracks semantic origin (album, playlist, artist top, etc.)
- Separate from queue - defines what 'next' means
- Backend: Rust struct with track IDs and position tracking
- Frontend: Svelte store with reactive subscriptions
- Tauri commands for context CRUD operations
- Context is nullable (single track playback has no context)
cp
ALSA Direct is currently non-functional due to CPAL limitations:
- CPAL cannot enumerate or open hw:X,Y devices required for bit-perfect playback
- Only named devices (front:, iec958:, sysdefault:) work, but they all use ALSA plugins with resampling
- User's DAC cannot achieve bit-perfect playback (stuck at 44.1kHz regardless of track sample rate)
Changes:
- Filter out ALSA Direct from backend selector dropdown
- Auto-switch users from ALSA Direct to Auto on settings load
- Add comments indicating this is temporary until alsa-rs rewrite
This prevents user frustration with a broken backend while we evaluate implementing
direct ALSA support via alsa-rs (bypassing CPAL entirely).
Critical Fix:
- CPAL only enumerates named ALSA devices (front:, sysdefault:, etc.)
- CPAL does NOT enumerate hw:X,Y or plughw:X,Y devices
- These must be created manually from aplay -l card list
Solution:
- Parse aplay -l to get card numbers and descriptions
- Manually create hw:X,0 and plughw:X,0 for each card
- Assume max_sample_rate: 384000 (devices are capable)
- Description: "Cambridge Audio USB Audio 2.0 (Direct Hardware - Bit-perfect)"
For user's system (based on aplay -l):
- hw:0,0 → CS201 (Direct Hardware - Bit-perfect)
- hw:2,0 → HDA NVidia (Direct Hardware - Bit-perfect)
- hw:3,0 → sof-hda-dsp (Direct Hardware - Bit-perfect)
- hw:4,0 → Cambridge Audio USB Audio 2.0 (Direct Hardware - Bit-perfect) ← USER NEEDS THIS
- Plus plughw: variants for each
These devices will now appear in the dropdown and can be selected for
true bit-perfect playback without resampling.
UX Problem:
- 4 devices all showed "Cambridge Audio USB Audio 2.0"
- Selecting one would select all (Map key collision)
- User couldn't distinguish between hw:4,0, front:CARD=C20, iec958:CARD=C20
Solution:
- Detect duplicate display names in deviceOptions
- Append [device_id] to duplicates for uniqueness
- Example: "Cambridge Audio USB Audio 2.0 (Direct Hardware - Bit-perfect) [hw:4,0]"
Now User Sees:
- Cambridge Audio USB Audio 2.0 (Direct Hardware - Bit-perfect) [hw:4,0] ← TRUE bit-perfect
- Cambridge Audio USB Audio 2.0 [front:CARD=C20,DEV=0] ← Front output with plugins
- Cambridge Audio USB Audio 2.0 [iec958:CARD=C20,DEV=0] ← S/PDIF with plugins
- Cambridge Audio USB Audio 2.0 [sysdefault:CARD=C20] ← System default with dmix
Each option is now unique and selectable. The hw:4,0 option is clearly
marked as "Direct Hardware - Bit-perfect" for audiophiles.
Critical Fix - Use CPAL Device Names:
- CPAL enumerates devices → these IDs actually work for playback
- aplay -L provides friendly descriptions → update CPAL device descriptions
- Stop creating hw:X,Y devices that CPAL doesn't recognize
- Fixes: "Device not found → fallback to default → audio from laptop"
Flow:
1. enumerate_via_cpal() returns devices CPAL can actually use
2. enumerate_via_aplay() calls #1, then parses aplay -L for descriptions
3. Updates device.description with friendly names from aplay -L
4. Frontend shows: "Cambridge Audio USB Audio 2.0" not "front:CARD=C20,DEV=0"
Loading Overlay:
- Full-screen semi-transparent overlay during device enumeration
- Animated spinner (Loader2 icon)
- "Loading audio devices... / Parsing hardware information"
- Prevents user thinking app is frozen during 4-5 second aplay parse
For Bit-Perfect Playback:
- User should select devices like front:CARD=C20,DEV=0 (CPAL knows these)
- These are more direct than sysdefault:CARD= (which has dmix/plugins)
- Not as direct as hw:4,0 but CPAL can actually find them
PipeWire and PulseAudio backends unchanged - still working as before.
Critical Fix:
- Changed hw: devices from hw:CARD=C20,DEV=0 to hw:4,0
- CPAL only accepts numeric format (hw:X,Y), not named format
- Parse aplay -l to get actual card numbers and device numbers
Before: hw:CARD=C20,DEV=0 → Device not found → fallback to default
After: hw:4,0 → CPAL finds device → bit-perfect playback works
Example from user's system:
- aplay -l shows: card 4: C20 [Cambridge Audio USB Audio 2.0], device 0
- We now create: hw:4,0 (not hw:CARD=C20,DEV=0)
- Description still shows: "Cambridge Audio USB Audio 2.0 (Direct Hardware - Bit-perfect)"
This fixes the issue where selecting the DAC device would play through
laptop speakers instead because CPAL couldn't find the device.
ALSA Device Filtering (45 → ~12 devices):
- Aggressively filter to show only useful devices for audiophiles
- Keep: default, sysdefault:CARD=, front:CARD=, hdmi:CARD=, iec958:CARD=
- Blacklist: surround* variants, usbstream:, pipewire, pulse, bare sysdefault
- Reduces 45 listed devices to ~12 actually useful ones
Add hw:CARD=XXX,DEV=0 Devices for Bit-Perfect Playback:
- Auto-generate hw: devices for each detected card
- hw: = direct hardware access without ALSA plugins (true bit-perfect)
- sysdefault:CARD= has dmix/resampling plugins (NOT bit-perfect)
- Description shows "(Direct Hardware - Bit-perfect)" to distinguish
- This fixes user's issue: DAC was stuck at 44.1kHz with sysdefault:CARD=C20
Loading Indicator:
- Show "Loading devices..." while parsing aplay -L output
- Fixes 4-5 second frozen UI on ALSA Direct backend selection
- isLoadingDevices state added to SettingsView
Stop Playback on Device Change:
- Call stop_playback() in handleBackendDeviceChange
- Prevents stuck/dead audio streams when changing output device
- Fixes: "After any config change, song in player stops working"
User can now:
1. Select hw:CARD=C20,DEV=0 for true bit-perfect to DAC
2. See loading indicator instead of frozen UI
3. Change device without breaking playback
4. Only see relevant devices (not 7 surround variants per card)
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)
ALSA Backend Fallback:
- enumerate_via_aplay() - Preferred method with real hardware descriptions
- enumerate_via_cpal() - Fallback without descriptions (frontend will translate)
- enumerate_alsa_devices() tries aplay first, falls back to CPAL on failure
- Warning log suggests installing alsa-utils if aplay fails
Edge Case Handled:
- System has ALSA installed but not alsa-utils package
- CPAL detects ALSA host → AlsaBackend available
- aplay -L command fails → fallback to CPAL enumeration
- User sees translated names instead of real hardware descriptions
- App still works, just with less friendly device names
Package Dependencies:
- Added alsa-utils as "Recommends" for .deb packages (Debian/Ubuntu)
- Added alsa-utils as "Recommends" for .rpm packages (Fedora/RHEL)
- "Recommends" = installs by default but not required (apt/dnf behavior)
- If user explicitly removes alsa-utils, app falls back gracefully
In practice alsa-utils is almost always installed with ALSA, but this
ensures we handle the edge case properly.
ALSA Backend Changes:
- Parse aplay -L output to get real hardware descriptions
- Description from hardware: "Cambridge Audio Cambridge Audio USB Audio 2.0, USB Audio"
- No more hardcoded CARD_NAMES for specific hardware
- Still uses CPAL to verify device exists and get max sample rate
- Blacklist filtering preserved (null, lavrate, samplerate, etc.)
Frontend Changes:
- Prefer device.description (from aplay -L) when available
- Falls back to getDevicePrettyName() translation only if no description
- ALSA Direct shows: "Cambridge Audio ... USB Audio, Front output / input"
- Not: "Cambridge Audio USB Front Output" (hardcoded translation)
Removed Hardcoding:
- Removed CS201 → "Cambridge Audio USB" (was specific to user's DAC)
- Removed C20 → "Cambridge Audio"
- Generic CARD_NAMES remain (NVidia, Intel HD Audio, etc.)
This makes device names work for ANY hardware, not just known cards.
Each backend should use native tools:
- ALSA: aplay -L
- PipeWire: pw-cli/pactl (future)
- PulseAudio: pactl (future)
ALSA Device Name Translation:
- Added missing patterns: front:CARD=, surround*:CARD=, iec958:CARD=
- Now shows "Cambridge Audio USB Front Output" instead of "front CS201 Output 0"
- Updated CARD_NAMES: CS201 → "Cambridge Audio USB", C20 → "Cambridge Audio"
- Surround patterns: 40→4.0, 41→4.1, 50→5.0, 51→5.1, 71→7.1
- S/PDIF (iec958) pattern added
Auto Mode Device Selection Fix (CRITICAL):
- Auto mode now only allows "System Default" (no specific device selection)
- Fixes device mismatch issue where PipeWire device names fail in ALSA
- Previous behavior caused:
* User selects DAC in Auto mode (PipeWire device name)
* Player uses legacy ALSA path
* Device not found → falls back to default
* 18+ second delay before playback starts
- Auto mode is now truly automatic - always uses System Default
This prevents cross-backend device name incompatibility. If user wants
to select specific device, they must choose PipeWire, ALSA Direct, or
PulseAudio backend explicitly.
Smart Toggle Improvements:
- DAC Passthrough now only works with PipeWire backend (uses pw-metadata)
- Auto-disables when switching to ALSA Direct, Auto, or PulseAudio
- Exclusive Mode only works with ALSA Direct backend
- Auto-disables when switching to any other backend
- Clear tooltips explain incompatibilities
Device Name Translation:
- Auto backend now loads devices and applies translation (was showing ugly names)
- ALSA Direct always applies translation via needsTranslation()
- All backends use deviceOptions with consistent translation
- Removed separate audioDeviceOptions path that skipped translation
Playback Reset:
- Stop playback when changing backend to prevent stuck/dead streams
- Fixes issue where pressing Play on current track would hang
- Player state is fully reset when backend changes
All backends (Auto, PipeWire, ALSA Direct, PulseAudio) now consistently:
1. Show translated device names
2. Auto-disable incompatible features
3. Reset to System Default device on change
4. Stop playback to prevent stream corruption
- Add DAC Passthrough auto-disable when ALSA Direct backend is selected
- DAC Passthrough toggle becomes disabled (grayed out) with ALSA Direct
- Add tooltip explaining why DAC Passthrough is disabled with ALSA Direct
- Always reset Output Device to System Default when backend changes
- Preserve existing auto-disable of Exclusive Mode with PipeWire/Auto
This ensures incompatible feature combinations are handled automatically,
respecting the user's last manual change while preventing invalid states.
Problem 1: ALSA Direct showed NO devices because aplay -L output doesn't
match CPAL device names, causing create_output_stream to fail.
Solution: Revert to CPAL enumeration but with blacklist filtering to skip
non-playback devices (null, lavrate, samplerate, speexrate, jack, oss,
speex, upmix, vdownmix).
Problem 2: Auto backend didn't apply fancy names because needsTranslation()
was too restrictive and didn't cover all ALSA device name patterns.
Solution: Simplify to: if device name starts with 'alsa_output.' it's from
PipeWire (already has friendly name), otherwise it's ALSA (needs translation).
This covers ALL ALSA naming patterns including front:CARD=, sysdefault:CARD=,
hw:, hdmi:, iec958:, etc.
Changes:
- alsa_backend.rs: Back to CPAL with blacklist filter
- SettingsView.svelte: Simplified needsTranslation() logic
Problem: When Audio Backend was set to Auto, device names showed as raw
ALSA names (hw:0,0) instead of friendly names, even though the translator
exists and works for ALSA Direct.
Root cause: Translation was only applied when selectedBackend === 'ALSA Direct'.
Auto mode can use either ALSA or PipeWire depending on system, so it needs
smart translation.
Solution: Instead of checking selectedBackend, check the device NAME itself.
If it looks like a raw ALSA device (starts with hw:, plughw:, sysdefault:CARD=,
etc.), apply getDevicePrettyName(). Otherwise (PipeWire names like 'Built-in
Audio Analog Stereo'), pass through unchanged.
This works for:
- ALSA Direct: Always translates (all devices are raw ALSA)
- PipeWire: Never translates (all devices are friendly pactl names)
- Auto: Translates only if backend chose ALSA
Changes:
- Add needsTranslation() helper to detect raw ALSA device names
- Apply translation conditionally in deviceOptions and deviceByDisplayName
- Update loadAudioSettings to use same logic
Problem 1: ALSA backend showed only 1 device or listed plugins/virtual devices
that don't work for playback (null, lavrate, samplerate, etc.).
Solution: Filter aplay -L output to only include actual playback devices:
- Hardware devices (hw:, plughw:, sysdefault:CARD=, front:CARD=)
- System defaults (default, pipewire, pulse)
- Digital outputs (hdmi:, iec958:, surround)
Problem 2: Quality badge showed file sample rate (e.g., 44.1kHz) instead of
actual hardware sample rate (e.g., 192kHz) when DAC Passthrough was active.
Solution: ExpandedPlayer now polls hardware_sample_rate every second when
DAC Passthrough is enabled and displays the real hardware rate instead of
the file metadata rate.
Changes:
- alsa_backend.rs: Add is_valid_device() filter for playback devices
- ExpandedPlayer.svelte: Poll get_hardware_audio_status every 1s
- ExpandedPlayer.svelte: Use displaySamplingRate (hardware rate when DAC on)
This ensures the quality badge accurately reflects bit-perfect playback status.
Add HTML comment at top of file to force Vite to reprocess correctly.
This fixes PostCSS trying to parse script tags as CSS due to corrupted
internal caching in Vite's Svelte plugin.
Problem 1: ALSA backend only showed CPAL hardware devices, missing virtual
devices like 'default', 'plughw', USB DACs, etc.
Solution: Use 'aplay -L' to enumerate ALL ALSA devices including:
- Hardware devices (hw:X,Y)
- Virtual devices (default, plughw, dmix)
- USB audio devices
- Network audio devices
Problem 2: UI was applying getDevicePrettyName() to all backends, causing
PipeWire's already-friendly names to be translated incorrectly.
Solution: Only apply translator for ALSA/Auto backends. PipeWire names
pass through unchanged since pactl already provides friendly descriptions.
Changes:
- ALSA backend: Use aplay -L instead of CPAL enumeration
- Frontend: Conditional translation based on selected backend
- Map deviceByDisplayName for correct reverse lookup
- Load settings with correct translation logic
This fixes both issues: ALSA now shows all devices including DACs,
and PipeWire names are no longer mangled.
Remove unused ProviderCredentials parameters from playlist import functions.
The proxy now handles all provider credentials, making these parameters
obsolete.
Changes:
- preview_public_playlist: Remove spotify_creds and tidal_creds params
- import_public_playlist: Remove spotify_creds and tidal_creds params
- Update all callers to remove None, None arguments
- Remove unused ProviderCredentials import
This fixes compilation error:
error[E0061]: this function takes 1 argument but 3 arguments were supplied
Apply getDevicePrettyName translator to all audio devices in settings.
This provides user-friendly names for ALSA devices (e.g., 'USB: Topping D50s'
instead of 'hw:0,0') while preserving PipeWire's native descriptions.
Changes:
- Import getDevicePrettyName from audioDeviceNames utils
- Apply translator in deviceOptions derived state
- Create deviceByPrettyName map for reverse lookup
- Update handleBackendDeviceChange to use pretty name mapping
- Update loadAudioSettings to display pretty names
This solves the issue where Auto and ALSA Direct backends showed
cryptic device names while PipeWire showed friendly descriptions.
User requested faster badge color changes. Previously badge only updated
on mount or hover, causing 2+ second delays.
Solution: Poll hardware status every 1 second when DAC Passthrough is
enabled. This provides instant visual feedback without affecting playback:
- Only polls when dac_passthrough is true (conditional)
- Only reads hardware status (no playback impact)
- Cleanup on component unmount
- Fast enough for instant feedback, light enough for performance
Addresses user feedback: badge updates now appear instantly instead of
requiring hover or waiting multiple seconds.
ALSA Direct Backend Implementation:
- Fully functional ALSA backend using CPAL's ALSA host
- Enumerates ALSA devices with hardware names
- Supports custom sample rates for bit-perfect playback
- Supports exclusive mode (device blocking)
- Smaller buffer size (512 samples) for lower latency in exclusive mode
- Clear error messages when device is in use
Smart Toggles in UI:
- Exclusive Mode auto-disabled with PipeWire/Auto backends
(PipeWire is multiplexed and cannot provide true exclusive access)
- Gapless Playback auto-disabled with DAC Passthrough
(bit-perfect requires recreating streams for sample rate changes)
- Toggle component now supports 'disabled' prop with visual feedback
- Tooltips updated to explain why features are disabled
- Auto-disable exclusive mode when switching to PipeWire backend
User Benefits:
- ALSA Direct now appears in backend dropdown
- True exclusive mode available with ALSA Direct
- Prevents confusing feature combinations
- Clear explanations via tooltips
- No more wondering why exclusive mode doesn't work with PipeWire
Technical Notes:
- ALSA backend uses CPAL host selection (not alsa-rs directly)
- Disabled toggles shown as grayed out with cursor: not-allowed
- Backend switching auto-adjusts incompatible settings
Problem: PipeWire was resampling 192kHz streams to 48kHz because the sink
was running at 48kHz. Creating a stream at 192kHz wasn't enough - PipeWire
would resample it down to match the sink's current rate.
Solution: Use pw-metadata to force PipeWire's global sample rate before
creating the stream:
pw-metadata -n settings 0 clock.force-rate 192000
This tells PipeWire to switch the sink to 192kHz, preventing resampling.
Technical details:
- Executes AFTER setting default sink
- Waits 300ms for PipeWire to apply the change
- Creates stream AFTER sample rate is forced
- Each new stream updates the forced rate (supports rate switching)
This ensures:
- 192kHz track -> 192kHz hardware (no resampling)
- 44.1kHz track -> 44.1kHz hardware (no resampling)
- True bit-perfect playback
Evidence: pw-top now shows ALSA sink running at requested sample rate
All API requests now go through Cloudflare Workers proxy.
User-provided credentials were collected but never used.
Removed:
- src-tauri/src/api_keys.rs (entire module)
- API Keys section from Settings UI
- ApiKeysState and related commands
- User credential parameters from providers
- Simplified DiscogsClient (removed with_user_credentials)
- Cleaned up imports and translations
Moved documentation:
- CHANGELOG-api-keys-refactor.md
- HANDOFF-MERGE.md
- MERGE-PREP.md
- POST-MERGE-CLEANUP.md
Moved to: qbz-nix-docs/feature-api-keys-refactor/
This cleanup reduces codebase by ~715 lines and removes
confusing UI that promised functionality that didn't work.
All API credentials are now managed server-side through the Cloudflare
Workers proxy. Build workflows no longer need to inject secrets into
the binary.
Removed:
- SPOTIFY_API_CLIENT_ID/SECRET from release-linux.yml
- TIDAL_API_CLIENT_ID/SECRET from release-linux.yml
- DISCOGS_API_CLIENT_KEY/SECRET from release-linux.yml
- LAST_FM_API_KEY/SHARED_SECRET from release-linux.yml
- Complete 'Inject API secrets' step from release-flatpak.yml
This completes the API keys refactor for Flathub compliance.
This major refactor achieves Flathub compliance by removing all embedded
API credentials from the binary. All API requests now go through a
Cloudflare Workers proxy for secure credential management.
New Features:
- Discogs artwork selection UI with multi-release support
- Catalog number support for audiophile libraries
- Carousel navigation for artwork options
- Release metadata display (title, year)
Technical Changes:
- Cloudflare Workers proxy for Last.fm, Spotify, Tidal, Discogs
- Database migration adds catalog_number column
- URI scheme registration (qbz://) for OAuth flows
- Rate limiting and User-Agent validation server-side
See CHANGELOG-api-keys-refactor.md for complete details.
See POST-MERGE-CLEANUP.md for removing legacy API Keys UI.
PipeWire backend was using generic OutputStream::try_from_device() which
lets PipeWire decide the sample rate, causing resampling even when
DAC Passthrough is enabled.
Now uses OutputStream::try_from_device_config() with custom StreamConfig
that forces the exact sample rate requested (e.g. 192kHz), just like
the legacy CPAL path.
Changes:
- Import CPAL config types (StreamConfig, SampleRate, etc.)
- Create StreamConfig with requested sample_rate and channels
- Use try_from_device_config() instead of try_from_device()
- Verify device supports the configuration
- Support exclusive mode with lower buffer size (512 samples)
This ensures bit-perfect playback:
- 192kHz track -> 192kHz hardware output
- 44.1kHz track -> 44.1kHz hardware output
- No resampling by PipeWire
Previously, init_device() used hardcoded 48000Hz when reinitializing
streams with backend system. This broke bit-perfect playback after
pause/resume or device changes.
Now init_device() accepts sample_rate and channels parameters and uses
the last known values from current_sample_rate/current_channels to
maintain the correct format across reinitializations.
This ensures DAC Passthrough works correctly:
- 192kHz track stays at 192kHz through pause/resume
- No unwanted resampling to 48kHz
- Bit-perfect playback maintained
Fixes apply to:
- Auto-reinitialization after sink failures
- Resume command when stream needs recreation
- ReinitDevice command (settings changes)
Root cause: We were restoring the default sink immediately after
creating the OutputStream, but the actual sink-input is only created
when playback starts (500ms+ later). By that time, we had already
restored the default to Speaker.
Solution: Don't restore the default sink at all. When user selects
a device in QBZ, it becomes the system default (expected behavior,
matches Strawberry Music Player).
Added 200ms delay after changing default sink to give PipeWire
time to process the change before creating the CPAL host.
PULSE_SINK environment variable approach was not working because
CPAL/rodio does not properly propagate it when creating streams.
New approach:
1. Save current default sink with pactl get-default-sink
2. Temporarily set default sink to target device
3. Create CPAL stream (will use current default)
4. Restore original default sink
This ensures audio routes to the selected device without permanently
changing the system default sink.
Tested approach is more reliable than PULSE_SINK env var.
Critical fix: Create fresh CPAL host AFTER setting PULSE_SINK environment variable.
Problem:
- PULSE_SINK was set in create_output_stream()
- But host was already created and connected in new()
- Host reads PULSE_SINK when it connects, not when stream is created
- Result: audio routing failed despite PULSE_SINK being set
Solution:
- Create new CPAL host in create_output_stream() AFTER setting PULSE_SINK
- This ensures host reads the environment variable when connecting
- Added verification logging to confirm PULSE_SINK is set
This should fix device selection routing to Cambridge DAC.
COMPILATION ERROR FIXED:
- audio_settings field was private
- Can't access from commands module
SOLUTION:
- Added public method: Player::reload_settings(settings)
- Encapsulation preserved
- Commands use public API
VERIFIED: cargo check passes
PROBLEMA ENCONTRADO:
1. Frontend guardaba backend_type correctamente ✅
2. Player leía settings al inicio (backend_type = None) ✅
3. Usuario cambiaba backend en UI → se guardaba en BD ✅
4. Pero Player en memoria tenía settings VIEJOS ❌
5. reinit_audio_device usaba legacy CPAL sin backend ❌
SÍNTOMAS:
- "Backend system not configured, using legacy CPAL path"
- "Device '...' not found, using default"
- Audio salía por laptop speakers, no por DAC
SOLUCIÓN IMPLEMENTADA:
1. init_device() ahora intenta backend system primero:
- Lee thread_settings.backend_type
- Si configurado, llama try_init_stream_with_backend()
- Fallback a legacy CPAL si falla
2. reinit_audio_device() recarga settings desde BD:
- Lee AudioSettings desde database
- Actualiza Player.audio_settings en memoria
- Luego llama reinit_device()
- Garantiza que Player siempre tiene config fresca
AHORA FUNCIONARÁ:
- Cambiar backend → se guarda → se recarga → se usa
- Cambiar device → se guarda → se recarga → se usa
- PULSE_SINK se setea correctamente
- Audio debe salir por Cambridge DAC
TESTING REQUERIDO:
Ir a Settings → Audio → Backend: PipeWire → Device: DacMagic Plus
Reproducir música → debería salir por DAC
Documents complete removal of unused API Keys infrastructure:
- What to delete: api_keys.rs module, Settings UI section
- What to modify: 11 files with specific line numbers and patterns
- Before/after code examples for clarity
- Verification steps and testing checklist
- ~715 lines of dead code to be removed
This cleanup should be done AFTER merge to main to avoid
conflicts with audio configuration changes in Settings.
AUTONOMOUS WORK SESSION (~45 min):
Implemented complete audio backend system from Phase 1-6
DELIVERABLES:
✅ Backend abstraction trait with 3 implementations
✅ Tauri commands for backend/device enumeration
✅ Database persistence with auto-migration
✅ Player integration with hybrid fallback
✅ Reactive UI with conditional selectors
✅ Comprehensive documentation
STATUS:
- Code compiles (cargo check + npm run check)
- 6 commits created with detailed messages
- Documentation includes architecture + testing plan
- Ready for functional testing (Phase 7)
NEXT: User testing with Cambridge DAC device
See SESSION_SUMMARY_2026-01-17.md for detailed report
PLAYER INTEGRATION:
- Added try_init_stream_with_backend() helper function
- Modified AudioCommand::Play to use backend system when configured
- Falls back to legacy CPAL path if backend_type is None
- Preserves existing behavior for users without backend config
BACKEND PRIORITY:
1. Try backend system (if backend_type is set in audio_settings)
2. Fall back to legacy CPAL direct access (backward compatible)
VERIFIED:
- cargo check passes
- Backward compatible with existing installations
- Ready for Phase 5 (UI components)
ARCHITECTURE:
- Created trait AudioBackend for unified interface
- Backends: PipeWire, ALSA (stub), PulseAudio
PIPEWIRE BACKEND (complete):
- Enumerates devices via pactl (pretty names)
- Sets PULSE_SINK env var for device routing
- Uses CPAL 'pulse'/'pipewire' device
- Does NOT change system default
- Only affects QBZ process
ALSA BACKEND (stub):
- To be implemented by Copilot
- Will provide direct hw access
- True exclusive mode
PULSE BACKEND (complete):
- Reuses PipeWire implementation
- Legacy fallback
BENEFITS:
- User can choose audio stack
- Pretty names from pactl
- Device selection only affects QBZ
- Preparation for Strawberry-style UI
Next: Tauri commands for enumeration
Logs now show:
- Device index
- Device name
- Is default
- Supported configs (channels/sample rates)
This helps identify devices when pretty names aren't clear.
PREVIOUS WRONG APPROACH (commit 212aae5):
- Used pactl to enumerate devices (PipeWire sink names)
- Tried to open those sink names with CPAL
- CPAL couldn't find PipeWire sink names → fell back to default
- Attempted workaround: change system default with set_pipewire_default_sink
- UNACCEPTABLE: Changed system-wide default, affecting all apps
ROOT CAUSE (identified by ChatGPT research):
- CPAL can open specific devices by name (research was correct)
- BUT: Name mismatch between pactl sinks and CPAL device names
- pactl returns: "alsa_output.usb-Cambridge_Audio..." (PipeWire sink)
- CPAL sees: "DacMagic Plus Analog Stereo" (user-friendly name)
CORRECT SOLUTION:
- Use CPAL for BOTH enumeration AND opening devices
- CPAL device names are consistent: enumerate → save → find → open
- No need to change system default
- Device selection only affects QBZ
CHANGES:
1. Rewrote get_pipewire_sinks() on Linux to use CPAL instead of pactl
2. Removed all calls to set_pipewire_default_sink()
3. Pass CPAL device names directly to reinit_audio_device()
4. CPAL can now find and open devices because names match
BENEFITS:
- ✅ Device selection only affects QBZ (not system-wide)
- ✅ No regresions
- ✅ No features lost
- ✅ Works exactly like librespot (Spotify client in Rust)
- ✅ Consistent with rodio/CPAL architecture
TESTING REQUIRED:
1. Select Cambridge DAC in QBZ → audio plays through Cambridge
2. Open Firefox/other app → uses its own device (unaffected)
3. Toggle devices in QBZ → changes correctly
4. Restart QBZ → restores saved device
5. DAC passthrough bit-perfect → works
ROOT CAUSE:
CPAL/Rodio (the audio library) cannot open PipeWire sinks by name directly.
CPAL only sees ALSA device names like "default", "hw:0,0", etc., not
PipeWire sink names like "alsa_output.usb-Cambridge_Audio...".
When we tried to pass the PipeWire sink name to reinit_audio_device(), CPAL
couldn't find it and fell back to system default, ignoring user selection.
SOLUTION:
1. When user selects a device, set it as PipeWire default using pactl
2. Pass device: null to reinit_audio_device() (uses PipeWire default)
3. On app startup, restore saved device as PipeWire default
This works because:
- PipeWire's "default" sink can be changed programmatically
- CPAL can successfully open "default" device
- The default sink points to the user's selected device
TRADE-OFFS:
- QBZ changes the system-wide PipeWire default sink
- Other apps will also use this sink (unless they specify their own)
- This is unavoidable with CPAL - it's the only way to select a specific
PipeWire sink from Rust without using PipeWire/ALSA APIs directly
AFFECTED FUNCTIONS:
- handleOutputDeviceChange() - Sets sink as default when user selects device
- handleExclusiveModeChange() - Restores saved sink as default before reinit
- handleDacPassthroughChange() - Restores saved sink as default before reinit
- handleGaplessPlaybackChange() - Restores saved sink as default before reinit
- handleCrossfadeChange() - Restores saved sink as default before reinit
- loadAudioSettings() - Restores saved sink as default on app startup
Documents all changes in feature/api-keys-refactor branch:
- Removed all embedded API credentials (Last.fm, Spotify, Tidal, Discogs)
- Implemented Cloudflare Workers proxy for credential management
- Added Discogs artwork selection UI with multi-release support
- Added catalog number support for audiophile libraries
- Database migrations and schema changes
- Security improvements and Flathub compliance
Ready for merge to main after audio configuration changes stabilize.
- Added carousel navigation for image options (4 per page)
- Show page indicator and navigation buttons only when >4 images
- Homogenized button sizes (Change Cover now matches Fetch from Discogs)
- Fixed Save functionality with better error logging
- Reset Discogs state when modal closes
- Import ChevronLeft/ChevronRight icons for carousel navigation
Users can now navigate through all available artwork options
and successfully save selected images from Discogs.
- Added /release/{id} endpoint to Cloudflare proxy for detailed release info
- Modified search_artwork_options to fetch full image sets from top 2 releases
- Interleave images: up to 4 from release #1, 4 from #2, 2 from others
- Added release_title and release_year metadata to each image option
- UI now displays release title and year for each artwork option
- Better image diversity and context for users
Users now see which release variant each artwork comes from,
making it easier to choose the correct edition.
- Added catalog_number field to LocalTrack and LocalAlbum models
- Extract catalog_number tag from audio files using lofty
- Database migration to add catalog_number column to local_tracks table
- Modified Discogs search to prefer catalog number over artist/album
- Updated UI to display catalog number in album details
- Pass catalog_number to discogs_search_artwork command
For audiophile users with well-tagged libraries, catalog numbers
provide more precise Discogs search results than artist + album.
- Modified search_artwork_options to return unique images from different releases
- Only take one image per release (prefer cover_image, fallback to thumb)
- Use HashSet to track and filter duplicate URLs
- Process up to 20 results to get more diverse options
- Adjusted grid layout from minmax(100px, 1fr) to minmax(80px, 1fr) to fit at least 4 items per row
Backend:
- Add DiscogsImageOption struct for artwork options
- Add discogs_search_artwork command to search multiple images
- Add discogs_download_artwork command to download selected image
- Extend DiscogsClient with search_artwork_options() method
- Extend DiscogsClient with download_artwork_from_url() method
- Register new commands in lib.rs
Frontend:
- Add Discogs image selection to album edit modal
- Add 'Fetch from Discogs' button with Discogs logo
- Display grid of artwork options from Discogs search results
- Allow user to select preferred artwork option
- Download and save selected artwork on Save
- Add comprehensive CSS styling for Discogs UI elements
- Adjust Discogs logo color filter for proper contrast
User can now click 'Fetch from Discogs', browse multiple artwork
options, select one, and save it as the album's cover art.
PROBLEM:
When selecting an audio device in QBZ settings, the app was changing
the system-wide PipeWire default sink, affecting all applications.
ROOT CAUSE:
handleOutputDeviceChange() was calling set_pipewire_default_sink(),
which changes the PipeWire default for the entire system.
FIX:
Removed set_pipewire_default_sink() call. The backend reinit_audio_device()
already handles opening a specific device for QBZ without changing the
system default.
Now QBZ uses the selected device independently from the system default.
PROBLEM:
When user selected a specific audio device (e.g., Cambridge Audio DAC),
audio would always play through system default device (laptop speakers)
instead of the selected device.
ROOT CAUSE:
All calls to reinit_audio_device() were passing device: null instead of
the actual selected device name. When device: null is passed, the Player
falls back to system default regardless of user selection.
Affected functions:
- handleOutputDeviceChange() - Primary bug, selected device ignored
- handleExclusiveModeChange() - Reset to default when toggling
- handleDacPassthroughChange() - Reset to default when toggling
- handleGaplessPlaybackChange() - Reset to default when auto-disabling DAC
- handleCrossfadeChange() - Reset to default when auto-disabling DAC
FIX:
Created getCurrentDeviceSinkName() helper that:
- Returns the internal sink name for selected device
- Returns null only for "System Default" selection
- Used consistently across all audio setting changes
SECONDARY CHANGES:
Improved DAC Passthrough warning messages in AudioOutputBadges:
- "ERROR: PipeWire is resampling" instead of generic warning
- Clearer tooltip guidance for fixing resampling issues
- Better distinction between active/warning/disabled states
This ensures device selection persists across all audio setting changes
and provides clearer feedback when bit-perfect playback is compromised.
Tooltip improvements:
- Consolidate duplicate tooltips into single unified tooltip
- Show device info + DAC status + sample rate in one place
- Remove native 'title' attributes that were causing conflicts
- Add visual indicators (colored dots) for setting states
- Display resampling warning with actual rates when detected
- Better structured tooltip with sections
Mutual exclusion enforcement:
- Validate settings on load in loadAudioSettings()
- Auto-disable Gapless and Crossfade if DAC Passthrough is enabled
- Prevents invalid state from persisted settings
This fixes the issue where users could have incompatible settings
active simultaneously after app restart.
- Update DISCOGS_API_URL to point to proxy endpoint
- Remove embedded CONSUMER_KEY and CONSUMER_SECRET constants
- Simplify DiscogsClient to only handle HTTP requests
- Update search_release() to use proxy /search endpoint
- Update search_artist() to use proxy /search endpoint
- Update download_image() to use proxy /image endpoint
- Add User-Agent 'QBZ/1.0.0' for proxy validation
- Maintain backward compatibility with with_user_credentials (no-op)
AudioOutputBadges was importing currentTrack from playerStore, which doesn't
export a reactive store. This caused the app to crash with a 500 error.
Solution: Pass samplingRate as a prop from NowPlayingBar instead of trying
to import track data directly. This matches the existing pattern used by
other components like QualityBadge.
Backend changes:
- Add audio_diagnostics module to read actual hardware sample rate from /proc/asound
- New command get_hardware_audio_status() parses hw_params for real-time monitoring
- Add glob dependency for file pattern matching
Frontend (AudioOutputBadges):
- Implement 3-state DAC badge system:
- Green: DAC passthrough working correctly (rates match)
- Yellow: DAC passthrough ON but resampling detected (warning)
- Gray: DAC passthrough OFF (intentionally disabled)
- Dynamic tooltips showing actual hardware sample rate
- Compare file sample rate vs hardware sample rate
- Increase tooltip z-index to 9999 to prevent occlusion issues
- Add pointer-events: none to tooltip to prevent interaction issues
Frontend (SettingsView):
- Replace hardcoded "192 kHz" with dynamic hardware sample rate
- Load and display actual hardware audio status
- Show format details (e.g., S32_LE) when available
- Display "No active playback" when no audio is playing
- Add muted styling for inactive state
Frontend (QualityBadge):
- Add native tooltip showing tier and format
- Add cursor: help to indicate interactivity
i18n:
- Add "noActivePlayback" translations (EN/ES)
This allows users to verify bit-perfect playback is working and detect
resampling issues that would compromise audio quality.
- Update LASTFM_API_URL to point to proxy endpoint
- Remove MD5 signature generation (proxy handles it)
- Remove api_key and api_secret from LastFmClient (proxy manages credentials)
- Simplify client to only handle session_key
- Update get_token() to return (token, authUrl) tuple from proxy
- Update all methods (get_session, scrobble, update_now_playing) to use proxy
- Add User-Agent header 'QBZ/1.0.0' for proxy validation
- Update bootstrap.ts to skip credential restoration (proxy handles it)
- Maintain backward compatibility with set_credentials as no-op
Remove isExternal requirement for DAC Passthrough badge activation.
The badge now lights up when DAC Passthrough setting is enabled,
regardless of whether the device is detected as external or internal.
This fixes the issue where the badge would remain off even when
DAC passthrough was working (confirmed by 192kHz reaching hardware).
- Remove DEFAULT_API_SECRET constant and get_api_secret() function
- Update Default impl to require user-provided secret
- Update has_embedded_credentials() to only check API key
- API secret will be handled by Cloudflare Workers proxy
Add auto-disable logic to prevent incompatible settings from being enabled simultaneously:
Frontend (SettingsView.svelte):
- DAC Passthrough ON → auto-disables Gapless Playback and Crossfade
- Gapless Playback ON → auto-disables DAC Passthrough
- Crossfade > 0 → auto-disables DAC Passthrough
- Added handleGaplessPlaybackChange() and handleCrossfadeChange() handlers
- Modified handleDacPassthroughChange() to disable incompatible settings
Backend (player/mod.rs):
- Only recreate OutputStream on format change when DAC passthrough is enabled
- When DAC passthrough is OFF: reuse existing stream for gapless transitions
- When DAC passthrough is ON: recreate stream for bit-perfect playback
- Added detailed logging for stream recreation decisions
This fixes the issue where Gapless Playback was enabled but gaps still occurred
due to DAC passthrough forcing stream recreation on sample rate changes.
The previous implementation tried to map ALSA device names (from cpal)
to PipeWire descriptions, but the naming schemes are completely different:
- cpal returns names like "plughw:1,0"
- pactl returns sink names like "alsa_output.usb-Cambridge_Audio_..."
This fix changes the approach:
1. Use PipeWire sinks directly for the device dropdown (already filtered
to real outputs and have friendly descriptions like "DacMagic Plus")
2. Store the PipeWire sink name when user selects a device
3. Set the PipeWire default sink using pactl when device is selected
4. Use rodio's default device (which follows PipeWire's default)
This ensures users see 4-5 meaningful devices with friendly names
instead of 30+ raw ALSA device names.
Backend changes:
- Add set_pipewire_default_sink command (pactl set-default-sink)
- Register new command in lib.rs
Frontend changes:
- Use pipewireSinks directly for device dropdown
- Display sink description (friendly name)
- Store sink name (for pactl)
- Call set_pipewire_default_sink when device changes
- Remove unused AudioDevice interface and getDevicePrettyName import
The play_data function was calling decode_with_symphonia which decoded
the entire audio file (271MB+) just to extract sample_rate and channels.
This caused 30-35 second delays between download complete and playback.
New extract_audio_metadata function:
- For FLAC: uses rodio decoder (reads headers only)
- For isomp4: uses symphonia probe to read codec_params without decoding
This restores the fast playback we had before.
vicrodh