FakeFlacFinder is a read-only command-line tool that checks FLAC integrity and looks for signs that the audio was previously compressed using a lossy format such as MP3.
Alpha status: Significant portions of this project were developed with AI assistance and reviewed through tests and manual inspection. Bugs and incorrect assumptions may remain, so treat results as evidence rather than proof.
It cannot prove that audio is genuinely lossless. A valid FLAC may contain previously compressed audio, while genuinely lossless recordings can sometimes show similar patterns.
Results use three score bands:
pass(0–34): no significant evidence was found.inconclusive(35–69, or no reliable score): the evidence is uncertain.fail(70–100): the configured fail threshold was met and additional conservative checks passed.
These thresholds are preliminary and have not yet been calibrated using a benchmark of files with known lossless or lossy-compression histories.
FakeFlacFinder requires CPython 3.11 through 3.14 and supports common Linux,
macOS, and Windows systems. SoundFile wheels usually include libsndfile.
Installing SoundFile from source or using an uncommon platform may require a
system libsndfile package. Default scans require no separate audio executable.
Install the published package with
pipx to keep it in an isolated environment:
pipx install fakeflacfinder
fakeflacfinder --helpAlternatively, install it with pip inside an activated virtual environment:
python -m pip install fakeflacfinder
fakeflacfinder --helpInstall uv 0.11.28 or a newer 0.11.x release, then run these commands from a source checkout:
uv sync --locked
uv run --locked fakeflacfinder --helpuv is used for development but is not a runtime dependency of built wheels.
The examples below use the installed fakeflacfinder command. When running
from a source checkout, prefix it with uv run --locked, for example:
uv run --locked fakeflacfinder scan ~/Musicfakeflacfinder scan ~/Music # human report
fakeflacfinder scan ~/Music --format jsonl # JSON Lines report
fakeflacfinder scan ~/Music --format json --output report.json
fakeflacfinder scan ~/Music --format json --output -
fakeflacfinder scan ~/Music --include "Live/**/*.flac"
fakeflacfinder scan ~/Music --exclude "**/Archive/**"
fakeflacfinder scan ~/Music --jobs 8
fakeflacfinder scan album.flac --native-verifyInclude and exclude patterns are repeatable, root-relative POSIX globs on every
platform. * matches within one path component, while ** can span directories.
Exclusions take precedence. A directory that matches an exclusion is not traversed.
Scans use one process by default. Use -j N or --jobs N (1–61) to analyze
directory contents concurrently. Results remain in traversal order. More jobs
use more CPU, memory, and storage bandwidth, so start with a modest value.
--native-verify adds an integrity check using the official flac executable
and requires --jobs 1. The executable must be available as flac on PATH.
Reports are saved in the current directory by default as
fakeflacfinder-report.txt, fakeflacfinder-report.json, or
fakeflacfinder-report.jsonl. Use --output FILE to choose another path or
--output - to write the report to stdout. Existing files are never
overwritten, and file reports are published atomically when complete.
Interactive scans show per-file progress when writing to a file. With
--output -, stdout contains only the report. Errors and diagnostics go to
stderr. A fail result is a content finding, not a command failure.
Human reports group files by their parent directory:
Scan root: /music/Example Album
ALBUM Example Album
FILE track.flac: Pass (7/100)
FILE other.flac: Inconclusive (36/100)
FILE suspect.flac: Fail (82/100)
ALBUM SUMMARY pass=1 inconclusive=1 fail=1 results=3 issues=0
SUMMARY pass=1 inconclusive=1 fail=1 eligible=3 results=3 issues=0 excluded=0 symlinks=0 exit=0
Routine valid and complete states are omitted from human reports. Problems
are labeled integrity: invalid, integrity: corrupt, integrity: unchecked,
or analysis incomplete. Interactive human output uses color; set NO_COLOR
to disable it. Report files and structured output never contain color codes.
JSON and JSONL results stay in traversal order and include overall totals in
lossy_evidence. Schema version 1.0.0 omits timestamps, elapsed time, host
identifiers, and temporary paths.
| Exit | Meaning |
|---|---|
| 0 | Scan completed; integrity and evidence outcomes do not change the exit code. |
| 1 | Invalid invocation or fatal startup, configuration, verifier, or output error. |
| 2 | Scan completed partially because one or more paths could not be processed. |
| 130 | Interrupted by the user. |
Integrity and lossy-origin evidence answer separate questions: whether the FLAC is structurally sound, and whether its audio shows signs of earlier lossy compression.
integrity: valid | invalid | corrupt | unchecked
lossy_evidence: pass | inconclusive | fail
lossy_score: 0..100 | null
valid: the available integrity checks passed.invalid: the file is not a native FLAC stream or has an invalid FLAC structure.corrupt: the file is FLAC, but decoding or an audio-integrity check failed.unchecked: integrity could not be determined because of an operational, resource, or decoder limit.
A null lossy score means that no reliable spectral score could be produced.
The pass, inconclusive, and fail labels use the score bands summarized
above. Scores rank evidence; they are not probabilities.
See
docs/lossy-evidence-scoring.md
for the exact coverage, scoring, strong-rule, and channel-aggregation rules.
See
docs/research-and-validation.md
for the literature review, validation status, known assumptions, and proposed
benchmark.
The built-in decoder currently supports common, known-length 8-, 16-, and
24-bit FLAC streams. Other valid variants are reported as unsupported, not
corrupt.
--native-verify may confirm their integrity, but their spectral result remains
inconclusive.
Spectral analysis requires a valid, supported FLAC sampled at 32–192 kHz and at least 15 seconds long. It analyzes each channel separately without mixing or resampling and samples at most 60 seconds of audio.
Quiet, tonal, sparse, or otherwise weak signals may be inconclusive. A fail
requires adequate coverage in a strict majority of channels and both a persistent
bandwidth edge and repeated spectral holes in the selected channel. A cutoff alone
cannot fail, and fail detection is disabled below 44.1 kHz.
Natural filtering, recording equipment, mastering, and restoration can produce similar patterns. Earlier lossy compression can also escape detection.
Files are opened read-only. FakeFlacFinder never modifies them or accesses the network. Tests cover file contents, size, permissions, and modification time; the operating system may still update each file's access time.
Reports can contain sensitive information, including absolute scan paths, filenames, audio tags, and other file metadata. Review and redact reports before sharing or publishing them. This repository ignores the default report filenames, but your own repository will not unless you configure it to do so.
To report a security vulnerability, follow SECURITY.md. Do not
include sensitive vulnerability details in a public issue.
uv lock --check
uv sync --locked
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked pytest
uv buildContribution guidelines are in CONTRIBUTING.md.
The major subsystems start in scanner.py, integrity.py, spectral.py, and
reporting.py; focused helper modules contain their implementation details.
The report schema, spectral analyzer, and scoring policy each have their own
version number. See docs/architecture.md for the system
design and
docs/lossy-evidence-scoring.md
for scoring and versioning rules. The research basis and work required to measure
accuracy are recorded in
docs/research-and-validation.md.
FakeFlacFinder is licensed under GPL-3.0-or-later. See LICENSE.