{"id":50783942,"url":"https://github.com/tbb98/checkflac","last_synced_at":"2026-06-12T06:02:02.394Z","repository":{"id":324402962,"uuid":"1097110568","full_name":"tbb98/checkflac","owner":"tbb98","description":"A CLI tool to check for FLAC file corruption","archived":false,"fork":false,"pushed_at":"2025-11-15T15:47:39.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-15T17:20:43.505Z","etag":null,"topics":["bitrot","data-hoarder","datahoarder","flac","hoarding","home-lab","homelab","jellyfin","lms","lyrion","lyrion-music-server","music","music-hoarding","musichoarder","navidrome","plex","plex-media-server","rust","self-hosted","selfhosted"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tbb98.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-15T15:02:35.000Z","updated_at":"2025-11-15T15:47:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tbb98/checkflac","commit_stats":null,"previous_names":["tbb98/checkflac"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tbb98/checkflac","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbb98%2Fcheckflac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbb98%2Fcheckflac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbb98%2Fcheckflac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbb98%2Fcheckflac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tbb98","download_url":"https://codeload.github.com/tbb98/checkflac/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbb98%2Fcheckflac/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34231212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitrot","data-hoarder","datahoarder","flac","hoarding","home-lab","homelab","jellyfin","lms","lyrion","lyrion-music-server","music","music-hoarding","musichoarder","navidrome","plex","plex-media-server","rust","self-hosted","selfhosted"],"created_at":"2026-06-12T06:01:26.958Z","updated_at":"2026-06-12T06:02:02.002Z","avatar_url":"https://github.com/tbb98.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\n⚠️ Warning: This is a vibe-coded piece of crap!\nIt seems to work. Use at your own risk. No responsibility accepted.  \n```\n\n# checkflac\n\nA **FLAC file integrity checker** for verifying large collections of FLAC audio files. It scans directories, creates job files, checks files in parallel, and reports results with detailed statistics. It will not modify your FLAC files.\n\n---\n\n## Features\n\n* **Directory scanning**: Recursively find all .flac files.\n* **Job file creation**: Save discovered files in a JSON “job file” for later checking.\n* **Parallel FLAC verification**: Uses all CPU cores (or configurable threads) to check files efficiently.\n* **FLAC integrity checks**:\n  * Decodes the audio completely.\n  * Computes MD5 hash of raw audio and compares it to the FLAC file’s header MD5 (if present).\n* **Safe incremental updates**: Saves job file after each file check to handle interruptions.\n* **Statistics and summaries**: Shows counts for OK, Bad, Error, and pending files.\n\n---\n\n## Installation\n\nRequires [Rust toolchain](https://rustup.rs/)\n\n```bash\ngit clone https://github.com/tbb98/checkflac.git\ncd checkflac\ncargo build --release\n```\nThe compiled binary will be in `target/release/checkflac`\n\n\n\n## Usage\n\n### Explore a directory\n\nCreate a job file from a directory containing FLAC files:\n\n```bash\ncheckflac explore \u003cDIR\u003e [--output \u003cJOB_FILE\u003e]\n```\n\n* `\u003cDIR\u003e` — directory to scan\n* `--output` — optional output path for the job file (defaults to auto-generated filename)\n\nExample:\n\n```bash\ncheckflac explore \"M:\\Music FLAC\"\n```\n\nProduces a JSON job file like `checkflac_my_music_20251115_123456_job.json`\n\n---\n\n### Check FLAC files\n\nRun integrity checks on a job file:\n\n```bash\ncheckflac check \u003cJOB_FILE\u003e [--threads \u003cN\u003e] [--continue-on-error]\n```\n\n* `\u003cJOB_FILE\u003e` — previously generated job file\n* `--threads \u003cN\u003e` — optional number of threads to use (default: CPU cores)\n* `--continue-on-error` — continues checking even if some files fail\n\nExample:\n\n```bash\ncheckflac check checkflac_my_music_20251115_123456_job.json\n```\n\n---\n\n### View statistics\n\nView detailed statistics and optionally list files by status:\n\n```bash\ncheckflac stats \u003cJOB_FILE\u003e [--show-ok] [--show-pending] [--full-paths]\n```\n\n* `--show-ok` — display OK files\n* `--show-pending` — display files still to be checked\n* `--full-paths` — show full file paths instead of relative paths\n\n---\n\n## How the FLAC check works\n\n1. **Decoding**: Each FLAC file is fully decoded using [claxon](https://docs.rs/claxon/latest/claxon/)\n2. **MD5 verification**:\n\n   * The FLAC file header (STREAMINFO block) **may contain an MD5 checksum** of the raw audio data.\n   * If present, the computed MD5 of the decoded audio is compared to the header.\n3. **Result classification**:\n\n| Status      | Meaning                                                                                                |\n| ----------- | -------------------------------------------------------------------------------------------------------|\n| OK          | File decoded successfully, MD5 matches (or no MD5 in header)                                           |\n| Bad         | File decoded but MD5 does **not** match → **likely corrupted audio**                                   |\n| Error       | File could not be decoded (→ **likely corrupted audio**), is unreadable, or has an unsupported format  |\n| ToBeChecked | File has not been processed yet                                                                        |\n| Checking    | File is currently being checked                                                                        |\n\n* Any errors during decoding (e.g., malformed frames) mark a file as **Error**\n* MD5 mismatch files are **Bad**, even if the audio can technically play\n* Running the check again will try to re-check the errored out files again\n\n---\n\n## Job File Structure\n\nJob files are JSON files containing:\n\n```json\n{\n  \"root_directory\": \"/music/flac\",\n  \"total_files\": 120,\n  \"statistics\": {\n    \"to_be_checked\": 0,\n    \"checking\": 0,\n    \"ok\": 110,\n    \"bad\": 5,\n    \"error\": 5\n  },\n  \"jobs\": [\n    {\n      \"path\": \"/music/flac/album1/song1.flac\",\n      \"status\": \"OK\",\n      \"error_message\": null\n    },\n    {\n      \"path\": \"/music/flac/album1/song2.flac\",\n      \"status\": \"Bad\",\n      \"error_message\": \"FLAC verification failed\"\n    }\n  ]\n}\n```\n\n---\n\n## Implementation Notes\n\n* **Parallel processing**: Uses [rayon](https://docs.rs/rayon/latest/rayon/) to fully utilize CPU cores.\n* **Thread safety**: `Arc\u003cMutex\u003cJobFile\u003e\u003e` ensures safe concurrent updates.\n* **Incremental saves**: Saves the job file after each file update to avoid losing progress on interruption.\n* **Progress display**: Uses [indicatif](https://docs.rs/indicatif/latest/indicatif/) for progress bars and spinners.\n* **Error handling**: Uses [anyhow](https://docs.rs/anyhow/latest/anyhow/) for detailed error reporting.\n\n---\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftbb98%2Fcheckflac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftbb98%2Fcheckflac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftbb98%2Fcheckflac/lists"}