User Guide

Complete guide to using FLAC Detective effectively.

Table of Contents

Basic Usage
Command-Line Options
Understanding Results
Real-World Examples
Batch Processing
Docker Usage
Best Practices
Troubleshooting

Basic Usage

Analyze a Directory

# Analyze current directory
flac-detective .

# Analyze specific folder
flac-detective /path/to/music

# Analyze with full path (Windows)
flac-detective "C:\Users\YourName\Music\FLAC"

Analyze a Single File

flac-detective /path/to/file.flac

Recursive Analysis

FLAC Detective automatically scans subdirectories:

Music/
├── Artist 1/
│   ├── Album A/
│   │   ├── 01 - Track.flac  ← Analyzed
│   │   └── 02 - Track.flac  ← Analyzed
│   └── Album B/
│       └── 01 - Track.flac  ← Analyzed
└── Artist 2/
    └── Album C/
        └── 01 - Track.flac  ← Analyzed

All .flac files are found and analyzed automatically.

Command-Line Options

Output Formats

# Default: Text report to console + file
flac-detective /music

# JSON output (for automation)
flac-detective /music --format json

# Save to specific file
flac-detective /music --output custom-report.txt

# JSON to file
flac-detective /music --format json --output results.json

# CSV — library triage: one row per file, ranked most-suspicious first
flac-detective /music --format csv --output triage.csv

# HTML — a visual report you double-click to open (spectrum plots for flagged files)
flac-detective /music --format html --output report.html

Four formats, four jobs:

`--format`	For	Notes
`text` (default)	reading	human-friendly report + console summary
`json`	automation	full result objects, parse with `jq` etc.
`csv`	triaging a whole library	one row per file, sorted by score (most suspicious first); open in any spreadsheet to sort/filter. Columns: `rank, score, verdict, filename, cutoff_freq_hz, sample_rate, bit_depth, reason, filepath`
`html`	seeing the evidence	a single self-contained `.html` (no external assets) with a sortable/filterable triage table and an inline spectrum plot for every flagged file — the MP3 “cliff” is visible to the eye, with the detected cutoff marked. Plots are drawn for flagged files only; a file that isn’t natively readable simply shows no plot

When a scan finds suspicious files, the console summary also prints the top suspects ranked by score, so you immediately see what to check first.

Analysis Options

# Verbose mode (show detailed rule execution)
flac-detective /music --verbose

# Faster analysis (15 seconds per file, less accurate)
flac-detective /music --sample-duration 15

# Longer analysis (60 seconds, more accurate)
flac-detective /music --sample-duration 60

# Deep mode: run the ML rule (CNN) on every file
flac-detective /music --deep

When to use --deep. A normal scan keeps things fast by skipping the ML rule (Rule 12, the CNN) on files the quick heuristic rules clear instantly. That’s the right default for the common case (low-bitrate MP3 fakes, which the heuristics catch anyway) — but it’s also exactly where a high-bitrate AAC, Opus or Vorbis transcode hides: those leave no heuristic trace, so they sail through as AUTHENTIC. --deep runs the CNN on every file; when it is highly confident a full-range file is a transcode, the verdict is lifted to WARNING (“worth checking”, never an outright “fake”). The price is speed — every file is decoded and run through the CNN, so a large library takes noticeably longer. Reach for it when you specifically suspect AAC/Opus/Vorbis sources, or for a thorough second pass on a collection a fast scan called clean. It does not help with band-limited recordings (early-music, 1920s, solo acoustic) — that’s a genuine signal limit no tool can cross.

Note: Auto-repair of corrupted FLAC files is enabled by default — no flag is needed, and it’s lossless and hi-fi-safe. It triggers only on files that can’t be decoded at all; it rebuilds a valid FLAC with the exact same PCM samples (Xiph’s reference flac tool), preserves tags/artwork, keeps a .corrupted.bak backup, and verifies the result before replacing anything. Healthy files are never rewritten. See Technical Details → Repair for the full procedure.

Combining Options

# Verbose + JSON
flac-detective /music --verbose --format json

# Fast scan with custom output
flac-detective /music --sample-duration 15 --output quick-scan.txt

Understanding Results

The Four Verdicts

✅ AUTHENTIC (Score ≤ 30)

Meaning: Genuine lossless audio, very high confidence

Typical characteristics:

Cutoff frequency at or near Nyquist (22050 Hz for 44.1kHz)
No compression artifacts detected
High spectral variance
May have analog source signatures (vinyl, cassette)

Example:

VERDICT: AUTHENTIC ✅ (Score: 12/150)
REASON: Full spectrum preserved, no artifacts
RECOMMENDATION: File is genuine lossless. Keep as-is.

Action: Keep the file, it’s authentic.

❓ WARNING (Score 31-54)

Meaning: Uncertain case, manual review needed

Typical characteristics:

Cutoff slightly below Nyquist (20-21 kHz)
Some minor artifacts but protected by other rules
Could be legitimate high-quality source
Could be borderline transcode

