mirror of
https://github.com/vondas-network/videobeaux.git
synced 2025-12-05 15:30:02 +01:00
147 lines
4.7 KiB
Plaintext
147 lines
4.7 KiB
Plaintext
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.
|