videobeaux/docs/programs/utilities/meta_extraction.md

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.