user-guide.md

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:

1. Listen to the file carefully
2. Check source credibility
3. Use complementary tool (e.g., Spek for visual spectral analysis)
4. 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:

1. Replace file from better source if available
2. Accept quality loss if no alternative
3. 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:

1. Delete the file
2. Find authentic source
3. 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.