Getting Started with FLAC Detective

This guide will help you install and run your first FLAC analysis in minutes.

Table of Contents

System Requirements

Required

  • Python: 3.10 or higher

  • Operating System: Windows, macOS, or Linux

Required for ALAC / APE

  • ffmpeg: needed only to analyse ALAC (.m4a) and APE (.ape) files — these are decoded to PCM via ffmpeg. FLAC and WAV never need it. If you only ever scan FLAC/WAV, you can skip this; if you point the tool at an ALAC/APE file without ffmpeg installed, that file is skipped with a clear message (everything else still works).

    • Linux: sudo apt-get install ffmpeg

    • macOS: brew install ffmpeg

    • Windows: winget install ffmpeg (or download from ffmpeg.org and add it to your PATH)

    • Verify: ffmpeg -version

Installation

Option 2: Install via Docker

Pull the pre-built Docker image:

docker pull ghcr.io/guillain-rdcde/flac_detective:latest

Test it:

docker run --rm ghcr.io/guillain-rdcde/flac_detective:latest --version

Option 3: Install from Source

For development or the latest features:

# Clone the repository
git clone https://github.com/Guillain-RDCDE/FLAC_Detective.git
cd FLAC_Detective

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

Upgrading to the Latest Version

A plain pip install flac-detective does not upgrade an existing install — pip checks whether any version is already there and, if so, prints Requirement already satisfied and exits without changing anything. This is a common surprise: it looks like the install succeeded, but you still have the old version.

To actually upgrade, add the --upgrade flag (short form -U):

# Upgrade to the latest version on PyPI
pip install --upgrade flac-detective

# Same thing with the optional ML extra
pip install --upgrade "flac-detective[ml]"

# Confirm the new version is active
flac-detective --version

Docker users: pull the image again to refresh the local copy.

docker pull ghcr.io/guillain-rdcde/flac_detective:latest

Installed from source? Pull the latest commits and reinstall:

cd FLAC_Detective
git pull
pip install -e ".[dev]"   # or pip install -e .

To see what changed between versions, browse the CHANGELOG.

First Analysis

Analyze a Directory

# Basic usage - analyze current directory
flac-detective .

# Analyze specific directory
flac-detective /path/to/your/music

# Example on Windows
flac-detective "C:\Users\YourName\Music\FLAC Collection"

Analyze a Single File

flac-detective /path/to/song.flac

Docker Usage

# Mount your music directory and analyze
docker run --rm -v /path/to/music:/data ghcr.io/guillain-rdcde/flac_detective:latest /data

# Windows example
docker run --rm -v "C:\Users\YourName\Music":/data ghcr.io/guillain-rdcde/flac_detective:latest /data

What Happens During Analysis

When you run FLAC Detective, it will:

  1. Scan for all .flac files recursively

  2. Analyze each file using 11 detection rules (plus an optional 12th CNN rule with pip install "flac-detective[ml]")

  3. Display progress with a real-time progress bar

  4. Generate a detailed report

  5. Save results to a timestamped text file

Understanding Results

Console Output

======================================================================
  FLAC AUTHENTICITY ANALYZER
  Detection of MP3s transcoded to FLAC
======================================================================

⠋ Analyzing audio files... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  15% 0:02:34

======================================================================
  ANALYSIS COMPLETE
======================================================================
  FLAC files analyzed: 245
  Fake/Suspicious FLAC files: 3 (including 1 certain fakes)
  Text report: flac_report_20251220_143022.txt
======================================================================

The Four Verdicts

FLAC Detective assigns one of four verdicts to each file:

Verdict

Score Range

Icon

Meaning

What to Do

AUTHENTIC

≤ 30

✅

Genuine lossless audio

Keep the file

WARNING

31-54

❓

Uncertain, needs review

Manual verification recommended

SUSPICIOUS

55-85

⚠️

Likely MP3 transcode

Replace if possible

FAKE_CERTAIN

≥ 86

❌

Definite MP3 transcode

Delete and replace

Sample Report Entry

FILE: Metallica - Enter Sandman.flac
Location: /music/Metallica/Black Album/
Duration: 5:29 | Sample Rate: 44100 Hz | Bit Depth: 16

VERDICT: SUSPICIOUS ⚠️ (Score: 72/150)

