BREAKING CHANGE: App ID changed from com.blitzkriegfc.qbz to com.blitzfc.qbz
Changes:
- Renamed Flatpak App ID and all metadata files
- Fixed MPRIS name: qbz_nix → qbz
- Added NAS support permissions: /mnt, /media, /run/media
- Updated CI workflow for new filenames
- Updated tauri.conf.json bundle identifier
Flatpak features:
- Runtime detection (/.flatpak-info check)
- Automatic data migration from old App ID
- Migrates config, data, and cache directories
- Non-destructive (preserves old directories)
- Runs on startup before any other initialization
- New Settings section (Flatpak-only)
- Filesystem permission guidance
- Copy-paste ready commands for NAS/SSHFS
- Professional UX per Flatpak best practices
Migration is automatic and transparent for existing users.
Features:
- New Settings section that appears ONLY when running in Flatpak
- Displays clear instructions for granting filesystem permissions
- Copy-paste ready commands for common scenarios (NAS, SSHFS)
- Explains Flatseal as GUI alternative
- Professional, defensive UX per prompt requirements
The section is completely hidden when not in Flatpak.
Users see actionable guidance with examples.
Features:
- Flatpak runtime detection (/.flatpak-info check)
- Automatic migration of user data from old App ID to new ID
- Config: ~/.config/com.blitzkriegfc.qbz → ~/.config/qbz
- Data: ~/.local/share/com.blitzkriegfc.qbz → ~/.local/share/qbz
- Cache: ~/.cache/com.blitzkriegfc.qbz → ~/.cache/qbz
- Migration runs on startup before any other initialization
- Old directories are preserved (manual cleanup required)
- Tauri commands for frontend integration:
- is_running_in_flatpak()
- get_flatpak_help_text()
Migration is non-destructive and idempotent.
Changes:
- Renamed Flatpak manifest, desktop file, and AppStream metainfo
- Updated App ID in all metadata files
- Fixed MPRIS name: qbz_nix → qbz
- Added NAS support permissions: /mnt, /media, /run/media
- Updated CI workflow to use new filenames
- Updated tauri.conf.json bundle identifier
BREAKING CHANGE: Users will need to migrate data from old App ID directories
Data migration will be implemented in next commit
Implements native ALSA hw: device support for bit-perfect playback with:
- Direct PCM access bypassing PipeWire/Pulse resampling
- Automatic format detection (S16_LE, S24_LE, S32_LE, FLOAT_LE)
- Optional hardware mixer volume control via ALSA
- HW badge indicator for ALSA Direct mode
- DAC badge improvements with device name tooltip
- Lightweight hardware status polling for sample rate verification
Database migrations are safe for existing users (1.1.5+):
- alsa_hardware_volume column added with NULL-safe handling
- Defaults to disabled for backwards compatibility
UI improvements:
- Improved ticker animation on album cards and tooltips
- Badge tooltip shows actual device name with scrolling
- Fixed badge width consistency across quality types
Changes:
- Reduced speed from 80 to 40 pixels per second for better readability
- Added typewriter-style animation with pauses and fast return
- Slow scroll (50% of time), pause, then quick return (10% of time)
IMPORTANT FOR MERGE: If this conflicts with other branches modifying the same animation, THIS VERSION should be kept as it provides better UX (tested and approved by user).
Adds scrolling animation when device names overflow tooltip width, borrowed from AlbumCard component pattern. Also fixes accessibility warning by adding role and aria-label to badge container.
The 1s polling of get_hardware_audio_status was logging every second:
"Hardware audio status: 192000Hz, format: Some("S32_LE")"
This is useful for debugging but too noisy for normal usage.
Change:
- log::info! → log::debug! (line 52)
Result:
- Console stays clean during playback
- Log still available with RUST_LOG=debug for debugging
- Polling continues working, just silently
This reverts the event-driven approach (9242b95) and restores lightweight
polling, but ONLY for hardwareStatus.
Problems with event-driven approach:
1. False yellow warnings: hardwareStatus had stale data from previous song
- Hardware: 88200 Hz (correct)
- Cached hardwareStatus: 44100 Hz (from previous song)
- Badge logic: 88.2 !== 44.1 → WARNING (false positive)
2. Lost device name: outputStatus never updated after mount
- loadStatus() only called once on mount
- outputStatus.device_name became stale
- Badge tooltip showed "Default" instead of "hw:4,0"
Solution - Lightweight polling (best of both worlds):
- Call loadStatus() once on mount (loads everything)
- Poll ONLY hardwareStatus every 1s (no device enumeration)
- get_hardware_audio_status just reads /proc/asound (very cheap)
- No CPAL device enumeration (no console spam)
- No get_pipewire_sinks calls (no ALSA errors)
Benefits:
- Badge always shows current hardware status (accurate resampling detection)
- Device name preserved (loaded once, doesn't change)
- Zero console spam (no device enumeration)
- Very lightweight (just read /proc/asound file)
- ~1000x cheaper than full loadStatus() polling
This gives us accurate bit-perfect validation without the overhead.
Changed hardware status polling from continuous (every 1s) to event-driven
(only when sample rate changes).
Rationale:
- Hardware sample rate ONLY changes when playing new song with different rate
- Continuous polling was overkill - 3600 unnecessary calls per hour
- If system is properly configured, status doesn't change mid-song
- Polling was originally added for "instant feedback" but wastes resources
Changes:
- Removed setInterval polling (lines 162-171)
- Added $effect that watches samplingRate prop changes
- Only calls get_hardware_audio_status when:
* samplingRate changes (new song or format change)
* Using DAC Passthrough or ALSA Direct (bit-perfect modes)
- Tracks previousSamplingRate to detect actual changes
Benefits:
- Zero backend calls during playback (unless rate changes)
- Still validates bit-perfect when it matters (new sample rate)
- Massive reduction in /proc/asound reads
- Better battery life, lower CPU usage
- Same UX - badge updates when song changes
Testing plan:
- Play songs with same sample rate → zero backend calls
- Play songs with different rates → update on each rate change
- Verify badge still shows correct status
- If issues found, can revert to 1s polling
The (() => { if (outputStatus?.is_playing) loadStatus(); }) was
causing massive console spam ("spam masivo") that continued even after
removing mouse from badge.
Root causes:
1. was cherry-picked from feature/ui-fixes for badge auto-update
2. But now we have 1s polling that already keeps data fresh
3. outputStatus object was being mutated/recreated frequently
4. This triggered repeatedly, calling loadStatus()
5. Each loadStatus() enumerated 12 CPAL devices + PipeWire sinks
6. CPAL enumeration causes ALSA errors: "Cannot get card index for 0"
Previous commit (0c3ca16) removed loadStatus() from onmouseenter, but
spam continued because kept triggering during playback.
Solution:
- Removed completely (lines 150-156)
- loadStatus() now only called once on mount
- Polling interval (1s) only calls get_hardware_audio_status
- get_hardware_audio_status just reads /proc/asound (no device enumeration)
Result:
- Console spam eliminated completely
- Badge still updates every 1s via polling
- Zero CPAL/ALSA enumeration during playback
- Massive reduction in CPU/battery usage
Root cause:
- onmouseenter was calling loadStatus() which enumerates ALL devices
- loadStatus() calls: get_audio_output_devices (12 devices), get_pipewire_sinks, get_hardware_audio_status
- Each hover triggered 3 expensive backend calls + CPAL/ALSA enumeration
- User reported "spam masivo en la consola" when hovering badge
Solution:
- Removed loadStatus() call from onmouseenter (line 180)
- Only set isHovering = true to show tooltip
- Polling interval (1s) already keeps hardware status fresh
- Tooltip now shows cached data instead of triggering new enumeration
Impact:
- Hover now instant with zero backend calls
- Console spam eliminated
- Battery/CPU usage reduced significantly
- Tooltip still shows current data via 1s polling
Documents known limitations discovered during ALSA Direct testing:
1. Seekbar Performance with Hi-Res Audio
- 10-20s delay when seeking with >96kHz sample rates
- Root cause: decoder must decode all samples from start to seek position
- Workaround: Use prev/next track buttons (instant)
- Future: Byte-level seeking planned for next release
2. First Sample Rate Change
- Brief delay on first large rate change (e.g., 88.2→44.1 kHz)
- Hardware stabilization time - normal behavior
- Subsequent changes are smooth
3. ALSA Direct Mode
- Bit-perfect but exclusive access (blocks other apps)
- Hardware volume control experimental
- Some DACs don't support hardware mixer
4. PipeWire DAC Passthrough
- Requires PipeWire configuration for rate switching
- Link to documentation
This section helps users understand limitations and workarounds, setting
proper expectations for bit-perfect audio modes.
This fixes the 2-5s delay when rapidly changing tracks. The drain() was
blocking for hundreds of milliseconds waiting for the PCM buffer to empty,
even when the user was skipping tracks.
Root cause (playback_engine.rs:136):
- drain() was called ALWAYS after playback loop ended
- drain() blocks until PCM buffer is completely empty (~125-500ms)
- When user skips tracks, we don't need elegant buffer drain
- This caused 'need to wait 2-5s' or 'double click next' behavior
Solution:
- Added 'natural_end' flag to track WHY playback stopped
- natural_end=true: Song finished normally → DO drain (elegant end)
- natural_end=false: User skipped/paused → SKIP drain (instant response)
Benefits:
- Track changes now instant (no 2-5s wait)
- Songs that finish naturally still drain properly (no clicks/pops)
- Maintains audio quality while improving responsiveness
Testing:
- Rapid track skipping should be instant
- Songs that play to end should have smooth transition
- No audio artifacts (clicks/pops) in either case
This addresses the 'slow playback' issue on first large sample rate transition
(e.g., 88.2kHz → 44.1kHz). The hardware needs extra time to stabilize when
changing sample rates significantly, especially on cold start.
Root cause:
- First transition 88.2→44.1 kHz: song started slowly
- Subsequent identical transitions: clean
- Affects both ALSA Direct and PipeWire DAC Passthrough
- Hardware 'warm-up' time needed for large rate changes
Fix:
- Increased delay from 50ms to 150ms (still imperceptible to user)
- Gives DAC hardware more time to stabilize clock after rate change
- Extra time especially critical for downward transitions (88.2→44.1)
Testing needed:
- Verify first 88.2→44.1 transition is now clean
- Ensure 150ms delay doesn't create noticeable gap
- Check all other transitions still work
The badge was always showing 'Default' regardless of the selected device because
thread_state.set_current_device() was only being called in the legacy CPAL path,
not in the backend system path (PipeWire DAC, ALSA Direct).
Root cause:
- Lines 801-805: Backend system creates stream but never sets current_device
- Lines 847, 883: Only legacy CPAL path was setting device name from CPAL device.name()
- UI badge calls get_audio_output_status() which returns player.state.current_device()
- current_device was None/outdated when using backend system
Fix:
- After successful stream creation (line 897), read output_device from settings
- Set thread_state.current_device with the device name from settings
- Fallback to 'Default' string if output_device is None
- Now badge shows: 'hw:4,0', 'DacMagic Plus Analog Stereo', etc.
Testing:
- ALSA Direct: Should show 'hw:4,0' or configured device
- PipeWire DAC: Should show 'DacMagic Plus Analog Stereo' or selected sink
- System Default: Should show 'Default'
This is an integral fix that resolves the multi-second gap when changing
sample rates, without breaking bit-perfect modes (DAC Passthrough, ALSA Direct).
Root causes identified:
1. Missing ALSA Direct format change detection - stream wasn't recreated
2. Unnecessary CPAL device enumeration before backend system - added latency
3. Decoder started before stream fully initialized - seekbar advanced without audio
Changes made:
1. Added ALSA Direct to format change detection (line 773-775)
- Stream now recreates on sample rate change for ALSA Direct
- Maintains bit-perfect playback like DAC Passthrough
2. Restructured device initialization to skip CPAL enumeration (lines 798-893)
- Backend system (PipeWire DAC, ALSA Direct) checked FIRST
- CPAL enumeration only used as fallback for legacy path
- Eliminates "Device 'hw:4,0' not found" warning for ALSA Direct
3. Added 50ms delay after stream creation (line 904-906)
- Ensures stream is fully initialized before decoder starts
- Prevents seekbar advancing without audio output
- Small enough not to be noticeable, large enough to prevent gap
Testing needed:
- ALSA Direct: 192→96→192→44.1→48→88.2 kHz transitions
- PipeWire + DAC Passthrough: Same sample rate transitions
- System Default: Verify gapless still works
- Verify bit-perfect modes still work (no resampling)
Add effect that reloads audio settings and status when playback begins, ensuring DAC/EXC badges show correct state without requiring hover interaction.
The current track is now marked as active even when paused, matching standard player behavior. This fixes the issue where after app restoration, the loaded track doesn't appear active until user interaction.
Changed: Remove isPlaybackActive condition from track active state logic in AlbumDetailView and PlaylistDetailView.
1. Change hardware volume to visible help text (like Offline settings)
- More critical info should be always visible
- Clearer explanation of experimental nature
2. Add blue HW badge for ALSA Direct mode
- Replaces DAC badge (mutually exclusive)
- Blue color simulates audio equipment LED
- Shows 'Hardware Direct: Bit-perfect ALSA' in tooltip
- Displays device name and sample rate
- Only visible when: ALSA Direct + hw plugin
3. Gapless logic already correct
- Only restricts gapless with DAC Passthrough (PipeWire)
- ALSA Direct can do gapless (same sample rate)
- Note: Different sample rates need investigation
Backend returns 'hw (Direct Hardware)' (lowercase) but UI was comparing with 'Hw (Direct Hardware)' (uppercase). Fixed all occurrences to use lowercase.
- Add alsa_hardware_volume to AudioSettings interface
- Add Tauri command set_audio_alsa_hardware_volume
- Add checkbox in Settings (visible only for ALSA Direct + Hw plugin)
- Checkbox disabled by default for maximum compatibility
- Clear tooltip explaining experimental nature and risks
- Add hardware_volume parameter to PlaybackEngine::new_alsa_direct()
- Update all three call sites in player.rs to pass alsa_hardware_volume setting
- Implement conditional volume control: hardware mixer or DAC/amplifier
- Add device_id() getter to AlsaDirectStream for mixer access
- Hardware volume disabled by default for maximum compatibility
Added set_hardware_volume() to AlsaDirectStream:
- Tries common mixer control names (Master, PCM, Speaker, Headphone, Digital)
- Returns error if DAC doesn't support mixer (doesn't break playback)
- Stores device_id in struct for mixer access
This enables bit-perfect volume control via DAC hardware when supported.
Falls back gracefully if not supported.
PROBLEM: App crashed on startup with existing databases:
'table audio_settings has no column named alsa_hardware_volume'
CAUSE: ALTER TABLE with 'NOT NULL' constraint fails on SQLite migrations.
FIX:
- Removed NOT NULL from ALTER TABLE statement
- Handle NULL values with unwrap_or(0) in get_settings()
- Defaults to false (disabled) for old databases
Now works with both new and existing databases.
Preparation for hybrid volume control (B+C option):
- New field: alsa_hardware_volume: bool (default: false)
- Database schema updated with migration support
- Setter/getter methods added
When enabled, will attempt to control DAC volume via ALSA mixer.
When disabled (default), in-app volume control is disabled for maximum
compatibility (user controls volume on DAC/amplifier).
PROBLEM: Hardcoding S32_LE only worked for Cambridge Audio DAC, not generic.
SOLUTION: Auto-detect best format at runtime:
- Try formats in priority order: FloatLE > S32LE > S24LE > S16LE
- Store detected format in AlsaDirectStream struct
- write() auto-converts from i16 based on detected format:
* FloatLE: i16 -> f32 (normalize to -1.0..1.0)
* S32LE: i16 -> i32 (bit-perfect: shift left 16 bits)
* S16LE: i16 -> i16 (no conversion)
Now works with any DAC regardless of supported formats.
PROBLEM: Cambridge Audio DAC only supports S32_LE format, not FloatLE.
Previous code failed with 'Invalid argument (22)' when trying to set FloatLE.
SOLUTION:
- alsa_direct.rs: Changed format from FloatLE to S32_LE
- alsa_direct.rs: Changed write() to accept i32 samples instead of f32
- playback_engine.rs: Convert i16 to i32 using bit-perfect left shift:
i32 = (i16 as i32) << 16
This maintains full bit-perfect precision while using hardware-supported format.
PROBLEM: Original code tried to collect() entire audio source into memory
before playback, causing 600+ MB allocations for 192kHz tracks and silent
failures.
SOLUTION: Stream samples in 8192-frame chunks:
- Read chunk from source iterator
- Convert i16 to f32
- Write to ALSA immediately
- Repeat until end of stream
This reduces memory usage from 600+ MB to ~300 KB per chunk and fixes
the no-audio issue.
- Replace Sink with PlaybackEngine abstraction throughout player
- Update StreamType to use Arc<AlsaDirectStream> for sharing
- Adapt all player commands (Play, Pause, Resume, Seek, Stop, SetVolume, ReinitDevice)
- Add as_any() trait method for backend downcasting
- Fix all type mismatches and compilation errors
- Compilation successful with 0 errors, 30 warnings
- Remove await from onMount (not async)
- Use .then() chain for proper async handling
- Initialize activeTab from preferences on mount
- Fixes tab order not persisting
- Fixes custom icon not displaying
cx
Removed continuous sync that was overriding user tab clicks.
Now only syncs activeTab with currentTab on initial mount to respect
configured first tab, then allows normal tab navigation.
cp
- Extended navigationStore with FavoritesTab state tracking
- Added setFavoritesTab() to push tab changes to history
- Modified navigateTo() to support favorites sub-navigation
- Wired handleTabChange() to call setFavoritesTab()
- Synced activeTab with navigation store via currentTab prop
- Back button now returns to correct Favorites tab
cp
- Detect missing icon_background column in favorites_preferences table
- Add ALTER TABLE migration to preserve existing user data
- Apply migration in both FavoritesPreferencesStore::new() and create_table()
cx
- Change top from 0 to -24px to account for container padding
- Ensures nav bar reaches top edge when scrolling
- clearCurrentSearch already collapses search correctly
cp
- Remove negative top margin from .favorites-nav (was -24px, now 0)
- Update clearCurrentSearch() to collapse search when cleared
- Add hover state to clear button for better UX
cp
- Add 3 more solid colors (cyan, rose, slate) for total of 11 solids
- Keep only sunset gradient (1 gradient)
- Change grid from 8 to 12 columns
- Ensures all colors fit in single row
cp
- Reduce modal width from 920px to 736px (80% of original)
- Center modal with 140px left offset (half sidebar width)
- Reduce color swatches from 40px to 30px
- Reduce color-grid gap from 8px to 4px
- Fix icon-preset button justify-content typo
- Swatches now properly fill single row
cp
- Changed modal columns from 50/50 to 65/35 split
- Reduced color picker grid gaps and increased density (8 columns)
- Adjusted color swatch border radius for consistency
cp
- Remove filter from backend selector dropdown
- Remove auto-switch logic from ALSA Direct to Auto
- Allow user to test if CPAL can actually open hw: devices
- If this works, we can skip alsa-rs implementation
- If it fails, we'll need to implement direct alsa-rs approach
- Add alsa 0.9 as Linux-only dependency
- Will replace CPAL-based ALSA backend with direct alsa-rs implementation
- Required to properly access hw:X,Y devices for bit-perfect playback
- Create FavoritesEditModal with preset icon grid
- Add custom image upload button
- Add tab reorder UI with up/down buttons
- Integrate edit button in Favorites page header (top-right)
- Add i18n keys for EN and ES
- Wire modal save handler to backend
cc
- Create favorites_preferences.rs with FavoritesPreferences struct
- Add database table (custom_icon_path, custom_icon_preset, tab_order)
- Implement State wrapper and Tauri commands
- Register state and commands in lib.rs
- Default preset: heart, default order: tracks/albums/artists/playlists
cc
- Replace native title with custom tooltip similar to DAC/EXC badges
- Add hover state and styled tooltip with context info
- Add debug logs to investigate onClick callback issue
cp
- Added $effect to reload preferences each time SettingsView is visible
- Fixes autoplay mode not persisting when navigating away and back
- Settings view doesn't unmount, so onMount only runs once per session
cp
- 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
vicrodh