MusicLib 1.71

MusicLib Release Notes

---

1.71 — 2026-05-18

Bug Fixes

• Fixed device list returning empty and wrong device ID being extracted in the Mobile Panel and Settings dialog when using kdeconnect-cli ≥23.08. That release added on IP via TRANSPORT between the device ID and the status parenthesis, breaking the previous regex. Both parsers are now format-agnostic and work with all kdeconnect-cli versions.

---

Improvements

• All direct acquire_db_lock / release_db_lock calls in shell scripts are now routed through the established wrapper functions, eliminating inconsistent call patterns and ensuring uniform lock timeout and error handling across all scripts.
• Build-time DSV schema assertion (step b): CMake now verifies the DSV schema definition at configure time, catching schema mismatches before a binary is produced.
• Test suite added for musiclib_init_config.sh, covering the config initialisation paths exercised during first-run setup and --restore-lastplayed.

---

Documentation

• MUSICLIB_USER_MANUAL.md: updated setup section and FAQ music player wording for v1.70 generalisation.
• README.md: updated MPRIS2 migration notes and player-agnostic setup instructions.

MusicLib 1.70

MusicLib Release Notes

---

1.70 — 2026-05-13

New Features

MPRIS2 Player Migration
Replaced all Audacious-specific integration (audtool, Song Change plugin, musiclib_audacious.sh) with a player-agnostic MPRIS2 layer. Playback tracking is now handled by musiclib-mpris.service, a systemd user daemon that listens for PropertiesChanged signals on the MPRIS2 D-Bus interface. The daemon fires musiclib_player_event.sh on each play/pause/stop transition, matching the behavior previously provided by the Audacious Song Change plugin. Any MPRIS2-compatible player (Audacious, Strawberry, Clementine, VLC, etc.) now works with MusicLib without reconfiguration. musiclib_audacious.sh and all Audacious helper stubs have been removed.

Playlist Position / Length in Conky Output
musiclib_player_event.sh now writes playlistposition.txt and playlistlength.txt to ~/.local/share/musiclib/data/conky_output/ on every player event, enabling Conky widgets to display current position within the active playlist without an additional D-Bus query.

regen_task_list.sh
New script regenerates deliverables/TASK_LIST.md by scanning all task notes in deliverables/task_notes/ for open items marked with [ ]. Allows task tracking to remain distributed in per-task note files while producing a consolidated view on demand.

---

Improvements

• musiclib_utils.sh has been split into focused modules (musiclib_utils_core.sh, musiclib_utils_tag_functions.sh, etc.) and the compatibility re-exporter shim has been removed. All 12 sourcing scripts updated to source the appropriate module directly.
• --load-player replaces --load-audacious in musiclib_smartplaylist.sh. The flag now dispatches on player identity via D-Bus, sending the generated playlist to whichever MPRIS2 player is active rather than hard-coding Audacious.
• refresh-player-playlists subcommand replaces refresh-audacious-only in musiclib_mobile.sh. Reloads the active MPRIS2 player's playlist queue from generated .m3u files.
• All remaining audtool QProcess spawns in the GUI (refreshNowPlaying(), refreshRating()) replaced with direct D-Bus calls via QDBusInterface, eliminating the external-process overhead and dependency on the audtool binary.
• MUSICLIB_SYSTEM_CONFIG_DIR and MUSICLIB_BIN_DIR environment overrides are now honoured in the C++ layer (CLI dispatcher and GUI). Setting these variables allows the application to run fully from the development tree without installing to /usr/lib/musiclib/.
• MUSICLIB_SYSTEM_CONFIG_DIR is also honoured in the shell load_config path; KID3_CMD and SCROBBLE_THRESHOLD_PCT are now exported so child scripts inherit them without re-sourcing the config.
• Star PNG images and bitrate display are now populated at application init and on every player event, not only after explicit user action.
• CMake install() rule added for star rating PNG assets (config/gui/star_ratings/).

---

Bug Fixes

• Fixed scrobble check progress being reset on Paused→Playing transitions for the same track. Progress is now carried across pause/resume cycles, and the scrobble handler fires correctly on the Paused→Playing transition rather than requiring a new track start.
• Fixed regen_task_list.sh array initialization (=()) to prevent set -u unbound-variable failures on bash 5.3.
• Removed obsolete weather integration from extract_metadata() in musiclib_player_event.sh; the code was unreachable and caused spurious log output.
• Removed duplicate log writes in musiclib_player_event.sh that produced redundant entries in the player event log on every track change.

---

Documentation

