musicfix

Jan/musicfix

Fork 0

6 releases 8 tags

RSS feed

v1.2.3 ba8cdccee9

v1.2.3 Stable
Jan released this 2026-07-23 15:42:28 +02:00 | 3 commits to main since this release
musicfix 1.2.3

This release improves HTML notifications and fixes rich message delivery through an Apprise API gateway.

Highlights
- redesigned HTML notifications with a cleaner, email-friendly layout
- added clearly separated sections for run information, library statistics, changes, and details
- added status colors for successful and failed runs
- improved spacing, typography, path wrapping, and mobile readability
- preserved HTML and Markdown formatting when notifications are sent through an Apprise API gateway
- added direct delivery to the Apprise API /notify/{key} endpoint
- added support for forwarding configured Apprise tags
Fixed
- fixed labels and values appearing merged in some email clients
- fixed HTML notifications being converted into plain text by the Apprise gateway
- fixed long log and manifest paths breaking the notification layout
- fixed rich notification formats not being passed correctly to the Apprise API
Compatibility

Plain-text and Markdown notifications remain unchanged.

Existing notification configurations using URLs such as:
```
apprise://server:8000/key/?tags=all
```
Downloads
- Source code (ZIP)
  0 downloads
- Source code (TAR.GZ)
  0 downloads

v1.2.1 aae9390c6c

v1.2.1 Stable
Jan released this 2026-07-22 23:37:53 +02:00 | 16 commits to main since this release
musicfix v1.2.1

Highlights

Version 1.2.1 adds a small but useful convenience command for opening the active musicfix configuration directly in Nano.

Users no longer need to repeatedly remember or search for the configuration path. A modest victory over hidden files and human memory.

Added

Configuration editor command

Open the active musicfix configuration file directly in Nano:
```
musicfix config --edit
```
The command automatically uses the active configuration path, normally:
```
~/.config/musicfix/config.toml
```
It respects the configuration file currently loaded by musicfix and exits with Nano's return status.

If Nano is not installed, musicfix displays a clear error message in the selected interface language.

Changed
- README configuration documentation now includes musicfix config --edit
- the project version has been updated to 1.2.1
- configuration editing no longer requires manually entering the full file path
Language support

The editor command includes messages in both supported interface languages:
- German
- English
Example German error:
```
FEHLER: nano ist nicht installiert.
```
Example English error:
```
ERROR: nano is not installed.
```
Usage

Open the configuration:
```
musicfix config --edit
```
Validate the configuration without editing it:
```
musicfix config --check
```
Display the active configuration:
```
musicfix config
```
Notes

The generated configuration comments remain in English and continue to document:
- music and state paths
- interface language and color output
- retention periods
- cleanup extension protection
- library categories
- Apprise notification settings
- notification message formats
No new configuration option was required for this release because --edit is a command-line convenience feature rather than a persistent setting.
Downloads
- Source code (ZIP)
  0 downloads
- Source code (TAR.GZ)
  0 downloads

v1.2.0 a8d2e89941

v1.2.0 Stable
Jan released this 2026-07-22 23:34:10 +02:00 | 17 commits to main since this release
musicfix v1.2.0

Highlights

Version 1.2.0 introduces universal Apprise notification templates, configurable message formats, richer run summaries, and a clearer README introduction that explains the complete musicfix workflow.

Notifications are now designed to remain readable across email, Telegram, Discord, Slack, ntfy, Gotify, and plain-text destinations without depending on fragile service-specific formatting. A rare outbreak of sensible interoperability.

Added

Universal notification templates

musicfix now sends structured notifications for:
- successful runs
- failed runs
- Apprise test messages
The templates are available in German and English and include:
- run mode
- run ID
- runtime
- audio-file count
- folder count
- total library size
- new files
- modified files
- deleted files
- selected audio files
- affected albums
- log path
- manifest path
- installed musicfix version
Failure notifications additionally include:
- failed maintenance step
- exit code
Configurable notification format

The notification format can now be selected in the configuration:
```
[notifications]
enabled = true
notify_on_success = true
notify_on_failure = true
format = "markdown"
urls = [
  "apprise://172.16.3.150:8000/jarvis/?tags=all",
]
```
Supported values:
```
format = "text"
format = "markdown"
format = "html"
```
Recommended usage:
- text for maximum compatibility
- markdown as the default for mixed services
- html mainly for email and other rich-content destinations
Cross-service compatibility

