Skip to main content
Agent skill

Video 4k Normalization

Normalizes a single video clip to unified 3840×2160 60FPS H.265 Main10 40Mbps + AAC 320kbps BT.709 SDR MP4 4K master (FFmpeg re-encode, HDR tone-mapped). Use before hard-cut merge when 4K (or near-4K) clips differ in color space, HDR/SDR, fps, or size. Triggers: video-4k-normalization, 4K normalization, video normalization, media conform, unify encode, color conform, tone map HDR, prepare for video-merge, mixed HDR/SDR.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Video 4k Normalization when an AI agent needs a reusable SKILL.md workflow for this job: Normalizes a single video clip to unified 3840×2160 60FPS H.265 Main10 40Mbps + AAC 320kbps BT.709 SDR MP4 4K master (FFmpeg re-encode, HDR tone-mapped). Use before hard-cut merge when 4K (or near-4K) clips differ in color space, HDR/SDR, fps, or size. Triggers: video-4k-normalization, 4K normalization, video normalization, media conform, unify encode, color conform, tone map HDR, prepare for video-merge, mixed HDR/SDR.

When not to use it

Skip Video 4k Normalization when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/video-4k-normalization
# Save SKILL.md to ~/.claude/skills/video-4k-normalization/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/video-4k-normalization/SKILL.md. For a shared project, commit the folder at .claude/skills/video-4k-normalization/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Video 4k Normalization skill for this task: Use Video 4k Normalization when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
61/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Video 4K Normalization

Re-encode a clip to one **merge-safe 4K master** (same delivery specs as `video-to-4k`, plus **unified BT.709 SDR color**):

| Spec | Value | |------|-------| | Resolution | 3840×2160 | | Frame rate | 60 FPS | | Video | H.265 Main10 (`libx265`, `yuv420p10le`) | | Video bitrate | 40 Mbps | | Audio | AAC 320 kbps | | Color | **BT.709 / bt709 / tv** (HDR → tone-mapped SDR) | | Container | MP4 (`.mp4`, `hvc1` tag) |

**Not** AI upscaling — use [`video-to-4k`](../video-to-4k/SKILL.md) first when SD/HD needs Real-ESRGAN quality. This skill uses FFmpeg `scale` + encode only.

## Why

Hard-cut [`video-merge`](../video-merge/SKILL.md) is stream-copy. Mixed **HDR (BT.2020 + PQ)** and **SDR (BT.709)** clips look fine alone, but after concat the player often applies the first clip's HDR tags to later SDR → oversaturated cuts. Normalization unifies pixels **and** color tags first.

## Rules

When this skill applies, read and follow [skill-dependency-manager](../skill-dependency-manager.md) — run scripts as documented, install missing tools into `.dependency/`.

- Run `normalize.py` through **`.dependency/python/python`**. Never use host `python` / `ffmpeg`. - **Never overwrite sources.** Outputs go under `video-4k-normalization/`. - Use the bundled script — do not hand-write equivalent FFmpeg commands. - **One file per run** — pass `--video` with a single file; repeat for each clip in a batch.

## Quick Start

```bash .dependency/python/python .ai/video-4k-normalization/normalize.py --video path/to/clip.mp4 ```

Example:

``` assets/shots/01.mp4 (HDR) → assets/shots/video-4k-normalization/01.mp4

assets/shots/10.mp4 (SDR) → assets/shots/video-4k-normalization/10.mp4 ```

Then hard-cut merge the `video-4k-normalization/` folder:

```bash .dependency/python/python .ai/video-merge/merge.py --folder path/to/clips/video-4k-normalization ```

## Defaults

| Setting | Default | Notes | |---------|---------|-------| | Target color | BT.709 SDR limited (`tv`) | HDR (PQ/HLG/BT.2020) → `hable` tone map | | Scale | FFmpeg lanczos to 3840×2160 | No Video2X | | FPS | Forced 60 | Frame dup/drop, not RIFE |

## Common Flags

`--video` · `-o` / `--output`

```bash .dependency/python/python .ai/video-4k-normalization/normalize.py --video clip.mp4 .dependency/python/python .ai/video-4k-normalization/normalize.py --video clip.mp4 -o out/masters/clip.mp4 ```

**Never overwrite source files.** Input must be a single video file (`--video`), not a directory. Supported inputs: `.mp4`, `.mkv`, `.mov`, `.avi`, `.webm`, `.wmv`, `.flv`, `.m4v`, `.mpeg`, `.mpg`, `.ts`, `.mts`, `.m2ts`, `.3gp`, `.ogv`.

## Agent Notes

1. Use the bundled script only. 2. Missing Python / FFmpeg → populate `.dependency/`, set `populated: true`, retry. 3. Tell the user `video-4k-normalization/` paths; they run `video-merge` on that folder when stitching. 4. For low-res quality upscale → `video-to-4k`, then optionally re-normalize if color still mixed. 5. Pipeline / filter details: [reference.md](reference.md)

## Tests

From repo root:

```bash .dependency/python/python .ai/video-4k-normalization/test_normalize.py ```

Manual CLI examples: [cli/video-4k-normalization.md](../../../cli/video-4k-normalization.md)

Intended uses

  • Use Video 4k Normalization when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.