REASON: MP3 192 kbps signature detected

ANALYSIS DETAILS:
  ✓ Rule 1 (MP3 Spectral): +50 pts - CBR pattern at 192 kbps
  ✓ Rule 2 (Cutoff Frequency): +15 pts - Cutoff at 19500 Hz
  ✓ Rule 9 (Compression): +7 pts - Pre-echo artifacts

RECOMMENDATION: Likely MP3 transcode. Consider re-downloading from source.

Score Interpretation

  • 0-30: File passes all authenticity checks → Keep it

  • 31-54: Borderline case → Verify manually

  • 55-85: Strong indicators of transcode → Likely fake

  • 86-150: Multiple definitive indicators → Definitely fake

Common Use Cases

Case 1: Verify Downloaded Album

# You downloaded an album and want to verify quality
flac-detective "/downloads/Pink Floyd - Dark Side of the Moon"

# If all files are AUTHENTIC → Good to go!
# If some are SUSPICIOUS → Re-download from better source
# If FAKE_CERTAIN → Report to source, find alternative

Case 2: Clean Your Music Library

# Analyze your entire collection
flac-detective ~/Music/FLAC

# Review the generated report
# Delete or replace suspicious files
# Keep authentic files

Case 3: Quality Control Before Sharing

# Before uploading to a music platform
flac-detective "/staging/my-album"

# Only upload if all files are AUTHENTIC

Command-Line Options

Flag

Purpose

-h, --help

Show the auto-generated help summary and exit

-V, --version

Print flac-detective <version> and exit

-v, --verbose

Set log level to DEBUG; surface per-rule scoring details

--sample-duration SECS

Audio sample duration (default 30, range 5–120; lower = faster)

--output PATH

Write the report to this path (default: auto-named in scan directory)

--format {text,json,csv}

Report format (default text; json = scan metadata + results; csv = one row per file, ranked most-suspicious first)

Examples:

# Show version / help
flac-detective --version
flac-detective --help

# Generate JSON output instead of text
flac-detective /path/to/music --format json

# Save output to a specific file
flac-detective /path/to/music --output my-report.txt

# Verbose mode (DEBUG log + per-rule details)
flac-detective /path/to/music --verbose

# Analyze only first 15 seconds (faster, less accurate)
flac-detective /path/to/music --sample-duration 15

# Combine: verbose + JSON to a custom path with a 60-second sample
flac-detective -v --sample-duration 60 --format json --output report.json /music

Auto-repair of corrupted files is enabled by default — no flag is needed.

Troubleshooting

pip install says “Requirement already satisfied” but I wanted the new version

That message means an older version is already on your system, and pip left it alone. Plain pip install <name> never upgrades — you have to ask for it explicitly:

pip install --upgrade flac-detective
flac-detective --version

See Upgrading to the Latest Version above for the full set of upgrade commands (pip extras, Docker, source).

“Command not found: flac-detective”

Solution: The package isn’t in your PATH. Try:

python -m flac_detective /path/to/music

“No FLAC files found”

Solution:

  • Verify you’re pointing to the correct directory

  • Check that files have .flac extension (not .FLAC on Linux)

  • Use ls or dir to confirm files exist

“Permission denied” errors

Solution:

# On Linux/macOS, you may need to fix permissions
chmod +r /path/to/music/*.flac

# Or run with sudo (not recommended)
sudo flac-detective /path/to/music

Analysis is very slow

Causes: Network drives, very large files, slow disk

Solutions:

  • Copy files to local disk first

  • Use --sample-duration 15 for faster analysis

  • Close other applications

Docker: “Cannot access /data”

Solution: Ensure volume mount is correct

# Windows - use forward slashes or escape backslashes
docker run --rm -v "C:/Users/Name/Music":/data ghcr.io/guillain-rdcde/flac_detective:latest /data

# Linux/macOS - use absolute paths
docker run --rm -v "/home/user/music":/data ghcr.io/guillain-rdcde/flac_detective:latest /data

Next Steps

Now that you’ve completed your first analysis:

  1. Learn more about usage → Read the User Guide

  2. Understand how it works → Read Technical Details

  3. Use the Python API → Read API Reference

  4. Contribute or customize → Read Contributing

Getting Help

Ready to analyze? Run flac-detective /path/to/music and you’re good to go!