Communitygithub.com

MelonTse/video-archive-skill

Helps users analyze local video, define compression goals, compare samples, batch-compress after confirming quality, and archive originals. Designed for home video and video material compression archiving; not for creative editing or unverified HDR/Log color conversion.

What is video-archive-skill?

This skill enables users to compress and archive video files using their own local AI environment. It first checks the environment for dependencies (Python 3.9+, FFmpeg, ffprobe), then analyzes source material to report metadata such as resolution, bitrate, color tags, and audio tracks. Based on user-defined goals (e.g., home viewing, long-term preservation), it recommends 2–3 candidate CRF values and generates representative samples for visual comparison. Once the user approves a specific sample and batch range, it executes batch compression sequentially, verifies output integrity, and guides archival of original files. The skill supports macOS (primary), uses POSIX file locks, relies on FFmpeg codecs (libx265/libx264), and does not require any API keys or upload material to external services. It avoids destructive operations (no deletion of originals) and provides clear fallback for unsupported features like HDR conversion or subtitles.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MelonTse/video-archive-skill/tree/HEAD/.agents/skills/video-archive

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Video Compression and Archiving

Use the user's own local AI environment to complete video compression. First check the environment, then analyze the material, ask about the target, recommend parameters, provide samples; only after receiving user confirmation on specific samples and batch scope proceed with batch execution, and guide archiving. Do not describe "automatic verification passed" as the user having accepted the quality.

The accompanying scripts only depend on Python 3.9+ standard library, FFmpeg, and ffprobe. The first version is primarily for macOS; execution depends on POSIX file locks. Ordinary chat tools that cannot read/write local files and execute commands can only provide guidance, not claim to have processed video. The scripts do not require a model API Key and do not upload material.

Entry and Task Directories

  • Find the absolute path of this Skill. Below, <script> refers to the absolute path of scripts/workflow.py; <task> is a new, independent task directory created on the user's machine. Do not write results back into the installed Skill package.
  • Create the task directory outside the user's original source material directory; each batch of tasks independently saves its manifest, plan, samples, confirmations, and status. Create a separate task for new or changed material; keep the original plan for already started batches.
  • The user's explicit instructions and already given authorization take precedence over this Skill's default suggestions. Do not repeatedly ask about already determined goals, paths, or choices. When user requirements exceed the script's supported scope, explain the limitations and prepare a separate plan; do not quietly modify scripts or downgrade processing.

1. Environment Check and Installation Guide

First, confirm the terminal can find Python, then run python3 "<script>" doctor. Check Python version, FFmpeg, ffprobe, libx265/libx264, and necessary options. When missing, read environment.md, explain what is missing, installation methods, and impact. If the user has already requested installation, execute within that scope; otherwise, first provide specific commands for the user to choose the execution method. Do not mistakenly report missing tools as "no video." Only continue after verifying availability post-installation.

2. Read-Only Analysis of Material

Confirm the source directory and output directory, run init, scan; see operations.md for commands. Scan read-only media metadata, do not start encoding. Report to the user: count, size, duration, resolution/frame rate, color depth, color tags, audio tracks, and main profiles; separately list files that cannot be read and those requiring review.

BT.709 tags do not prove shooting mode and do not rule out Log; combine with user-provided shooting information for judgment. The first version executor only automatically processes H.264/HEVC, 4:2:0, 8/10-bit material with complete BT.709 tags; HLG/PQ/HDR, subtitles, multiple primary video streams, and unknown colors are listed separately as REVIEW and are not automatically converted to SDR. Known Log material should be handled separately first; do not give the user assurances about color correctness.

3. Ask About Usage Goals

First explain the scan findings, then only ask questions that are not yet clear and would change the plan: primary use (home viewing / long-term preservation / continued editing / sharing), priority between quality and size, acceptable processing time, playback device or file size limits. Generally combine into one brief round of questions; do not make the user fill in irrelevant parameter forms.

For archiving, also explain two options: keep originals in place; or, after successful compression and re-verification, move them to a specified subdirectory of the original parent directory. Default is keep; moving requires the user's explicit choice; do not provide functionality to delete originals. Determine this choice first, then generate sample configurations.

4. Recommend Comparable Options

Following quality.md, connect the user's goals to the actual material. Explain the encoder, preset, 2–3 candidate CRFs, parameters to preserve, expected trade-offs, and uncertainties. Do not treat CRF22, a specific camera, or a particular directory as a fixed rule for all users.

Create plan.json inside the task; format see operations.md. Save the user's goals and recommendation rationale; select only those Profiles with a clear intention to process this time; each selected Profile must have at least one sample. Pick representative segments for motion, texture, dark areas, etc.; when metadata cannot identify scenes, explain and ask the user to specify key segments or assist with viewing. When there are many material types, narrow the scope in batches.

Default behavior: preserve resolution, frame rate, aspect ratio, orientation, color depth, known color metadata, and copy all audio tracks. The script only copies the primary video and audio streams; auxiliary data tracks / cover art will not enter the compressed copy; state this in the plan. Scaling, color grading, HDR conversion, audio re-encoding, hardware encoding, strict target file size, and intermediate formats for editing are not within the first version's automatic execution scope.

5. Samples and Manual Viewing

Run sample, display sample-report.md, reference, and local paths of each candidate. All candidates are encoded from the same reference segment. Explain capacity and time cost, and guide the user to compare details, motion, dark areas, gradients, audio-video sync, and actual playback devices; keyframe trimming may cause slight duration offsets.

Do not run approve, run, or start before the user explicitly accepts a candidate. If the user is unsatisfied, adjust the plan, re-sample, then collect conclusions; do not guess that it "meets requirements." The script's PASS is a structural check, not a frame-by-frame quality proof.

6. Batch Execution After Confirmation

Show the range and output mapping of plan --crf N, the selected CRF, archiving strategy, and sample-based estimates of time/capacity. After the user confirms availability and agrees to execute this batch, use approve to record the real user response; if the response already covers these matters, do not ask again. The confirmation record can restore context, but does not prove that the response came from a real person.

After calling start, use status and logs to confirm actual running. Batch processes individual FFmpeg jobs sequentially; safe pausing is only possible after the current file finishes encoding, verification, and archiving. Use pause; do not pause by killing the process. resume clears the pause request; start after the controller exits; do not start a new controller if one is already running. Do not maintain high-frequency AI polling for long tasks. Only use notification/scheduling capabilities provided by the user's AI system if the user requests to be notified later.

Changes to parameters, paths, scope, or samples invalidate old confirmations; already started tasks resume with the original plan; create a new task for changes. Report failures and items pending review separately. Breakpoint recovery works per file; unfinished videos are re-encoded from the beginning.

7. Verification and Archival Delivery

Following archival.md, explain the correspondence between compressed versions, originals, and task records. Summarize completed/skipped/pending review items, capacity difference of compressed copies, current location of originals, and recovery method. The compression ratio in the report does not equal actual freed space: original files are retained, so disk usage during the current workflow typically increases.

Do not overwrite original files or existing output; unverified temporary files are not delivered as final products. Automatic verification is based on ffprobe, size/mtime, not content hash or full-frame decoding. If the user needs stricter verification or backup, design corresponding steps; moving directories is not a backup. Keep the task directory so that the user or another AI can recover and interpret results.

Related Skills