• ADR-001 through ADR-009 added to docs/adr/: records architectural decisions covering the MPRIS2 migration, musiclib_utils.sh split, tag schema design, and build system conventions.
• MUSICLIB_USER_MANUAL.md: updated setup steps, player integration section, and CLI examples for MPRIS2 migration; removed Audacious Song Change plugin references.
• BACKEND_API.md: updated BACKEND_API_VERSION to 1.70; documented MPRIS2 daemon interface, D-Bus call patterns, and updated script-to-function cross-references.
• SCRIPTS_SUMMARY.md and DEPLOYMENT_PATHS.md: updated for removed scripts (musiclib_audacious.sh), new modules from utils split, and new conky_output files.

MusicLib 1.62

Addressed bugs affecting MusicLib setup across maintenancepanel, cli_utils, command_handler, and musiclib_init_config.sh.
Updated user manual to reflect changes.

MusicLib 1.61

Bug fixes: corrected CMake install destination for extension-less config files (e.g. k3brc) missed by FILES_MATCHING glob, and fixed KDE service menu install path to the correct KF6 location (share/kio/servicemenus/). Fixed Audacious library path detection in musiclib_init_config.sh to use a proper if block with a confirmation message, and corrected SERVICEMENU_SRC to the KF6 path.

MusicLib 1.60

Tag Schema System
Replaced the tag exclusion list with a declarative two-tier allowlist schema (tag_schema.conf). Schema defines [db_written] frames (sourced from the musiclib DB and written fresh on rebuild) and [file_preserved] frames (read from the file before strip and restored unchanged). Supports kid3 unified names, explicit TXXX descriptions, and raw ID3v2 frame codes. Tag functions in musiclib_utils_tag_functions.sh now use load_tag_schema() and an allowlist-driven is_frame_allowed() in place of the old exclusion-list logic.

Tag Backup & Restore

• Per-file tag backups are now retained for 30 days after a successful rebuild, enabling recovery from unexpected frame loss or value corruption discovered after the fact.
• New --keep-backup flag for tagclean and tagrebuild overrides the default (which previously deleted backups on success).
• New musiclib_tagrestore.sh script: locates the most recent dated backup for a given MP3 and restores it with cp + cmp verification. Supports dry-run (-n), verbose (-v), and list-only (-l) modes.

Exiftool Stays-Open Daemon
Added a long-running exiftool -stay_open coproc daemon (start_exiftool_daemon, stop_exiftool_daemon, query_exiftool_daemon) to musiclib_build.sh. Each file scan now sends one request over named pipes instead of spawning a new exiftool process, eliminating the ~100 ms per-file interpreter startup cost on large library scans.

kid3 Config Auto-Sync
New sync_external_tool_config() function propagates POPM star-mapping, custom TXXX frame names, and UTF-8 text encoding into kid3rc automatically. Uses an mtime hash to skip re-application when the config is already current. Called at rating time and at install time so the kid3 GUI config stays aligned with musiclib.conf without manual reconfiguration.

GUI Tag Maintenance Enhancements

• TagClean group: added Recursive, Verbose, and Keep-backup checkboxes; arguments are passed through to the script.
• TagRebuild group: browse button now presents a file-or-directory picker menu; added Keep-backup checkbox and a "Restore Last Backup" button wired to launchTagRestore(); executing against the library root now shows a confirmation dialog with Cancel / Preview / Proceed options.

Copy Location to Clipboard
Added a "Copy location to clipboard" context-menu action to LibraryView. Copies the selected track's file path and echoes it to the status bar.

---

Improvements

• POPM star-rating values (POPM_STAR1–POPM_STAR5) are now configurable per installation via musiclib.conf (defaults: 1 / 64 / 128 / 196 / 255) without requiring code changes. musiclib_rate.sh consumes these variables with fallback defaults for older installs.
• KID3_CONFIG_FILE added to musiclib.conf so all scripts share a single kid3 config path.
• TXXX frames and USLT lyrics are now explicitly preserved across tag rebuilds: file-preserved TXXX frames are pre-read via kid3-cli before strip; lyrics are extracted from exiftool JSON and restored after rebuild.
• COMM frame handling improved with language-coded fallback variants; kid3 "Grouping" reference corrected to "Work" (maps to TIT1 / Content Group Description).
• Unicode preserved throughout tag operations; iconv transliteration removed; kid3 configured for UTF-8.
• Added --restore-lastplayed flag to musiclib_build.sh: reads the LastTimePlayed TXXX value from existing tags via kid3-cli before rebuilding the DB entry and writes it back after, preserving play history on full database rebuilds.
• Audacious running-state detection in smartplaylistpanel.cpp now reads /proc/<pid>/comm directly instead of spawning pgrep, eliminating stray PID output to the console.
• musiclib_init_config.sh: added pre-detection of EXISTING_MUSIC_REPO from the Audacious config at install time; added a Python patch block to seed the initial kid3rc with custom frame names, UTF-8 encoding, and POPM star-rating mapping.

