flac-checker 2.0.0
Detect fake FLAC files (transcoded from lossy formats) by analyzing frequency spectrum
License: MIT
Requires Python: >=3.8
Keywords: audio, flac, lossless, detection, mp3

# FLAC Checker

A modern Python tool to detect "fake" FLAC files - audio files that claim to be lossless but were actually created by transcoding from lossy formats (like MP3).

## Features

- 🔍 **Automatic Detection**: Analyzes frequency spectrum to identify telltale signs of lossy compression
- 📁 **Batch Processing**: Recursively scans directories and processes multiple files in parallel
- 📊 **Rich Progress**: Beautiful progress bars and status updates using Rich
- 🎯 **Multiple Samples**: For long files, analyzes multiple segments (1/3 and 2/3 through file) for better reliability
- ⚡ **Fast**: Parallel processing with configurable worker threads
- 🎨 **Modern CLI**: Clean command-line interface built with Typer

## Installation

### From Source

```bash
git clone <repository-url>
cd fakeflac
pip install -e .
```

### Dependencies

The tool requires:
- Python 3.8+
- numpy
- scipy
- soundfile
- typer
- rich

All dependencies are automatically installed when installing the package.

## Usage

### Basic Usage

Check all FLAC and WAV files in a directory:

```bash
flac-checker /path/to/music/directory
```

### Options

```bash
flac-checker [OPTIONS] DIRECTORY

Arguments:
  DIRECTORY  Directory containing audio files to check

Options:
  -f, --only-fake          Only print files that are likely fake (score < 100)
  -d, --sample-duration     Duration of each sample in seconds [default: 30]
  -s, --single-sample       Only analyze first sample (don't use multiple samples)
  -c, --channel            Audio channel to analyze (0=left, 1=right) [default: 0]
  -j, --jobs               Number of parallel workers [default: CPU cores]
  -e, --extensions         Comma-separated file extensions [default: .flac,.wav]
  --help                   Show this message and exit
```

### Examples

**Check a directory and save results to a file:**

```bash
flac-checker ~/Music/library > report.txt
```

**Only show files that are likely fake:**

```bash
flac-checker ~/Music/library --only-fake
```

**Use custom sample duration and extensions:**

```bash
flac-checker ~/Music/library --sample-duration 45 --extensions .flac,.wav,.m4a
```

**Process with 8 parallel workers:**

```bash
flac-checker ~/Music/library --jobs 8
```

## Output Format

The tool outputs results in the format:

```
/path/to/file.flac:score
```

Where `score` is a number from 0-100:

- **100**: Likely authentic lossless audio
- **90-99**: Probably authentic
- **70-89**: Might be transcoded
- **50-69**: Likely fake
- **1-49**: Definitely fake (heavily filtered)

### Example Output

```
/home/user/Music/track1.flac:100
/home/user/Music/track2.flac:73
/home/user/Music/track3.flac:45
```

## How It Works

FLAC Checker analyzes the frequency spectrum of audio files to detect signs of lossy compression by:

1. **Spectral Analysis**: Performs FFT on audio segments to analyze frequency content
2. **Cutoff Detection**: Identifies sharp frequency cutoffs characteristic of MP3 low-pass filtering
3. **Multiple Samples**: For files longer than 90 seconds, analyzes segments at 1/3 and 2/3 through the file
4. **Scoring**: Returns a percentage representing how much of the frequency spectrum contains significant energy

For detailed algorithm documentation, see [ALGORITHM.md](ALGORITHM.md).

## Performance

- **Single file**: Typically processes in 1-3 seconds
- **Batch processing**: With 8 CPU cores, processes ~4-8 files per second
- **Memory usage**: ~50-200 MB per worker (depends on file size)

## Limitations

1. **Short Files**: Files shorter than the sample duration may not produce reliable results
2. **Silent Sections**: Very quiet audio might not have enough energy for analysis
3. **False Positives**: Some legitimate audio (e.g., heavily processed electronic music) might show cutoffs
4. **False Negatives**: Very high bitrate MP3s (320 kbps) might have less obvious cutoffs

## Development

### Setup

```bash
# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run type checking
mypy flac_checker/

# Format code
black flac_checker/

# Lint code
ruff check flac_checker/
```

### Project Structure

```
flac-checker/
├── flac_checker/
│   ├── __init__.py      # Package initialization
│   ├── analyzer.py      # Core analysis functions
│   └── main.py          # CLI entry point
├── pyproject.toml       # Project configuration and dependencies
└── README.md           # This file
```

## License

MIT License - see LICENSE file for details

## Credits

Based on the original [FakeFLAC](http://www.maurits.vdschee.nl/fakeflac/) tool by Maurits van der Schee.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.