imf-panscan-metadata

Artist-authored pan-and-scan metadata for deriving HD outputs from matted UHD IMF masters.

Status: independent proof-of-concept. Not an official SMPTE publication or standards project. See NOTICE.md.

Thesis

A small, validatable metadata model can carry creative framing decisions for alternate aspect-ratio deliveries — instead of trapping those decisions in baked alternate masters, NLE projects, or vendor-specific notes. The same metadata can drive any compatible renderer to produce the alternate deliverable deterministically.

First concrete case: a 2.39 feature mastered as a 3840×2160 UHD IMF (Application #2E ProRes), deriving a 1920×1080 1.78 HD output with approved per-shot framing.

What's in the repository

packages/core              schema, crop math, validation, render-plan, JSON + XML IO
packages/interchange       CMX 3600 EDL parser + Resolve FCP XML (xmeml) parser
packages/ffmpeg-renderer   filter_complex builder, output presets, ffmpeg execution
apps/cli                   imf-panscan {init, validate, inspect, render, export-xml}
apps/electron              authoring UI (main / preload / renderer, Bradford dark theme)
docs/                      proposal, architecture, CLI reference, keyboard shortcuts,
                           metadata schema reference, standards references
examples/schema            JSON Schema for v0 metadata
examples/metadata          sample static + dynamic JSON + XML examples
examples/reports           sample validation report

Current capabilities

• Schema v0 (org.smpte.demo.imf-panscan.v0) — JSON + XML representations, JSON Schema, validation with structured issue codes.
• Cut-list import — CMX 3600 EDL and Resolve "FCP XML" (xmeml v5). 215 real shots imported cleanly from the test asset.
• Composition timeline — shots start at frame 0; optional source.sourceOffsetFrames for IMFs with pre-picture leader.
• Per-shot presentation mode — crop (default, scaled crop window) or letterbox (no crop, fit-with-blanking for titles, credits, intros).
• Output target presets — HD 1080, UHD, HD 4:3, DVD 4:3, 1.85 Vista, 2.39 Scope, 1:1 Square, 9:16 Vertical, Custom. Changing target re-centers every shot's crop.
• FFmpeg renderer — ProRes 422 HQ / ProRes 422 / H.264 review. Single filter_complex of per-shot trim → (crop|pad) → scale → concat.
• Electron authoring UI — IMF package directory picker, lazy-loaded shot thumbnails, draggable + corner-resizable crop with aspect lock, scroll/pinch zoom on the source, in-shot loop playback with pause + arrow-key scrub, title-safe (90%) / action-safe (95%) / center crosshatch overlays, dark mask over non-cropped area, auto-saved sidecar panscan.json in the IMF package directory.
• Render proof — verified against a 2.39 UHD IMF master (ANARCHIST) producing 1920×1080 ProRes 422 HQ output with correct per-shot framing.

Quick start

# install + build everything
npm install
npm run build

# run tests (currently 34/34 passing)
npx vitest run

# launch the authoring UI
./node_modules/.bin/electron apps/electron

# or use the CLI
node apps/cli/dist/index.js init \
  --source /path/to/IMF/VIDEO.mxf \
  --xml /path/to/sequence.xml \
  --out panscan.json

node apps/cli/dist/index.js validate panscan.json
node apps/cli/dist/index.js inspect panscan.json
node apps/cli/dist/index.js render panscan.json \
  --source /path/to/IMF/VIDEO.mxf \
  --out output.mov --preset prores-hq

node apps/cli/dist/index.js export-xml panscan.json --out panscan.xml

Documentation

• docs/proposal.md — standards-facing proposal narrative for SMPTE / 35PM.
• docs/architecture.md — module layout and data flow.
• docs/metadata-schema.md — field-by-field schema reference.
• docs/cli.md — CLI command reference.
• docs/keyboard-shortcuts.md — Electron app shortcuts.
• docs/standards-references.md — SMPTE document pointers.

License

• Code: Apache-2.0 (LICENSE.md)
• Docs and examples: CC BY 4.0

See NOTICE.md for the standards-status disclaimer and CONTRIBUTING.md for contribution rules.