---

Bug Fixes

• Fixed NEXT_ALBUM_ID counter initialization and cross-file tracking in musiclib_build.sh so album IDs are assigned consistently across a full library scan.
• Fixed CUSTOM2 field resolution: now uses a three-tier priority — dedicated TXXX frame first, then a COMM frame with a recognized prefix, then falls back to empty — preventing stale or incorrect values from leaking through.

---

[2026-04-08 additions]

New Features

tagrestore CLI Command
Registered tagrestore in CommandHandler; delegates to musiclib_tagrestore.sh. Argument parsing and validation are handled entirely by the script. Version bumped to 1.60; MUSICLIB_VERSION cmake define injected into CLI and GUI targets so the version string and Backend API version (1.6) are read from the define rather than hardcoded.

Pending Add-Track Handler
New add_track case in musiclib_process_pending.sh: validates inputs, acquires a DB lock, reads metadata via kid3-cli, builds a DSV entry, writes to the DB, updates file tags, and fires a kdialog notification on success.

libmusiclib Stubs
Placeholder .cpp implementations added for utils, db_reader, json_parser, script_executor, and config_loader — scaffolding for the planned migration to a shared libmusiclib.so.

Improvements

Batched kid3-cli Tag Writes
musiclib_utils_tag_functions.sh: replaced per-tag individual kid3-cli calls with a local kid3_set_cmds array flushed in a single invocation — eliminates per-command Qt+taglib startup overhead for every write in Stage 4. musiclib_tagrestore.sh: batched the ID3v1/v2/APE remove into a single kid3-cli call instead of three separate ones.

Strict Mode in Shell Scripts
Added set -e / -u / -o pipefail to musiclib_audacious.sh, musiclib_baloo_sync.sh, musiclib_edit_field.sh, musiclib_rate.sh, and musiclib_remove_record.sh.

GUI Include Guards Converted to #pragma once
configuretoolbarsdialog, settingsdialog, albumwindow, mainwindow, confwriter, mobile_panel, main — all remaining #ifndef include guards replaced with #pragma once.

Library-Root Confirmation Dialog
maintenancepanel: added confirmation dialog (Cancel / Preview / Proceed) before a recursive tag-clean runs on the entire library root.

Desktop Icons Added
Application icons at 48×48, 128×128, and 256×256 px added to desktop/icons/.

Documentation

• BACKEND_API.md bumped to v1.6: documents pending-ops wire format (§1.6), add_track operation type, progress line protocol (ACCOUNTING/UPLOAD prefixes), .pending_tracks and .failed recovery file schemas. Removed superseded JSON queue design. Corrected script/executable paths throughout.
• DEVELOPMENT.md: corrected all paths from /usr/lib/musiclib/bin/ to bin/; updated executable paths to build/bin/.
• MUSICLIB_USER_MANUAL.md: updated tagrestore usage examples, keyboard shortcut section, and workflow notes.
• README.md: corrected KID3_CONFIG_FILE and POPM_STAR* config variable names; corrected path references.

MusicLib 1.50

New Features
Smart Playlist Panel

Fully configurable Smart Playlist system integrated into settings
Automatically generates playlists based on custom criteria
Synchronizes with Audacious playback state for seamless operation

Dolphin File Manager Integration

Rate tracks directly from Dolphin context menu
Baloo indexing support displays ratings from Dolphin
Baloo integration runs automatically in build script

Custom Artist Field

Replaced 'Album Artist' with 'Custom Artist' in LibraryView
Enables more flexible artist tagging for Smart Playlist generation

Improvements

Refactored boost script and related CLI and GUI operations for better maintainability
Minor Smart Playlist Panel update to better align Audacious running state with playlist generation

Bug Fixes

Fixed window raise bug in system tray panel selection

MusicLib 1.4

Added panel for K3b, KDE-based CD Ripper. Updated PKGBUILD to generate an install script for optdepends.

MusicLib 1.31

Version correction only

MusicLib 1.3

Overview

Release 1.3 focused on code quality improvements, bug fixes, configuration architecture redesign, and repository cleanup. The release addressed critical path handling errors, database integrity issues, and implemented a robust multi-layered configuration system.

