mirror of
https://github.com/vondas-network/videobeaux.git
synced 2026-01-27 09:11:09 +01:00
88 lines
3.6 KiB
Markdown
88 lines
3.6 KiB
Markdown
# meta_extraction
|
||
|
||
## Description
|
||
Extracts detailed metadata—such as codecs, bitrates, dimensions, color information, loudness, black-frame metrics, and stream structure—from any media file.
|
||
|
||
## Purpose
|
||
`meta_extraction` is designed to provide deep insight into media characteristics for:
|
||
- archival workflows,
|
||
- QC diagnostics,
|
||
- automated processing pipelines,
|
||
- research or analytics tasks,
|
||
- downstream editing or transcoding decisions.
|
||
|
||
It can scan frames, detect black segments, analyze loudness, and output structured metadata for additional tools.
|
||
|
||
## How It Works
|
||
1. **Stream Inspection**
|
||
Reads the container and stream-level metadata (codec, resolution, color space, duration, bitrates, etc.).
|
||
2. **Frame Sampling**
|
||
- `sample_frames` sets how many frames to analyze.
|
||
- `sample_stride` controls spacing between sampled frames.
|
||
- `sample_limit` prevents excessive scanning on long videos.
|
||
3. **Black Frame Detection**
|
||
If enabled, black detection evaluates frames for luminance thresholds.
|
||
- `black_pic_th` tunes sensitivity.
|
||
- `black_dur_min` sets minimum black duration to report.
|
||
- `blackdetect` toggles the feature.
|
||
4. **Loudness Analysis**
|
||
When enabled, checks LU, LRA, and peak values for broadcast loudness compliance.
|
||
5. **Output**
|
||
Metadata is written to a structured file (JSON or text depending on implementation).
|
||
|
||
## Program Template
|
||
videobeaux -P meta_extraction \
|
||
-i input.mp4 \
|
||
-o output.mp4 \
|
||
--outputfile VALUE \
|
||
--sample_frames VALUE \
|
||
--sample_stride VALUE \
|
||
--sample_limit VALUE \
|
||
--blackdetect VALUE \
|
||
--black_pic_th VALUE \
|
||
--black_dur_min VALUE \
|
||
--loudness VALUE
|
||
|
||
## Arguments
|
||
|
||
- **outputfile** — Name of the metadata output file produced by the scan.
|
||
- **sample_frames** — Total number of frames to sample for inspection.
|
||
- **sample_stride** — Number of frames skipped between each analyzed frame.
|
||
- **sample_limit** — Maximum frame count allowed during sampling.
|
||
- **blackdetect** — Enables detection of black frames and black segments.
|
||
- **black_pic_th** — Pixel-level threshold for determining whether a frame is considered black.
|
||
- **black_dur_min** — Minimum duration (seconds) of black required to register as a black segment.
|
||
- **loudness** — Enables loudness analysis (LUFS, LRA, true peak).
|
||
|
||
## Real World Example
|
||
videobeaux -P meta_extraction \
|
||
-i myvideo.mp4 \
|
||
-o meta_extraction_styled.mp4 \
|
||
--outputfile EXAMPLE \
|
||
--sample_frames EXAMPLE \
|
||
--sample_stride EXAMPLE \
|
||
--sample_limit EXAMPLE \
|
||
--blackdetect EXAMPLE \
|
||
--black_pic_th EXAMPLE \
|
||
--black_dur_min EXAMPLE \
|
||
--loudness EXAMPLE
|
||
|
||
## Technical Notes
|
||
- Metadata extraction is extremely fast because only sampled frames are examined.
|
||
- Excessive `sample_frames` or low `sample_stride` may increase scan time.
|
||
- Black detection is luminance-based; noisy or low-light footage may require adjusted thresholds.
|
||
- Loudness metrics follow broadcast-standard measurement curves.
|
||
- Great for building metadata catalogs or dashboards.
|
||
|
||
## Recommended Usage
|
||
- Preflight analysis before encoding or delivery.
|
||
- QC checks for broadcast, festival, or archival compliance.
|
||
- Automated pipelines needing structural insight into media files.
|
||
- Generating metadata for UI previews, asset managers, or machine-learning datasets.
|
||
|
||
## Quality Tips
|
||
- Use `black_pic_th` between **0.05–0.10** for most SDR footage.
|
||
- Increase `sample_stride` to speed up scans on long files.
|
||
- Keep `sample_limit` reasonable to avoid unnecessary overhead.
|
||
- Enable `loudness` for interview, dialog, or broadcast deliverables.
|