KoNViD-150k-A (K150K-A) — Feature Extraction¶

KoNViD-150k-A is the largest publicly available no-reference video quality corpus: 152,265 H.264 clips each annotated with a crowd-sourced mean-opinion-score (MOS). This document covers how to extract the 26 FEATURE_NAMES columns (the FULL_FEATURES pool of Research-0026 plus vmaf) from it for tiny-AI model training. For CHUG (a full-reference corpus) use chug-ingestion.md instead.

Quick start¶

# Smoke-test: 100 clips (~3 min at 8 workers on a 32-thread CPU)
python ai/scripts/extract_k150k_features.py --limit 100 --threads-cuda 8

# Full run (background, ~60–80 h at 8 workers)
nohup python ai/scripts/extract_k150k_features.py \
    --threads-cuda 8 --threads 4 \
    > runs/k150k_extract.log 2>&1 &
echo "PID $!"

Both commands resume automatically from the .done checkpoint if interrupted.

Throughput¶

Default K150K throughput is achieved via parallel CPU workers (--threads-cuda). Benchmarking showed that 540p 5-second clips are CPU-bound: CUDA context initialisation overhead makes the GPU binary 3.7× slower than CPU for this clip geometry. At 8 parallel workers the CPU path achieves 0.5–0.7 clip/s vs the 0.14 clip/s serial baseline — a 4–5× improvement. See ADR-0383 and Research-0096 for the full investigation.

ai/scripts/train_konvid_mos_head.py --feature-parquet <path> consumes the resulting FULL_FEATURES parquet files directly and maps <feat>_mean columns onto the trainer's canonical feature vector.

Build¶

The system /usr/local/bin/vmaf v3.0.0 is not compatible — it lacks ssimulacra2 and motion_v2. Build the fork binary:

meson setup core/build-cpu core \
    -Denable_cuda=false -Denable_sycl=false --buildtype=release
ninja -C core/build-cpu

Optional CUDA extraction uses a CUDA-capable fork binary for the stable CUDA feature set and a CPU fork binary for the residual feature pass:

meson setup core/build-cuda core \
    -Denable_cuda=true -Denable_sycl=false --buildtype=release
ninja -C core/build-cuda

python ai/scripts/extract_k150k_features.py \
    --vmaf-bin core/build-cuda/tools/vmaf \
    --cpu-vmaf-bin core/build-cpu/tools/vmaf

For larger local FR-from-NR corpora, a CUDA-capable --vmaf-bin enables the split extractor path: stable CUDA twins run on the GPU, while residual float_ssim / cambi extraction stays on the CPU binary.

The split is intentional. The CUDA binary exposes GPU twins for most FULL_FEATURES, but the all-feature --backend cuda auto-selection path can double-register feature keys on mixed extractor bundles. The extractor uses explicit CUDA feature names for the GPU-safe pass and keeps float_ssim / cambi on the CPU binary so the emitted feature-column schema stays unchanged.

Options¶

Output schema¶

The output parquet has one row per clip: 8 identity columns plus one _mean and one _std column for each of the 26 FEATURE_NAMES entries (60 columns):

Runs that pass --metadata-jsonl append sidecar metadata columns such as content_id, bitrate_ladder_id, mos_raw_0_100, split, chug_split_key, and chug_split_policy. The MOS-head trainer preserves split for held-out validation and uses <feat>_mean values for the canonical feature columns it knows about.

A parquet extracted without --metadata-jsonl can be enriched afterwards:

python ai/scripts/enrich_k150k_parquet_metadata.py \
    --features-parquet .corpus/chug/training/full_features_chug.parquet \
    --metadata-jsonl .corpus/chug/chug.jsonl

The utility rewrites the output atomically, fills only missing metadata cells by default, and prints a JSON summary with matched and missing row counts.

Feature order follows FEATURE_NAMES in ai/scripts/extract_k150k_features.py (column-order-locked — see ai/AGENTS.md §K150K-A corpus extraction).

Parallelism architecture¶

Each worker in the ProcessPoolExecutor independently:

1. Decodes one clip to a worker-private YUV file at --scratch-dir/<stem>_w<id>_<pid>.yuv.
2. Scores it via vmaf with --threads <N>.
3. Aggregates per-frame metrics.
4. Deletes the YUV file immediately (keeps peak scratch usage to ~8 × 120 MB = ~1 GB).
5. Returns the row dict to the main process.

The main process collects results from as_completed(), writes the .done checkpoint, and flushes the parquet every --flush-every clips. Worker failures are isolated — one bad clip emits a FAIL log line and does not abort the run.

FR-from-NR adapter¶

K150K-A carries no reference video. To run full-reference libvmaf extractors the script uses the FR-from-NR adapter (ADR-0346): the decoded YUV is passed as both --reference and --distorted. This has two consequences:

• Informative features (cambi, motion, motion2, motion3) reflect actual content properties and are useful for training.
• Constant features (ADM, VIF, SSIM, VMAF) floor at their identity value; null features (ciede2000, psnr_hvs) are all-NaN. Downstream training must drop or impute these columns.
• ssimulacra2 is not in the schema: self-vs-self it returns about 100 for every frame (ADR-0431).

Hardware requirements¶

Restartability¶

An interrupted run resumes from its .done checkpoint: a file next to --out (same path with a .done extension) that lists completed clip names, one per line. On restart the script skips clips already listed.

Two durability layers cover the write path (Research-0135, ADR-0862):

1. A <out>.rows.jsonl staging file receives one line per completed clip, so a crash mid-run does not lose features that already finished their VMAF pass. It is the in-run write-ahead log.
2. The parquet at <out> is written exactly once at the end through a .tmp rename, then fsync'd (file and parent directory) before the staging file is unlinked.

If the staging file survives a crash, its rows are merged into the parquet during the no-op or end-of-run write.

Consistency check (ADR-0862)¶

Since 2026-05-30, before the no-op early exit returns, the script compares len(.done) against _parquet_row_count(<out>) plus any rows recovered from the staging file. A mismatch typically means a prior run crashed after the parquet rename but before the staging unlink, on a filesystem that does not order metadata and data writes.

End-of-run accounting¶

The post-write path asserts len(rows) == len(recovered_rows) + ok before writing the parquet. On mismatch it raises RuntimeError and preserves the staging file for forensic recovery instead of letting a broken parquet land.

Further reading¶

• ADR-0383 — parallelism redesign decision
• Research-0096 — CUDA investigation and timing data
• ADR-0362 — original corpus integration design
• ADR-0346 — FR-from-NR adapter pattern
• ADR-0862 — .done vs parquet consistency check on restart
• Research-0026 — cross-metric feature-fusion design; the current FULL_FEATURES definition lives in ai/data/feature_extractor.py.