Notification templates intentionally avoid:
- Markdown tables
- complex nesting
- service-specific markup
- formatting that becomes unreadable as plain text
The same message structure can therefore be used with:
- email
- Telegram
- Discord
- Slack
- ntfy
- Gotify
- other Apprise-supported services
- plain-text notification targets
Apprise notification types

musicfix now sends the appropriate Apprise notification type:
- success for successful runs
- failure for failed runs
- info for test messages
Services that support notification types may use their own icons, colors, priorities, or visual indicators.

Realistic Apprise template preview

The existing test command now sends the same structured template used by real maintenance runs:
```
musicfix apprise test
```
The test message contains realistic example data, including:
- write mode
- example run ID
- example runtime
- library statistics
- incremental change counts
- example log path
- example manifest path
- installed musicfix version
This makes it possible to preview the selected format without running library maintenance.

Improved README introduction

The README now includes a concise English description of the project:

musicfix is a safety-focused command-line toolkit for maintaining large,
folder-based music libraries on Linux. It can validate and repair FLAC files,
clean metadata and titles, normalize filenames, manage album and artist
artwork, quarantine unwanted files, and keep detailed logs, reports, backups,
and reversible run manifests.

The introduction also explains:
- dry-run and write behavior
- incremental SQLite indexing
- configurable cleanup protection
- support for audio, image, lyrics, video, and custom formats
- optional Apprise notifications
- compatibility with multiple notification services
Changed
- Markdown is now the default Apprise message format
- notification messages use a clearer section-based layout
- run notifications now include incremental change statistics
- failure notifications now identify the failed step and exit code
- notification details now include the manifest path
- notification footers now include the installed musicfix version
- the Apprise test command now previews the real notification template
- README documentation now reflects the complete current feature set
- notification configuration examples now include the format option
Configuration example
```
[notifications]
# Enable automatic notifications after complete musicfix runs.
enabled = true

# Send a notification when a run completes successfully.
notify_on_success = true

# Send a notification when a run fails.
notify_on_failure = true

# Message format: text, markdown or html.
# Markdown is the recommended default across mixed services.
format = "markdown"

# One or more Apprise service URLs.
urls = [
  "apprise://172.16.3.150:8000/jarvis/?tags=all",
]
```
Example Markdown notification
```
✅ musicfix completed successfully

## Run

**Mode:** `Write`
**Run ID:** `20260722-224502-815491`
**Runtime:** `12 min 38 s`

## Library

**Audio files:** `8,197`
**Folders:** `705`
**Library size:** `157.80 GiB`

## Changes

**New:** `12`
**Modified:** `4`
**Deleted:** `1`
**Selected audio files:** `23`
**Affected albums:** `6`

## Details

**Log:** `/home/user/.local/share/musicfix/logs/musicfix.log`
**Manifest:** `/home/user/.local/share/musicfix/runs/example/manifest.json`

---

musicfix 1.2.0
```
Example failure notification
```
❌ musicfix failed

## Run

**Mode:** `Write`
**Run ID:** `20260722-224502-815491`
**Runtime:** `8 s`

## Library

**Audio files:** `8,197`
**Folders:** `705`
**Library size:** `157.80 GiB`

## Changes

**New:** `2`
**Modified:** `1`
**Deleted:** `0`
**Selected audio files:** `7`
**Affected albums:** `2`

## Details

**Failed step:** `flac-repair`
**Exit code:** `1`
**Log:** `/home/user/.local/share/musicfix/logs/musicfix.log`
**Manifest:** `/home/user/.local/share/musicfix/runs/example/manifest.json`

---

musicfix 1.2.0
```
Testing

Verify the active configuration:
```
musicfix config --check
```
Check required dependencies:
```
musicfix doctor
```
Preview the selected notification format:
```
musicfix apprise test
```
Run an incremental dry run:
```
musicfix all
```
Run incremental maintenance with changes enabled:
```
musicfix all --write
```
Force a complete library pass:
```
musicfix all --full
musicfix all --full --write
```
Safety
- notifications do not modify the music library
- notification failures do not change the maintenance run result
- dry runs remain read-only
- write operations still require --write
- failed or interrupted runs do not update the incremental index
- unsupported files are moved to quarantine instead of being deleted directly
- logs, reports, backups, and manifests remain available for inspection and recovery
Downloads
- Source code (ZIP)
  0 downloads
- Source code (TAR.GZ)
  0 downloads

v1.1.1 9fd52ac74c

v1.1.1 Stable
Jan released this 2026-07-22 23:13:57 +02:00 | 19 commits to main since this release
musicfix v1.1.1

Highlights

Version 1.1.1 improves cleanup safety, adds configurable file-extension preservation, expands video-file support, and introduces a dedicated Apprise test command.