---

Major Changes by Category

1. Critical Bug Fixes

Path Configuration & File Addition Failures

• Commit: d99fa66 & b1c5c54
• Impact: HIGH - Fixed critical bugs in musiclib_utils_tag_functions.sh that were:
  • Preventing new file additions due to misconfigured paths
  • Causing tag processing failures when tag fields contained single quotes
• Files Modified: bin/musiclib_utils_tag_functions.sh, bin/musiclib_utils.sh

Database Integrity Strengthening

• Commit: b1c5c54
• Impact: HIGH - Enhanced data validation for:
  • New database record additions
  • New database builds
• Files Modified: bin/musiclib_build.sh, bin/musiclib_new_tracks.sh

---

2. Configuration Architecture Redesign

New Configuration System

• Commit: 46283d9 (Latest)
• Status: Added /config/musiclib.conf with 124 lines of configuration
• Purpose: Centralized essential configuration management

Configuration Management Improvements

• Commit: eae78da
• Enhancement: Updated musiclib_init_config.sh to preserve existing custom configurations during reinstall
• Benefit: Users can now safely reinstall without losing their custom setup

Layered Configuration Support

• Commit: a6db63d (Refactor)
• Implementation: Revised load_config() in musiclib_utils.sh
• Architecture:
  • System defaults: /usr/lib/musiclib/config/
  • User overrides: ~/.config/musiclib/
  • Environment variable override: MUSICLIB_CONFIG_DIR for dev/custom setups
• Benefit: Flexible, dev-friendly configuration management

---

3. Documentation Updates

Comprehensive Documentation Refresh

• Commits: 57935f6, 67d9576
• Updated Files:
  • CMakeLists.txt - Version reference
  • README.md - Main documentation
  • docs/BACKEND_API.md - 110+ lines of API documentation added/updated
  • docs/DEVELOPMENT.md - 250+ lines of development guide updates
  • docs/SCRIPTS_SUMMARY.md - New script summary documentation
• Changes: ~247 insertions, 141 deletions across 6 files

---

4. Repository Cleanup

Non-Essential Files Migration to Local Storage

• Commit: 733639a
• Removed from Git: 6 documentation files (3,017 lines)
  • docs/LOCK_CONTENTION_RESOLUTION.md
  • docs/MusicLib_KDE_Feature_Evaluation.md
  • docs/MusicLib_KDE_Feature_Evaluation_Supplement.txt
  • docs/Phase1_Task1_CMake_Setup_Subtasks.md
  • docs/musiclib_cli_dispatcher.md
  • docs/musiclib_cli_proposed_changes.md
• Purpose: Reduce repository bloat; maintain clean git history

Large Binary Removal

• Commit: 52e49a0
• Removed: musiclib.dsv file (15,599 lines)
• Purpose: Clean up version-tracked data files

.gitignore Refinement

• Commits: 2d32bd6, 46283d9, a6db63d
• Updates: Cleaned up .gitignore entries and added:
  • config/musiclib.conf - Exclude user configuration from tracking
• Result: More precise git exclusion patterns

---

5. Code Quality Improvements

File Naming Corrections

• Commit: b1c5c54
• Files Fixed: musiclib_utils_tag_functions.sh, musiclib_utils.sh
• Impact: Improved code consistency and maintainability

Formatting & Code Cleanup

• Commit: 2d32bd6
• Focus: Minor formatting improvements for code readability
• Files Affected: .gitignore, docs/README.md

Path Hardcoding Removal

• Commit: a6db63d
• Removed: Hardcoded /mnt/project/ path from musiclib_init_config.sh
• Removed: Personal paths (/home/lpc123/) from documentation
• Benefit: Improved portability and security

---

6. New Features & Enhancements

Audacious Integration Setup

• Commit: a6db63d
• Addition: New file bin/musiclib_audacious_setup.sh (216 lines)
• Purpose: Dedicated setup script for Audacious music player integration

Configuration Variable Expansion

• Commits: 46283d9, a6db63d
• Added: ~150+ configuration variables now available in config/musiclib.conf
• Scope: Enhanced customization options for users

MusicLib 1.2

Release 1.2

Features:

• Display artwork for currently playing track in left panel
• Edit DB fields in LibraryView via double-click
• Optional file removal when deleting DB records
• Library Conformance Check in setup flow
• Enhanced setup script with kid3, rsgain, and DB detection

Documentation:

• Updated User Manual, README, and KDE menu descriptor

Maintenance:

• Minor script updates