videobeaux — meta_extractionion
================================

## Description

`meta_extraction` is a robust metadata extraction and analysis utility for video and audio files.  
It leverages `ffprobe` and optional `ffmpeg` filters to capture **technical metadata**, **black-frame detection**, **audio loudness analysis**, and **sampled visual summaries**.

This function is useful for Quality Control (QC), editorial preparation, archival metadata generation, and automated video insight pipelines.

---

## Features

- **Comprehensive ffprobe core metadata**
  - Format, streams, codecs, durations, bitrates, resolution, color profile, and tags.
- **Sampled frame analysis**
  - Extract visual snapshots every N seconds.
  - Optionally compute histogram/mean color data.
- **Black frame detection**
  - Detect fade-ins/fade-outs or black commercials gaps.
- **EBU R128 Loudness**
  - Integrated Loudness (LUFS), LRA, True Peak.
- **Combined JSON catalog**
  - Merges all collected data into a structured metadata report.

---

## Why Use It

### 1. Quality Control (QC)
Detects black segments, silence, or loudness inconsistencies automatically.

### 2. Automated Asset Management
Generate sidecar JSON metadata for cataloging and search indexing.

### 3. Archival Provenance
Document codec info, stream layout, aspect ratio, and other preservation details.

### 4. Edit Prep
Helps identify fades and loudness ranges to pre-trim or normalize clips before editing.

---

## Inputs & Outputs

**Inputs**
- `-i / --input` : Input file (video or audio).  
- Optional sampling & detection flags.

**Outputs**
- `--outputfile`: Output JSON metadata file.  
  If omitted, defaults to `<input>.videobeaux.meta.json`

### Example JSON Structure
```json
{
  "source": "bbb.mov",
  "format": { "duration": 8.41, "size": 45678123, "bitrate": 876000 },
  "streams": [
    { "type": "video", "codec": "h264", "width": 1920, "height": 1080 },
    { "type": "audio", "codec": "aac", "channels": 2, "samplerate": 48000 }
  ],
  "blackdetect": [ { "start": 0.00, "end": 0.20, "duration": 0.20 } ],
  "loudness": { "integrated": -14.2, "lra": 3.5, "truepeak": -1.1 },
  "samples": [ "frame_0001.jpg", "frame_0002.jpg", "..." ]
}
```

---

## Key Flags

| Flag | Description |
|------|--------------|
| `--sample-frames` | Enable frame sampling for visual snapshots |
| `--sample-stride` | Seconds between frame samples (default 0.5s) |
| `--sample-limit` | Max number of frames to sample |
| `--blackdetect` | Run black frame detection |
| `--black-pic-th` | Pixel threshold for black detection (default 0.06) |
| `--black-dur-min` | Minimum duration for black detection (default 0.06s) |
| `--loudness` | Run EBU R128 loudness analysis |
| `--outputfile` | Output metadata JSON |
| `-F` | Force overwrite existing output file |

---

## Example Commands

### 1. Basic Probe (format + streams + chapters)
```bash
videobeaux -P meta_extraction   -i ./media/bbb.mov   --outputfile ./out/outbbb_meta_basic.json -F
```

### 2. Frame Sampling
```bash
videobeaux -P meta_extraction   -i ./media/bbb.mov   --outputfile ./out/outbbb_meta_sampled.json   --sample-frames --sample-stride 0.5 --sample-limit 200 -F
```

### 3. Black Detection (commercial fade detection)
```bash
videobeaux -P meta_extraction   -i ./media/bbb.mov   --outputfile ./out/outbbb_meta_black.json   --blackdetect --black-pic-th 0.08 --black-dur-min 0.08 -F
```

### 4. Loudness Measurement
```bash
videobeaux -P meta_extraction   -i ./media/bbb.mov   --outputfile ./out/outbbb_meta_loud.json   --loudness -F
```

### 5. All-in-One Comprehensive QC Report
```bash
videobeaux -P meta_extraction   -i ./media/bbb.mov   --outputfile ./out/outbbb_meta_full.json   --sample-frames --sample-stride 0.5 --sample-limit 200   --blackdetect --black-pic-th 0.10 --black-dur-min 0.10   --loudness -F
```

---

## Performance Notes

- Frame sampling and loudness analyses invoke full decoding → expect increased runtime.
- ffprobe-only mode is extremely fast (metadata only).
- Works with all FFmpeg-supported containers (MOV, MP4, MKV, WEBM, MXF, WAV, etc.).

---

## Best Practices

- Use **ffprobe-only** mode (`no --sample-frames/--blackdetect/--loudness`) for mass ingestion.
- Use **blackdetect** for commercial-cut or fade timing analysis.
- Use **loudness** when targeting broadcast spec (-23 LUFS EBU or -14 LUFS web).
- Combine **sample-frames + loudness** for advanced QC dashboards.

---

## Troubleshooting

- Ensure FFmpeg/ffprobe installed and in PATH.
- For noisy blackdetect, raise `--black-pic-th` slightly.
- Loudness requires `ebur128` filter; ensure FFmpeg built with it (`ffmpeg -filters | grep ebur128`).

---

## Future Enhancements

- Scene detection and color histogram summaries.
- Waveform extraction for audio visualization.
- Optional export to CSV for large-scale audits.