Metadata-Version: 2.4
Name: fakeflacfinder
Version: 0.1.1
Summary: Read-only FLAC integrity and lossy-origin evidence scanner
Project-URL: Homepage, https://github.com/ribomo/FakeFlacFinder
Project-URL: Repository, https://github.com/ribomo/FakeFlacFinder
Project-URL: Issues, https://github.com/ribomo/FakeFlacFinder/issues
Author: FakeFlacFinder contributors
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: audio,flac,integrity,spectral-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Requires-Python: <3.15,>=3.11
Requires-Dist: mutagen<2,>=1.48
Requires-Dist: numpy<3,>=2.3
Requires-Dist: soundfile<1,>=0.14
Requires-Dist: tqdm<5,>=4.68.4
Description-Content-Type: text/markdown

# 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:

```console
python -m pip install fakeflacfinder
fakeflacfinder --help
```

From a source checkout, install [uv](https://docs.astral.sh/uv/) 0.11.28 or a
newer 0.11.x release, then run:

```console
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:

```console
uv run --locked fakeflacfinder scan ~/Music
```

## Usage

```console
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:

```text
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

```text
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`](docs/lossy-evidence-scoring.md)
for the exact coverage, scoring, strong-rule, and channel-aggregation rules.
See
[`docs/research-and-validation.md`](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`](SECURITY.md). Do not
include sensitive vulnerability details in a public issue.

## Development

```console
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`](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`](docs/architecture.md) for the system
design and
[`docs/lossy-evidence-scoring.md`](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`](docs/research-and-validation.md).

## License

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