# Getting Started with FLAC Detective

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

## Table of Contents

- [System Requirements](#system-requirements)
- [Installation](#installation)
- [First Analysis](#first-analysis)
- [Understanding Results](#understanding-results)
- [Next Steps](#next-steps)

## 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](https://ffmpeg.org/download.html) and add it to your `PATH`)
  - Verify: `ffmpeg -version`

### Optional (Recommended)
- **FLAC command-line tool**: used for the automatic repair of corrupted FLACs (and the
  standalone `python -m flac_detective.repair` duration-fixer)
  - Linux: `sudo apt-get install flac`
  - macOS: `brew install flac`
  - Windows: Download from [Xiph.org](https://xiph.org/flac/download.html)

## Installation

### Option 1: Install via pip (Recommended)

The easiest way to install FLAC Detective:

```bash
pip install flac-detective
```

Verify installation:

```bash
flac-detective --version
```

#### Optional: ML classifier (Rule 12)

The 12th scoring rule uses a bundled CNN to flag high-bitrate transcodes
that the heuristic rules miss. It is opt-in because PyTorch is a heavy
dependency:

```bash
pip install "flac-detective[ml]"
```

Without this extra, Rule 12 is a graceful no-op and the existing 11
heuristic rules run unchanged.

### Option 2: Install via Docker

Pull the pre-built Docker image:

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

Test it:

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

### Option 3: Install from Source

For development or the latest features:

```bash
# 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`):

```bash
# 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.

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

**Installed from source?** Pull the latest commits and reinstall:

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

To see what changed between versions, browse the [CHANGELOG](https://github.com/Guillain-RDCDE/FLAC_Detective/blob/main/CHANGELOG.md).

## First Analysis

### Analyze a Directory

```bash
# 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

```bash
flac-detective /path/to/song.flac
```

### Docker Usage

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
pip install --upgrade flac-detective
flac-detective --version
```

See [Upgrading to the Latest Version](#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:
```bash
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**:
```bash
# 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
```bash
# 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](user-guide.md)
2. **Understand how it works** → Read [Technical Details](technical-details.md)
3. **Use the Python API** → Read [API Reference](api-reference.md)
4. **Contribute or customize** → Read [Contributing](https://github.com/Guillain-RDCDE/FLAC_Detective/blob/main/.github/CONTRIBUTING.md)

## Getting Help

- **Questions**: [GitHub Discussions](https://github.com/Guillain-RDCDE/FLAC_Detective/discussions)
- **Bug reports**: [GitHub Issues](https://github.com/Guillain-RDCDE/FLAC_Detective/issues)
- **Documentation**: [Documentation Index](index.md)

---

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