The cleanup step is now far less likely to mistake a perfectly valid video file for digital litter, which is a reassuringly low bar that software still manages to trip over.

Added

Configurable cleanup allow-list

A new [cleanup] section controls which file extensions must be preserved:
```
[cleanup]
keep_extensions = [
  ".flac",
  ".mp3",
  ".m4a",
  ".jpg",
  ".png",
  ".mkv",
  ".mov",
  ".webm",
]
```
The allow-list:
- is case-insensitive
- accepts extensions with or without a leading dot
- removes duplicate entries automatically
- can be extended with custom file formats
- can be reduced by removing or commenting out entries
Files whose extension is not included may be moved to quarantine during a cleanup write run.

Default video-file protection

Common video formats are now preserved by default:
- .3gp
- .asf
- .avi
- .divx
- .flv
- .m2ts
- .m4v
- .mkv
- .mov
- .mp4
- .mpeg
- .mpg
- .mts
- .ogv
- .rm
- .rmvb
- .ts
- .vob
- .webm
- .wmv
Common audio, lyrics, and image formats also remain protected by default.

Apprise test command

A dedicated notification test command is now available:
```
musicfix apprise test
```
The command:
- sends a real test notification
- uses every URL configured in [notifications].urls
- works even when automatic notifications are disabled
- validates whether configured Apprise URLs can be loaded
- reports delivery success or failure
- supports German and English output
- does not modify the music library or incremental index
Example German output:
```
✓ Apprise-Test erfolgreich: 1 Ziel
```
Example English output:
```
✓ Apprise test successful: 1 target
```
Changed
- Cleanup now receives its protected extensions from the central configuration
- Generated configuration files include a documented [cleanup] section
- The README now explains cleanup behavior, quarantine safety, and extension customization
- Configuration output shows the number of protected cleanup extensions
- Cleanup reports configured file extensions as an explicit preservation reason
- Apprise testing no longer requires a complete maintenance run
Fixed
- Video files such as MKV, MOV, M4V, WebM, AVI, M2TS, TS, VOB, and WMV are no longer quarantined by default
- Custom file extensions can now be protected without changing source code
- Cleanup-extension matching now works consistently regardless of capitalization
- Extensions without a leading dot are normalized automatically
- New cleanup messages are available in both German and English terminal output
Configuration example
```
[cleanup]
# Extensions that cleanup must preserve. Matching is case-insensitive.
# Comment out an entry to stop preserving that format.
# Add another extension to preserve additional file types.
# The leading dot is optional, but recommended for readability.
# Files not listed here may be moved to quarantine by cleanup --write.
keep_extensions = [
  # Audio
  ".aac",
  ".aif",
  ".aiff",
  ".alac",
  ".ape",
  ".flac",
  ".m4a",
  ".mp3",
  ".mp4",
  ".ogg",
  ".opus",
  ".wav",
  ".wma",
  ".wv",

  # Lyrics
  ".lrc",
  ".lyrics",

  # Images
  ".avif",
  ".bmp",
  ".gif",
  ".jpeg",
  ".jpg",
  ".png",
  ".webp",

  # Video
  ".3gp",
  ".asf",
  ".avi",
  ".divx",
  ".flv",
  ".m2ts",
  ".m4v",
  ".mkv",
  ".mov",
  ".mpeg",
  ".mpg",
  ".mts",
  ".ogv",
  ".rm",
  ".rmvb",
  ".ts",
  ".vob",
  ".webm",
  ".wmv",

  # Optional custom formats
  # ".cue",
  # ".nfo",
]
```
Safety

Preview cleanup actions without changing files:
```
musicfix cleanup
```
Apply cleanup and move unsupported files to quarantine:
```
musicfix cleanup --write
```
Run the complete maintenance workflow:
```
musicfix all
musicfix all --write
```
Test notifications independently:
```
musicfix apprise test
```
Files are never permanently deleted directly by cleanup. Unsupported files are moved to the configured quarantine directory first.
Downloads
- Source code (ZIP)
  0 downloads
- Source code (TAR.GZ)
  0 downloads

v1.1.0 110062755b

v1.1.0 Stable
Jan released this 2026-07-22 22:46:21 +02:00 | 21 commits to main since this release
musicfix v1.1.0

Highlights

Version 1.1.0 introduces incremental library processing, a restored cross-distribution installer, and built-in Apprise support.

Normal maintenance runs no longer need to fully inspect the entire music library when only a small number of files have changed. Humanity may finally be spared one unnecessary full scan.

