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

Three formats, three 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`

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

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-03 14:30:22
Analyzer Version: 1.1.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.