video/skills/pipelines/screen-demo/compose-director.md

Compose Director - Screen Demo Pipeline

When To Use

Render the final screen-demo outputs. The quality bar is simple: the UI must be readable, the pacing must feel intentional, and the result must match the planned platform shapes.

Runtime Routing (MANDATORY first step)

Read edit_decisions.render_runtime first. Screen-demo compositions use three distinct runtimes depending on the demo shape:

• render_runtime="remotion" with TerminalScene — the preferred path for synthetic terminal/CLI/install flows. See .agents/skills/synthetic-screen-recording/.
• render_runtime="remotion" (other scenes) — for mixed screen-capture + animated overlays.
• render_runtime="hyperframes" — for custom synthetic HTML UI demos where CSS + GSAP express the UI naturally. Read skills/core/hyperframes.md. hyperframes lint and hyperframes validate must both pass before render.
• render_runtime="ffmpeg" — for simple cut/concat of real screen recordings without composition.

Silent swaps between runtimes are CRITICAL governance violations. If the locked runtime is unavailable, escalate per AGENT_GUIDE.md before substituting.

Pass proposal_packet to video_compose.execute() so the tool can directly confirm the runtime locked at proposal matches what edit_decisions says. Without it the in-tool swap check is skipped and you rely entirely on the reviewer skill to catch drift.

Prerequisites

Layer	Resource	Purpose
Schema	schemas/artifacts/render_report.schema.json	Artifact validation
Prior artifacts	state.artifacts["edit"]["edit_decisions"], state.artifacts["assets"]["asset_manifest"]	What to render
Tools	video_compose, audio_mixer, video_trimmer	Rendering capabilities
Playbook	Active style playbook	Quality targets

Process

1. Render For Legibility First

Prefer the simplest reliable render chain:

• trim and speed-adjust source footage,
• compose overlays and subtitles,
• mix audio only as much as needed,
• encode at a bitrate suitable for text-heavy content.

2. Choose Output Shapes Pragmatically

Platform	Aspect Ratio	Resolution	Notes
YouTube / docs	16:9	1920x1080 or higher	safest default for dense UI
LinkedIn feed	1:1	1080x1080	good compromise when vertical is too tight
Shorts / Reels / TikTok	9:16	1080x1920	only if crop plan is actually readable

If the source is 4K and text is tiny, keep a higher resolution when practical.

3. Compose In The Right Order

1. apply trims and speed changes,
2. apply crop and framing strategy,
3. place masks and overlays,
4. burn subtitles,
5. mix audio,
6. encode with text-preserving settings.

Use sharp scaling and avoid aggressive compression. Screen text is the first thing viewers notice when encode quality drops.

4. Keep Audio Honest

• preserve original speech clarity,
• do not overcompress,
• mute or simplify useless sped-up noise,
• use music sparingly, if at all.

5. Verify Every Output

File checks:

• Output file exists and is a valid MP4 container
• Duration matches effective target within +/-5%
• Resolution matches selected profile

Visual spot checks:

• Text is sharp and readable at sampled frames
• Crop transitions are smooth enough to follow
• Callout overlays appear and disappear cleanly
• Blur masks fully cover sensitive data
• No black frames or timing glitches
• Subtitles do not sit on top of critical UI

Audio spot checks:

• Narration/voiceover is clear and consistent volume
• Music, if used, is not competing with speech
• No obvious audio glitches at speed boundaries
• No clipping or distortion

Record important findings in:

• render_report.verification_notes
• render_report.warnings
• render_report.metadata.variant_notes

Common Pitfalls

• Rendering 9:16 versions that are technically exported but practically unreadable.
• Encoding screen text with generic low-bitrate social defaults.
• Letting decorative backgrounds or padding reduce usable UI area too far.