Added

Incremental library index
- Added a SQLite-backed library index
- Detects new, modified, and deleted audio files
- Detects relevant artwork changes
- Uses file path, size, and nanosecond modification time for change detection
- Selects all audio files from affected album directories
- Stores the index below the configured state directory as index.sqlite3
- Updates the index automatically after successful write runs
- Keeps pending changes available after dry runs
- Falls back to a full run when no index exists
Index commands
```
musicfix index status
musicfix index rebuild
musicfix index clear
```
Create the initial baseline:
```
musicfix index rebuild
```
Inspect pending changes:
```
musicfix index status
```
Delete the current index:
```
musicfix index clear
```
Incremental maintenance

Normal complete runs are now incremental:
```
musicfix all
musicfix all --write
```
Force a complete library pass:
```
musicfix all --full
musicfix all --full --write
```
The following maintenance steps process only selected files during incremental runs:
- FLAC repair
- Title cleanup
- Tag normalization
- Filename normalization
- Embedded cover extraction
- Online cover lookup
- Placeholder-cover generation
Artist-image validation and cleanup remain global because they inspect directory-level library structure.

Apprise notifications
- Added Apprise as an automatic Python dependency
- No separate Apprise installation is required
- Added optional notifications after complete runs
- Supports notifications for successful runs
- Supports notifications for failed runs
- Supports multiple Apprise service URLs
- Uses the Apprise Python library directly
- Notification failures do not change the musicfix run result
Notification messages include:
- Success or failure status
- Dry-run or write mode
- Run ID
- Runtime
- Audio-file count
- Folder count
- Total library size
- Log-file path
Example configuration:
```
[notifications]
enabled = true
notify_on_success = true
notify_on_failure = true
urls = [
  "apprise://0.0.0.0",
]
```
Installer
- Restored install.sh
- Added support for Arch Linux, CachyOS, EndeavourOS, Manjaro, Debian, Ubuntu, Linux Mint, Pop!_OS, Fedora, openSUSE, and Alpine Linux
- Automatically installs required system packages when possible
- Installs musicfix through pipx
- Installs Python dependencies, including Apprise
- Supports installing the latest branch or a specific Git tag
- Prints Fish-specific PATH guidance when required
Install the latest version:
```
curl -fsSL \
  https://git.justdoit.network/Jan/musicfix/raw/branch/main/install.sh \
  | bash
```
Install version 1.1.0:
```
curl -fsSL \
  https://git.justdoit.network/Jan/musicfix/raw/branch/main/install.sh \
  | bash -s -- v1.1.0
```
Changed
- Complete maintenance runs now use incremental processing by default
- Dry runs no longer consume pending index changes
- Successful write runs rebuild the index after all file changes are complete
- Apprise integration now uses the Python library instead of an external command
- Generated configuration files include English comments describing supported options
- README documentation now covers configuration, notifications, incremental processing, and installation
- Configuration inspection remains read-only unless an actual setting changes
Safety
- No library changes are made without --write
- Incremental index updates occur only after successful write runs
- Interrupted or failed runs do not update the index
- Suspiciously broad library roots remain blocked
- Parallel write operations remain protected by a process lock
- Logs, reports, backups, and run manifests remain available for recovery
- Full scans remain available through --full
Downloads
- Source code (ZIP)
  0 downloads
- Source code (TAR.GZ)
  0 downloads

v1.0.0 0f96bed90a

v1.0.0 Stable
Jan released this 2026-07-22 22:08:02 +02:00 | 25 commits to main since this release

release
Downloads
- Source code (ZIP)
  0 downloads
- Source code (TAR.GZ)
  0 downloads

v1.2.3 Stable

musicfix 1.2.3

Highlights

Fixed

Compatibility

v1.2.1 Stable

musicfix v1.2.1

Highlights

Added

Configuration editor command

Changed

Language support

Usage

Notes

v1.2.0 Stable

musicfix v1.2.0

Highlights

Added

Universal notification templates

Configurable notification format

Cross-service compatibility

Apprise notification types

Realistic Apprise template preview

Improved README introduction

Changed

Configuration example

Example Markdown notification

Example failure notification

Testing

Safety

v1.1.1 Stable

musicfix v1.1.1

Highlights

Added

Configurable cleanup allow-list

Default video-file protection

Apprise test command

Changed

Fixed

Configuration example

Safety

v1.1.0 Stable

musicfix v1.1.0

Highlights

Added

Incremental library index

Index commands

Incremental maintenance

Apprise notifications

Installer

Changed

Safety

v1.0.0 Stable