Video Footage Refinement · Video Prep
Prepare raw recordings into a bright, clear footage library organized by content and ready for editing. Deliver segmented videos with consistent enhancement, a continuous keep/drop list, source timecode mappings, and an optional merged version. The source is read-only. By default, preserve content order, original speed, original audio, aspect ratio, frame rate, and authentic courseware; do not add subtitles, BGM, logos, or poster packaging.
When independent promotional clips need to be produced from an entire recording, use the
final-cut handoff contract to export a verified
and a list of directly playable MP4 files for
. A fully enhanced version does not mean that content selection is complete; this boundary does not create another Skill.
Triggers
Activate when
- “Apply this bright look to the entire video and remove the low-quality, meaningless parts.”
- “Brighten this in-person course recording, split it by topic, and retain the substantive explanations and demonstrations.”
- “Help preprocess and segment this recording into enhanced, useful source clips.”
Do not activate when
- Only selecting photos for social media: hand off to .
- Only subtitles or chapter bars are needed: use transcription or chapter-generation capabilities.
- The final video requires fine editing, animation, packaging, and publishing specifications: hand off to .
- Uploading or publishing is required: follow separate publishing authorization; this Skill ends with local acceptance.
Runtime context
Read
and the
Profile contract on every run, and execute:
bash
python3 "$SKILL_DIR/scripts/profile_store.py" read --skill-id lov-media-preprocessor
Current request/parameters → environment → project context → this Skill’s records → shared Profile → defaults. Save only visual goals, editing preferences, and output preferences that the user explicitly asks to reuse across sessions; do not write one-off paths, subtitles, personal identities, or inferred values to long-term records.
bash
python3 "$SKILL_DIR/scripts/profile_store.py" record --skill-id lov-media-preprocessor --path records.visual_style --value '"bright-documentary"' --confirm
After saving, report the canonical Profile location. First read the composition boundary: this is a Single + standalone Python CLI, and each stage shares the source/analysis/plan contract. External Skills hand off only through files. New segment names and descriptions are subject to the branding gate; transcripts, courseware, and source identifiers must not be rewritten.
Workflow (MANDATORY)
1. Inputs and completion criteria
Use the provided video and approved visual references directly. Ask through the host AskUserQuestion or an equivalent questioning tool only when missing information would materially affect the result; do not ask the user to select a technical engine.
bash
python3 "$SKILL_DIR/scripts/media_preprocessor.py" probe "$VIDEO"
Confirm the duration, audio/video tracks, dimensions, frame rate, color tagging, source identity, and actual available space. For a large source, random-access it directly instead of copying tens of GB to the system drive. First estimate speed and output size using short windows, then select a derived directory with enough space; preserve the source project’s independent tracks.
By default, segment by complete content units rather than a fixed number or duration. The plan must cover the entire video; sparse sampling cannot be claimed as frame-by-frame review. Record the actual status of analysis, transcription, enhancement, semantic judgment, and rendering separately.
2. Calibrate the bright direction for continuous video
Read the enhancement contract. Based on the approved photos, target clear subjects, natural skin tones, visible shadows, and readable projected slides. Select representative windows, such as backlit people and white/dark courseware. Video processing must remain stable across frames; do not regenerate people or text frame by frame.
First write a plan containing the source identity, a full-coverage timeline, and the
, then validate representative clips with
. Actually read back the output frames, continuous motion, and audio track; correct lifted blacks, overexposed skin, flicker, or unreadable slides. Approval of the photo style cannot replace video acceptance.
If the user also wants a fully enhanced version, generate an explicit no-cut plan with
after completing the technical index, and render it independently. This step does not depend on transcription; mark every interval as
and do not claim that semantic review is complete. Deliver the fully enhanced version and the concise segmented version in separate directories.
3. Full-video technical indexing and transcription
bash
python3 "$SKILL_DIR/scripts/media_preprocessor.py" analyze "$VIDEO" --interval 30 --workers 2 --output "$RUN/data/analysis"
Generate a source fingerprint, sampled frames, brightness/blur/dark-scene diagnostics, continuous audio-energy windows, and mono analysis audio.
is a luminance proxy for the lower region of the frame and cannot be claimed to automatically locate faces. Quality signals only flag windows for investigation and must not directly determine content value.
Reuse an existing timestamped transcript from the same source when available; otherwise, use the host ASR or the bundled local adapter:
bash
python3 "$SKILL_DIR/scripts/media_preprocessor.py" transcribe "$RUN/data/analysis/audio-16k.wav" --model "$ASR_MODEL" --language zh --output "$RUN/data/transcript"
Use the currently available quality tier and explicit parameters; do not silently switch to a faster tier for long videos. The CLI does not automatically download models or upload private course content. Cloud processing must follow host authorization, cost, and data boundaries. The local adapter runs
over context-aware audio chunks while retaining raw output, model/audio hashes, and progress.
On Apple Silicon, the same model can use a local MLX implementation. In a Python environment with
installed, add
--backend mlx --model "$MLX_MODEL_DIR"
. The directory must contain configuration and actual weights; the CLI does not download them implicitly. Normalize loudness only for the analysis track, disable cross-chunk duplicate prompts, and retain raw model output and low-confidence information; the source recording’s original audio is not changed.
When long silence or distant conversation causes looping hallucinations, add
(requires
). It selects only conservative probable-speech windows for ASR and retains a one-second margin before and after each window, along with the model hash and original timestamps. Skipped windows remain in the full-video index and cannot be treated as confirmed content-free or deleted directly.
If
or
is interrupted, add
to reuse only results whose source, model, and parameters match. When explicitly reusing an old transcript, pass
--reuse-asr "$OLD_ASR_RUN"
: the audio, model, and chunk coordinates must match, hashes must be verified for each chunk, and import provenance must be retained; incomplete chunks must not be imported. Before transcript
, do not claim that full-video semantic analysis is complete.
4. Intelligent selection and semantic segmentation
Read the segmentation contract. The Agent reads the complete transcript and reviews sampled frames and anomalous windows from across the entire video. Organize complete content by viewpoint, question, method, demonstration, result, Q&A, and speaker changes; do not divide the video evenly or select only the loudest portions.
- : contains unique information, an effective demonstration, or necessary context; if quality is poor but the content is important, prioritize enhancement and retention.
- : an invalid wait, abandoned attempt, or unusable empty scene verified through content, visuals, and boundaries, with no unique useful content.
- : evidence is insufficient or usability is uncertain; retain and mark it by default rather than silently deleting it.
Write a full-coverage
timeline, then validate it:
bash
python3 "$SKILL_DIR/scripts/media_preprocessor.py" plan "$RUN/data/analysis/analysis.json" --decisions "$RUN/data/decisions.json" --output "$RUN/data/plan.json"
Running without
generates only a technical proposal. Record concrete evidence and the actual review status for every deletion; do not insert false Boolean values merely to pass validation. Inspect original-audio evidence and surrounding semantics at each cut, preserving word beginnings and endings; silence, ASR punctuation, and quality scores cannot independently determine a cut. If the host cannot directly listen and review, conservatively locate cuts using the complete transcript, word-level time estimates, the continuous waveform, and frames around each cut, and explicitly record that manual listening was not performed. If evidence conflicts or useful content could be lost, expand the retained range or mark it as
.
5. Sequential rendering and source time mapping
bash
python3 "$SKILL_DIR/scripts/media_preprocessor.py" render "$VIDEO" --plan "$RUN/data/plan.json" --output "$RUN/videos" --concatenate
Use high-quality CPU H.264 by default. When explicitly supported by the platform, select
--codec h264_videotoolbox --bitrate-mbps 14
, and read back courseware and skin tones over a short window before processing the entire video. Do not claim that encoding parameters are lossless. Keep each segment’s grade stable, recalibrating only after a clear scene change rather than chasing exposure on every frame.
On macOS with Swift compilation tools installed, add
--engine metal --codec h264_videotoolbox
. The bundled native backend samples numerical enhancements into a 65³ color lookup table and processes consecutive frames with Core Image; it must first be compared against an FFmpeg sample, and clip audio-video synchronization must be verified. FFmpeg remains the default across platforms. Build artifacts and logs must be written only to the run directory; the source package must not contain binaries.
If the entire video has already been enhanced and the content plan is completed afterward, use
--prepared-run "$FULL_ENHANCED_RUN"
to reuse the same-source, complete, same-grade enhanced master and precisely re-encode the segments with FFmpeg. The tool verifies the master hash and full-coverage source mapping and does not brighten the video again. This is a second encode, so an appropriate bitrate and readback are required; do not claim that it is lossless. Do not use ordinary stream copy to conceal frame-count or duration discrepancies at B-frame edit points.
Export both
and
. Deleted segments must remain in the source and plan. Write source start/end times and the new timeline to the manifest. Encoded segments may be merged without further compression into
.
verifies the source, plan, parameters, and completed-file hashes and does not overwrite unknown outputs.
6. Final readback and handoff
bash
python3 "$SKILL_DIR/scripts/media_preprocessor.py" verify "$RUN/videos" --decode
Check file decoding, duration, audio tracks, starting synchronization, dimensions, hashes, and source time mappings; actually inspect representative clips, scene changes, and every high-risk cut. When listening is available, sample the joins; otherwise, compare the source waveform with the output audio track, record the actual method and limitations, and do not claim manual listening. Fine filler-word removal requires word-level alignment and retranscription around edit points; coarse segmentation must not be substituted for fine editing.
Deliver numbered videos, an optional merged version,
,
,
, and a validation report. The footage library must use one player, topic search, and usable/review filters rather than loading dozens of videos simultaneously. Report source duration, retained/deleted/review durations, segment count, actual specifications, rationale, and limitations. Only state that full-video processing is complete after the entire video has been rendered and read back; when only a sample was validated, state that accurately.
Downstream handoff occurs through files: photo selection reads enhanced segments and the source mapping, formal editing reads segment files, original audio, and the timeline, and chapter bars read the finalized timeline. Each downstream stage is responsible for its own acceptance and must not replace this Skill’s image-quality and content-completeness acceptance.
Validation
bash
python3 "$SKILL_DIR/scripts/validate_skill.py" "$SKILL_DIR"
python3 "$SKILL_DIR/scripts/check_workflow.py"
Synthetic tests validate engineering boundaries only and must not be presented as real user cases. See the cases for real input and output examples.