Example:

VERDICT: WARNING ❓ (Score: 45/150)
REASON: Cutoff at 20500 Hz, minor artifacts
RECOMMENDATION: Verify with external tools. Could be legitimate.

Action:

Listen to the file carefully
Check source credibility
Use complementary tool (e.g., Spek for visual spectral analysis)
Consider re-downloading if suspicious

⚠️ SUSPICIOUS (Score 55-85)

Meaning: High confidence MP3 transcode

Typical characteristics:

MP3 spectral signature detected (Rule 1: +50 pts)
Cutoff matches known MP3 bitrate (128-256 kbps)
Compression artifacts present
Consistent patterns across file

Example:

VERDICT: SUSPICIOUS ⚠️ (Score: 72/150)
REASON: MP3 192 kbps signature detected
ANALYSIS:
  ✓ Rule 1: +50 pts - CBR pattern at 192 kbps
  ✓ Rule 2: +15 pts - Cutoff at 19500 Hz
  ✓ Rule 9: +7 pts - Pre-echo artifacts
RECOMMENDATION: High confidence transcode. Replace if possible.

Action:

Replace file from better source if available
Accept quality loss if no alternative
Document for future reference

❌ FAKE_CERTAIN (Score ≥ 86)

Meaning: Definite MP3 transcode, absolute confidence

Typical characteristics:

Multiple MP3 indicators confirmed
Strong compression artifacts
Suspicious metadata (fake 24-bit)
Consistent MP3 patterns throughout

Example:

VERDICT: FAKE_CERTAIN ❌ (Score: 103/150)
REASON: Multiple MP3 signatures confirmed
ANALYSIS:
  ✓ Rule 1: +50 pts - MP3 128 kbps signature
  ✓ Rule 2: +30 pts - Cutoff at 16000 Hz
  ✓ Rule 4: +30 pts - Suspicious 24-bit encoding
  ✓ Rule 9: +15 pts - Multiple compression artifacts
RECOMMENDATION: Definitely transcoded. Delete and replace.

Action:

Delete the file
Find authentic source
Report to distributor if applicable

Understanding Rule Contributions

Each rule can add or subtract points:

Positive Rules (Add points → Indicates fake):

Rule 1: MP3 Spectral Signature (+50)
Rule 2: Low Cutoff Frequency (+30)
Rule 3: Bitrate Mismatch (+50)
Rule 4: Suspicious 24-bit (+30)
Rule 9: Compression Artifacts (+15 / +30 / +50, by artifact count)
Rule 10: Multi-Segment Consistency (+20)

Protection Rules (Subtract points → Protects authentic):

Rule 5: High Variance Protection (-40)
Rule 6: High Quality Protection (-30)
Rule 7: Vinyl & Silence Analysis (-100)
Rule 8: Nyquist Exception (-50)
Rule 11: Cassette Detection (-60)

Optional ML Rule (requires pip install "flac-detective[ml]"):

Rule 12: CNN Classifier — sharpens borderline verdicts on suspect files; not applied unless the ML extra is installed

Report File Format

FLAC Detective saves a detailed text report:

FLAC AUTHENTICITY ANALYSIS REPORT
Generated: 2026-06-05 14:30:22
Analyzer Version: 1.3.0
Sample Duration: 30.0s
Scan Path: /music/collection
======================================================================

SUMMARY
======================================================================
Total files analyzed: 245
Authentic files: 215 (87.8%)
Warning files: 18 (7.3%)
Suspicious files: 9 (3.7%)
Fake certain files: 3 (1.2%)

======================================================================
DETAILED RESULTS
======================================================================

[Individual file entries follow...]

Real-World Examples

Example 1: Cleaning Your Library

Scenario: You have 1000 FLAC files and want to identify fakes.

# Run analysis
flac-detective ~/Music/FLAC > analysis.txt

# Review summary
head -30 analysis.txt

# Find all fakes
grep "FAKE_CERTAIN" analysis.txt

# Find suspicious files
grep -E "SUSPICIOUS|FAKE_CERTAIN" analysis.txt

Result interpretation:

950 AUTHENTIC → Keep these
35 WARNING → Review manually
12 SUSPICIOUS → Replace if possible
3 FAKE_CERTAIN → Delete immediately

Example 2: Verifying Downloads

Scenario: You downloaded an album from the internet.

# Analyze the album
flac-detective "/downloads/Pink Floyd - DSOTM (2011 Remaster)"

# Check results

Outcomes:

All AUTHENTIC → Safe to import to library
Some WARNING → Check source reputation, verify samples
Any SUSPICIOUS/FAKE → Find better source

Example 3: Pre-Upload Quality Check

Scenario: Before uploading to Bandcamp/streaming service.

# Verify your mastered album
flac-detective "/projects/my-album/masters"

# Ensure all files are AUTHENTIC
# Fix any issues before upload

Example 4: Marketplace Purchase Verification

Scenario: Bought FLAC collection from seller.

