fakeflacfinder 0.1.1

Read-only FLAC integrity and lossy-origin evidence scanner

FakeFlacFinder

FakeFlacFinder is a read-only command-line tool that checks FLAC integrity and flags evidence that audio may have previously been 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.

FakeFlacFinder scans FLAC files without changing them. It checks file integrity and looks for audio patterns that may indicate earlier lossy compression.

It cannot prove that audio is genuinely lossless. A valid FLAC may contain previously compressed audio, while legitimate recordings can produce similar patterns. pass means a score from 0–34, inconclusive means a score from 35–69 or no reliable score, and fail means the fail band and strong-rule gate were met. The spectral policy has not yet been calibrated against a ground-truth real-codec benchmark.

Requirements and setup

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 external audio tool.

Install the published package from PyPI:

python -m pip install fakeflacfinder
fakeflacfinder --help

From a source checkout, install uv 0.11.28 or a newer 0.11.x release, then run:

uv sync --locked
uv run --locked fakeflacfinder --help

uv 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 ~/Music

Usage

fakeflacfinder 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 --exclude '**/Archive/**'
fakeflacfinder scan ~/Music --jobs 8
fakeflacfinder scan album.flac --native-verify

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.

Reports

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:

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.

Interpreting results

integrity: valid | invalid | corrupt | unchecked
lossy_evidence: pass | inconclusive | fail
lossy_score: 0..100 | null

• invalid: the file is not a native FLAC stream.
• corrupt: the file is FLAC, but validation or decoding failed.
• unchecked: integrity could not be determined because of an operational, resource, or decoder limit.
• pass: score 0–34; this analyzer found no significant evidence.
• inconclusive: score 35–69, or no reliable score could be produced.
• fail: score 70–100 and the conservative detection conditions were met.
• 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 v0.1 decoder supports common, known-length 8-, 16-, and 24-bit FLAC. Other valid variants are reported as unsupported, not corrupt. --native-verify may confirm their integrity, but their spectral result remains inconclusive.

Analysis limits

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.

Safety and privacy

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. The default report filenames are ignored by Git, but reports written under other names or outside this repository are not.

To report a security vulnerability, follow SECURITY.md. Do not include sensitive vulnerability details in a public issue.

Development

uv lock --check
uv sync --locked
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked pytest
uv build

Contribution 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.

License

FakeFlacFinder is licensed under GPL-3.0-or-later. See LICENSE.