This project is in active development. Features may change between releases. Please report issues on GitHub.
BeatsCheck finds damaged music files. It decodes every file in your library with ffmpeg, flags the ones that fail or stop short, and explains in plain English what is wrong. You can then review them, delete them, or move them to a quarantine folder. Later scans check only new files; rescan --fresh checks everything again, including files replaced under the same name.
It starts in setup mode: nothing is scanned, moved or deleted until you choose to.
Supported formats: FLAC, MP3, M4A, OGG, Opus, WAV, WMA, AAC, AIFF, APE, WavPack, ALAC, M4B, M4P, MP2, MPC, DSF, DFF
- Copy
compose.yamlinto a folder, set your music and config paths, and rundocker compose up -din that folder. On Unraid, use the template. - Start a scan:
docker exec beatscheck rescan report - Read the results in
corrupt.txtin your config folder, or turn on the WebUI.
| Mode | What it does | Music mount | Safe? |
|---|---|---|---|
setup |
Container starts idle, no scanning (default) | ro |
Yes |
report |
Scan and log, writes corrupt.txt. With delete_after set it also auto-deletes, which needs rw |
ro |
Yes, while delete_after = 0 |
delete |
Interactive — prompts per album folder to delete | rw |
You choose |
move |
Auto-move corrupt files to quarantine folder | rw |
Destructive |
docker exec beatscheck rescan report # scan now, in report mode
docker exec beatscheck rescan --fresh report # re-check every file
docker exec -it beatscheck delete # review and delete corrupt files
docker exec beatscheck reset-webui-password # forgot the WebUI password- Installation — Docker Compose, docker run, Unraid, without Docker, updating
- Scanning and deleting — scan, review, delete and rescan
- Configuration — every setting, environment variables, output files
- How it works — the decode test, cut-short files, safety features, performance
- Web UI — setup, login and security
- Lidarr integration — blocklist, delete and search for replacements through Lidarr
See SECURITY.md for the security policy, vulnerability reporting, and container security measures.