# Verify authenticity
flac-detective "/purchased/jazz-collection"

# Calculate fake percentage
# >20% fakes → Request refund
# <5% fakes → Accept (normal variation)

Batch Processing

Process Multiple Folders

#!/bin/bash
# analyze-all.sh

for artist in ~/Music/FLAC/*/; do
    echo "Analyzing: $(basename "$artist")"
    flac-detective "$artist" --output "reports/$(basename "$artist").txt"
done

Find and Move Suspicious Files

#!/bin/bash
# quarantine-fakes.sh

mkdir -p ~/Music/quarantine

# Run analysis and save
flac-detective ~/Music/FLAC --format json > results.json

# Parse JSON and move files (requires jq)
jq -r '.files[] | select(.score >= 55) | .filepath' results.json | while read file; do
    mv "$file" ~/Music/quarantine/
done

Parallel Processing (Advanced)

#!/bin/bash
# Fast parallel analysis using GNU parallel

find ~/Music -name "*.flac" | parallel -j 4 "flac-detective {} --format json >> results.jsonl"

Docker Usage

Basic Docker Commands

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

# Analyze directory
docker run --rm \
  -v /path/to/music:/data \
  ghcr.io/guillain-rdcde/flac_detective:latest \
  /data

# Save report outside container
docker run --rm \
  -v /path/to/music:/data \
  -v /path/to/reports:/reports \
  ghcr.io/guillain-rdcde/flac_detective:latest \
  /data --output /reports/report.txt

Docker Compose

Create docker-compose.yml (Compose v2+ no longer requires a top-level version: key):

services:
  flac-detective:
    image: ghcr.io/guillain-rdcde/flac_detective:latest
    volumes:
      - ./music:/data
      - ./reports:/reports
    command: /data --output /reports/analysis.txt

Run:

docker-compose up

Windows Docker Examples

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

Best Practices

1. Regular Library Audits

# Monthly check
flac-detective ~/Music/FLAC --output "reports/audit-$(date +%Y%m).txt"

2. Verify Before Archiving

Always check files before long-term storage:

flac-detective /staging/to-archive
# Only archive if all AUTHENTIC

3. Document Questionable Files

Keep a log of WARNING files:

grep "WARNING" report.txt > warnings.txt
# Review periodically

4. Use Multiple Tools for Confirmation

FLAC Detective is excellent but not perfect:

Visual inspection with Spek for spectral analysis
Listen with quality headphones for audible artifacts
Cross-reference with multiple sources when uncertain

5. Understand Your Sources

Different sources have different characteristics:

Vinyl rips: May trigger Rule 7 (protected)
Cassette transfers: May trigger Rule 11 (protected)
High-quality MP3 320: Rule 6 provides some protection
Streaming rips: Often SUSPICIOUS or FAKE_CERTAIN

Troubleshooting

Issue: High False Positive Rate

Symptoms: Many authentic files marked as SUSPICIOUS

Causes:

Vinyl or cassette sources
Aggressive mastering
Special audio processing

Solution: Check if files are protected by Rules 7 or 11. If not, file a bug report with samples.

Issue: Slow Performance

Symptoms: Analysis takes >10 seconds per file

Causes:

Network drives
Very large files (>100MB)
Slow disk I/O

Solutions:

# Use shorter sample duration
flac-detective /music --sample-duration 15

# Copy to local disk first
cp -r /network/music /tmp/local-copy
flac-detective /tmp/local-copy

Issue: “ModuleNotFoundError”

Symptoms: Python import errors

Solution:

# Reinstall dependencies
pip install --upgrade flac-detective

# Or install from source
pip install -e ".[dev]"

Issue: Corrupted FLAC Files

Symptoms: “FLAC decoder error” messages

Solution: Auto-repair is enabled by default — just re-run the command and the tool will attempt to repair unreadable files transparently. For manual repair outside FLAC Detective:

flac --verify --decode-through-errors file.flac

Issue: Docker Volume Permissions

Symptoms: “Permission denied” in Docker

Solution (Linux):

# Run with current user
docker run --rm \
  --user $(id -u):$(id -g) \
  -v /path/to/music:/data \
  ghcr.io/guillain-rdcde/flac_detective:latest \
  /data

Advanced Tips

Customize Thresholds (Python)

from flac_detective import FLACAnalyzer

analyzer = FLACAnalyzer(sample_duration=45.0)
# Analyze with custom parameters

Integration with Music Players

# Create playlist of authentic files
flac-detective ~/Music --format json | jq -r '.files[] | select(.score <= 30) | .filepath' > authentic.m3u

Automated Quality Monitoring

# Cron job: daily library check
0 2 * * * /usr/local/bin/flac-detective ~/Music --output ~/reports/daily-$(date +\%Y\%m\%d).txt

Getting More Help

Detailed technical info: Technical Details
Python API usage: API Reference
Development & bugs: Contributing
Installation issues: Getting Started

Happy analyzing! For questions, visit GitHub Discussions.