Merged Screen & Edit · Agent Playbook

Unified Screen + Edit Playbook

Non-conflicting merge of all files in edits and video skills (Apex Qwen master, AI-Agent Production Guide, Effects & edits, Effects×opt hybrid, Virality hybrid, screening SOP, follow-up ops, opus/python/models extras). Four core production sections + v2 upgrade packs (SEO, full effects kits, AGENTS.md viral pipeline, per-app prompts/mistakes, failure modes/self-check). Copy-paste templates throughout.

1 · Screen 9:16 2 · Screen 16:9 + Feed 3 · General enhance 4 · Platform-specific

DOMAIN STATUS — edit vs editor (read this)

https://edit.addict.best and https://editor.addict.best are two Caddy vhosts on the same Contabo box (149.102.150.185). They are NOT different products — they were temporarily different inventories (edit had full MD + 4 HTML engines; editor had only 2 HTMLs). After the unify deploy they serve the same full package. Prefer either URL; content is mirrored.

  • No functional bug in SSL/Caddy for either (both use tls admin@ielts.fast).
  • Earlier difference was inventory depth, not a broken app.
  • Canonical deep engine for agents: this page + /Qwen-expert-Ai-editor.md.

Conflict resolution (canonical law — always apply)

  • Brand numbers: AI-Agent Video Production Guide §1 table wins over any older generic grade or “18–22% hook for all apps”.
  • Zoom ceiling is per-app: Dose/Dentist 1.08–1.15× · Female 1.08–1.18× · Coach 1.10–1.22×. Never exceed that app’s max (including hook).
  • Retention before polish: hook → dead-air kill → kinetic captions → loop → audio → export → then fancy effects.
  • Faceless absolute: no eyes, nose, mouth, eye-circles, face-implying shapes in generated visuals.
  • Readability beats style: any grade/effect that hurts dose/UI text is removed.
  • Hard cuts ~80–90% of edits; heavy dissolves/light-leaks/glitch off UI footage.
  • Render invariants: image inputs -framerate 30 · mux apad+-shortest · audio -ar 48000 · HDR→SDR before grade.
  • QA three-state: PASS / FAIL / INCONCLUSIVE. INCONCLUSIVE ≠ PASS. Never claim done without gate.
  • Process order: capture → archive raw → grade → motion → safe-zone place → captions → interrupts → audio → export → QA.
  • Soft research numbers (exact % completion targets from models dump) are directional only — optimize your own retention curve.
1

Screen videos — 9:16 Shorts / Reels / TikTok / Shorts

Merged from: screening SOP · AI-Agent PART 1 · Effects hybrid Part 2 · Virality ROI · follow-up chrome crop · opus 2K notes

Copy-ready FFmpeg recipes (merge from both engines)

Use these exact filter chains inside agent templates

  • HDR → SDR: ffmpeg -i in.mp4 -vf "zscale=t=linear:npl=100,format=gbrpf32le,zscale=p=bt709:t=bt709:m=bt709,format=yuv420p" -c:v libx264 -crf 18 -c:a copy out_sdr.mp4
  • Clean high-key grade: -vf "eq=contrast=1.05:brightness=0.03:saturation=0.93,colorbalance=rs=0.02:gs=0.01:bs=-0.02"
  • Chrome/dock crop (example): ffmpeg -i raw.mp4 -vf "crop=in_w:in_h-120:0:60" -c:v libx264 -crf 18 clean.mp4 (tune crop to real chrome height)
  • Ken Burns still→clip: ffmpeg -loop 1 -framerate 30 -i img.png -vf "scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,zoompan=z='min(zoom+0.0008,1.12)':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=90:s=1080x1920:fps=30" -t 3 -c:v libx264 -pix_fmt yuv420p clip.mp4
  • 9:16 blurred fill: ffmpeg -loop 1 -framerate 30 -i img.png -vf "scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,boxblur=20:5,scale=1080:1920[bg];[0:v]scale=1080:1920:force_original_aspect_ratio=decrease[fg];[bg][fg]overlay=(W-w)/2:(H-h)/2" -t 3 -c:v libx264 out.mp4
  • Mux VO no drift: ffmpeg -i v.mp4 -i a.mp3 -filter_complex "[1:a]apad[a]" -map 0:v -map "[a]" -c:v copy -c:a aac -ar 48000 -shortest out.mp4
  • Loudnorm: -af "loudnorm=I=-14:LRA=11:TP=-1"
  • Screen encode (follow-up): ffmpeg -i in.mov -c:v libx265 -crf 19 -preset medium -pix_fmt yuv420p -tag:v hvc1 -x265-params no-sao=1:no-strong-intra-smoothing=1 -c:a aac -b:a 192k out.mp4

1.1 Purpose & platforms

Vertical short-form is for scroll-stop + completion + rewatch, not depth. Use for cold-open hooks, single-feature demos, myth-busting, “you’re doing this wrong,” quick tips. Platforms: TikTok, Instagram Reels, YouTube Shorts, Facebook Reels, Stories. Length target: 15–45s (also ship ultra-tight 12–22s + standard 25–40s variants when possible).

1.2 Capture (screen recording) — non-negotiable

  • Resolution: native app screen at highest available; minimum delivery-ready headroom (prefer ~1.3× target, e.g. 1284×2778+ for 1080×1920 delivery, or 2K 1440×2560 for archive/opus batches).
  • Clean capture only: no filters, overlays, grade, or effects while recording.
  • Chrome & dock removal (Mac): hide browser chrome (tabs/URL/profile) and Mac dock — crop/zoom so only clean app UI is in frame (from follow-up notes).
  • HDR: if device records HDR, tone-map to SDR first before any pipeline step.
  • Edge margin: no critical UI within 10% of any frame edge; note per-screen zoom target (the number/result, not the full screen).
  • Archive raw forever — never overwrite the master recording.
  • Screen encode tips (follow-up): CRF 18–21 (often CRF 19 for 9:16 45–55s); prefer yuv420p; for HEVC use hvc1 tag; no-sao=1 helps screen content sharpness.

Capture checklist

  • Raw archived separately
  • No browser chrome / dock in frame
  • SDR confirmed
  • Zoom targets noted per screen

1.3 Locked process order (after capture)

  1. Grade — locked preset from brand table (or Clean High-Key default for generic apps). Do not re-derive per video.
  2. Motion — Ken Burns / punch-in only within app zoom ceiling; ease in/out; target the result element.
  3. Safe zone — place captions/graphics inside safe bounds from the start (not “check later”).
  4. Captions — burn-in, kinetic, 2–4 word groups; hook treatment first 1–2.5s.
  5. Pattern interrupts & numbers — visual change every app cadence; count-up anim on results.
  6. Audio — VO primary; music ducked 8–12 dB; SFX ≥15 dB under dialogue; −14 LUFS / −1 dBTP (or −11 to −12 LUFS if prioritizing TikTok/Reels loudness).
  7. Loop — end frame + spoken fragment can restart into open.
  8. Export — 1080×1920, H.264 High, 30 fps (60 only if fast scroll), 15–20 Mbps typical for UI, MP4, no watermark.
  9. QA — mute test, real phone, grade match, zoom ceiling, faceless, legible numbers.

1.4 Safe zone (9:16 1080×1920)

  • Outer bound for all text/logos/graphics: x: 60–930, y: 250–1450
  • Caption centroid specifically: ~20–55% of frame height (y ≈ 384–1056)
  • Avoid top ~15% and bottom ~20–22% (platform UI overlays)
  • Confirm on a real phone — desktop preview lies

1.5 Retention engineering (merged ROI — short-form)

Execute in this priority order (polish never jumps the queue):

  1. Multi-channel hook 0–3s: strongest visual + bold kinetic text (0–0.3s) + audio impact. Never logo/greeting/slow fade open. Prefer negative/mistake framing.
  2. Dead air out + pattern interrupt every ~1.8–3.2s (use per-app table when Promedic).
  3. Kinetic captions ≥95% speech coverage, high contrast, safe zone.
  4. Seamless / near-seamless loop.
  5. Audio engineering (compression, ducking, micro-SFX).
  6. Correct export + variants.
  7. Secondary polish only (grain/vignette) if still readable.

Default look for app screens

Clean High-Key (or app brand grade) · minimal grain · almost no light leaks · Ken Burns not static holds · hard cuts default · kinetic captions carry clarity.

1.6 Per-app short-form ceilings (Promedic family)

AppZoom maxHook windowInterruptAccent
Dose Calculator1.08–1.15×1.0–1.8s2.0–3.0sSoft clinical blue
Female ProMedic1.08–1.18×1.5–2.2s2.5–3.5sRose-gold / blush
Coach ProMedic1.10–1.22×1.0–1.6s1.8–2.8sOrange or electric blue
Dentist Pro1.08–1.15×1.5–2.5s2.5–3.5sTeal/cyan (≠ Dose blue)

1.7 Hook rules (platform-aware)

  • TikTok often needs attention inside ~1.0–1.3s; Reels ~1.5–2.1s — treat as directional pressure, not magic numbers.
  • Cold-open on result/outcome screen, not splash logo.
  • Hook text: 5–9 words max, readable muted; bold distinct treatment vs body captions.
  • Negative framing usually beats positive on hook rate for feature demos.

1.8 AI-agent template — 9:16 screen → short

Copy the block below into an agent session. Replace {APP_NAME} and brand variables (or leave defaults for generic apps).

Agent template · Section 1 9:16 screen recording → Shorts / Reels / TikTok
# AGENT BRIEF — SCREEN TO 9:16 SHORT-FORM
You are a precise CLI video agent for app screen content → TikTok / Reels / YouTube Shorts.

## IDENTITY
- Faceless absolute: NO eyes, nose, mouth, eye-circles, face features in any generated visual.
- Readability beats style. UI text, doses, numbers must stay legible.
- Hard cuts = ~80–90% of transitions.
- Process order is LAW: grade → motion → safe-zone place → captions → interrupts → audio → export → QA.
- Never overwrite the raw recording. Archive first.

## INPUTS
- Raw screen recording path: {RAW_PATH}
- App: {APP_NAME}   # Dose Calculator | Female ProMedic | Coach ProMedic | Dentist Pro | Generic
- Voiceover / script path (optional): {VO_PATH}
- Music bed (optional): {MUSIC_PATH}
- Output dir: {OUT_DIR}

## BRAND VARIABLES (fill from table; defaults = Clean High-Key clinical)
White balance: {WB}           # Dose~5900K cool | Female~5200K warm rose | Coach~5700K | Dentist~6100K cool
Exposure: {EXPOSURE}          # typically +0.2 to +0.3 EV
Black lift: {BLACKS}          # RGB 5–12 depending on app
Highlight cap: {WHITES}       # 245–250
Saturation: {SATURATION}      # Dose/Dentist desat; Coach slight +sat
Grain: {GRAIN}                # 0 default; never on numeric close-ups
Vignette: {VIGNETTE}          # none or very light; mask off UI corners
Accent: {ACCENT}
Zoom range: {ZOOM_MIN}–{ZOOM_MAX}   # NEVER exceed max (hook included)
Hook window: {HOOK_MIN}–{HOOK_MAX}s
Interrupt every: {INTERRUPT_MIN}–{INTERRUPT_MAX}s

## PHASE 1 — PREP (if not already clean)
1. Confirm raw is archived.
2. If HDR → tone-map to SDR.
3. If browser chrome / dock visible → crop/zoom to clean app UI only (keep resolution; no soft upscale).
4. Probe: duration, fps, resolution. Prefer constant 30 fps output.

## PHASE 2 — PROCESS (in order)
1) GRADE (locked — do not invent)
   Apply {WB}, {EXPOSURE}, {BLACKS}, {WHITES}, {SATURATION}, {GRAIN}, {VIGNETTE}.

2) MOTION
   - Ken Burns / punch-in only within {ZOOM_MIN}–{ZOOM_MAX}.
   - Zoom TARGET = the number/result on that screen, never full frame.
   - Ease in/out only (no linear zoom). Completes over full on-screen duration of that shot.
   - Default stills→motion if input is image sequence: mild Ken Burns per still.

3) SAFE ZONE (1080x1920)
   - Outer: x 60–930, y 250–1450 for all text/logos/graphics.
   - Caption centroid ~20–55% height.
   - Place captions inside bounds during generation (not “fix later”).

4) CAPTIONS
   - Burn-in, synced to VO/speech.
   - Groups of 2–4 words (not single-word spam unless emphasis).
   - Min hold 0.4–0.5s per chunk even if speech is faster.
   - HOOK ({HOOK_MIN}–{HOOK_MAX}s): bolder treatment, single punchy line or number reveal; must read with SOUND OFF.
   - Highlight numbers, feature names, benefits in {ACCENT}.
   - Coverage ≥ 95% of spoken words when speech exists.

5) PATTERN INTERRUPTS & NUMBERS
   - New screen / zoom punch / caption change / motion graphic every {INTERRUPT_MIN}–{INTERRUPT_MAX}s.
   - Result numbers: count-up 0→final in 0.5–0.8s + soft pop SFX (never static pop-in).
   - Highlight circles / soft glow: max 1–2 per screen, in {ACCENT}.
   - Soft whoosh only on screen transitions.

6) AUDIO
   - Voiceover primary, compressed, dominant.
   - Music ducked 8–12 dB under VO during narration.
   - SFX ≥15 dB below dialogue.
   - Normalize: -14 LUFS integrated / -1 dBTP true peak
     (optional -11 to -12 LUFS if TikTok/Reels feed loudness priority).
   - Final audio sample rate 48000. When muxing: apad + -shortest (no A/V drift).

7) LOOP
   - End on frame + spoken fragment that can restart into the opening for rewatches.

8) EXPORT
   - 1080x1920, 9:16, H.264 High Profile, 30fps (60 only if fast scroll/swipe),
     15–20 Mbps preferred for dense UI (or 8–12 Mbps min), MP4, no watermark.
   - Prefer at least two variants: ultra-tight 12–22s and standard 25–40s when material allows.
   - On image inputs to FFmpeg always use -framerate 30 (VFR trap).

## PHASE 3 — QA (all must PASS; INCONCLUSIVE = not done)
[ ] Multi-channel hook in first 3s (visual motion + text + audio)
[ ] Muted playback: hook + captions fully understandable
[ ] Real-phone safe zone: nothing under platform UI
[ ] Grade matches locked preset (no drift)
[ ] Zoom never exceeds {ZOOM_MAX} including hook
[ ] No illegible / distorted numbers or UI text
[ ] Faceless rule respected in all generated assets
[ ] No watermark; correct 1080x1920
[ ] A/V drift < 0.5s if measurable
[ ] At least one publishable file written to {OUT_DIR}

## SEO + DISCOVERY (on-video + publish package)
- Spoken keywords: say the feature + problem + app name naturally in first 8s and once near end.
- On-screen text: burn keyword-rich phrases (drug names, feature, benefit) — platforms index speech + captions.
- Hashtags: 3–5 highly relevant ONLY (not 8–12 spam). Example set for clinical: #dose #clinicaltools #medicalapp (adapt to niche).
- Title formula: [Mistake/Outcome] + [Specific result] + [Audience]
  e.g. "Most clinicians miss this interaction — live dose fix"
- Description (Shorts/Reels caption): line 1 = value claim; line 2 = save CTA; line 3 = 3–5 tags.
- First frame / thumbnail intent: biggest number or bold hook text readable at stamp size; no chrome/dock.
- Soft CTA for saves: "Save this clinical reference" (Dose) / "Save this workout" (Coach) — never generic "follow for more" only.
- Soft research % are directional — optimize YOUR retention graph, do not hardcode magic completion %.

## HARD FAILURES (fix and re-render)
- Starts with logo/greeting/slow fade
- Dead air longer than interrupt budget
- Captions outside safe zone
- Grain/light-leak/glitch on clinical numeric screens
- Inventing medical numbers in AI visuals (overlay real numbers as graphics only)

## OUTPUT REPORT
Return: file paths, durations, variants, checklist PASS/FAIL per item, what changed.

## TOOLS
Prefer FFmpeg/ffprobe local. Optional Whisper for captions. Optional OpenCV for stills analysis.
Never claim done without QA PASS.
2

Screen videos — 16:9 long-form + Feed (4:5 primary · 1:1 alt)

Merged from: AI-Agent PART 2A/2B · Effects hybrid Part 3 · platform notes · title-safe / grid-crop rules

2.1 Two different jobs (do not mix constraints)

16:9 Long-form

YouTube, LinkedIn native, Facebook video, site embeds. Goal: watch time, trust, education, SEO. Length often 3–12+ min. Deeper holds, chapters, steady subtitles after hook.

Feed 4:5 / 1:1

Instagram/Facebook/LinkedIn feed scroll. Length 15–60s. Closer to short-form energy than YouTube. Main risk = grid thumbnail crop, not Reels button overlays.

2026 feed note

4:5 (1080×1350) is primary Instagram-optimized feed export. 1:1 (1080×1080) is the cross-platform alt (LinkedIn/Facebook/uniform grids). Export both from one project when possible. Same brand grade as 9:16 — never drift looks between formats.

2.2 Capture for multi-format

  • Same clean, high-res, non-destructive capture as 9:16. Archive raw once.
  • Best practice: record once with headroom, then re-frame per format (do not blind-center-crop from 9:16 into 16:9/4:5 if it pushes UI off).
  • Chrome/dock still removed. HDR→SDR still first.
  • Zoom headroom matters less for long-form (holds longer, punches rarer) but still useful.

2.3 Long-form 16:9 — process differences from short

ElementShort 9:16Long 16:9
Hook window1.0–2.5s5–12s still strong, can breathe
Visual change~1.8–3.5s~6–14s per app tier (or on new info)
Ken BurnsMost screensSparing — key reveals only
CaptionsKinetic most of runtimeKinetic in hook only; then steady full-clause subtitles
StructureHook–body–loopProblem → Solution → Proof → How → CTA + chapters
SFX densityHigherSparser, restrained
Export1080×19201920×1080, 15–25 Mbps if dense UI
Loudness−14 or −11/−12 TT−14 LUFS / −1 dBTP (YouTube normalize target)

2.4 16:9 safe zones

  • Canvas 1920×1080.
  • Title-safe: keep essential text/graphics roughly within x:120–1800, y:70–1010 (~6% margin) for embeds/TV apps.
  • End screens (YouTube): final 5–20s keep essentials in central ~90%; avoid bottom-right ~60×40px duration counter region late.
  • No TikTok-style side buttons on frame — but still respect embed crops.

2.5 Feed 4:5 & 1:1 — process

  • Grade: identical to short-form brand preset.
  • Motion: same zoom ceiling as short; hold slightly longer than Reels.
  • Safe zone (grid protection):
    • 4:5 1080×1350: keep key subject/text in central 1080×1080 band (approx y:135–1215 full width).
    • 1:1 1080×1080: keep essentials in central ~90%.
    • Nothing essential in outer ~10% any edge.
  • Captions: kinetic hook same short window; then steady density similar to short (feed is mute-first too).
  • Export: primary 1080×1350 12–18 Mbps; alt 1080×1080 same codec.

2.6 Long-form visual-change cadence (per app)

AppLong-form visual changeNotes
Dose6–12sLinkedIn/FB often outperform pure entertainment
Female6–12sIG feed + Reels combo; carousels help
Coach6–10sFront-load energy 30–45s then teach
Dentist8–14sMost restrained; skip punches on LinkedIn OK

Workflow that prevents brand drift

Build the 9:16 cut first (highest retention pressure forces structure), then expand to long-form/feed by lengthening holds, thinning interrupts, adding explanatory VO — from the same project so grade never drifts.

2.7 AI-agent template — 16:9 + feed from screen

Agent template · Section 2 16:9 long-form + 4:5 / 1:1 feed from screen masters
# AGENT BRIEF — SCREEN TO 16:9 LONG-FORM + FEED (4:5 / 1:1)
You produce multi-format exports from clean app screen footage.

## IDENTITY & LAWS
- Faceless absolute. Readability beats style.
- Same brand grade as any 9:16 version of this app — ZERO look drift between formats.
- Hard cuts default. Process order: grade → motion → safe zones → captions → structure → audio → export → QA.
- Prefer: build/expand from an existing approved short cut when available; do not invent a second grade.

## INPUTS
- Raw or graded master: {MASTER_PATH}
- Optional approved 9:16 cut to expand from: {SHORT_PATH}
- App: {APP_NAME}
- Formats requested: {FORMATS}   # e.g. 16:9, 4:5, 1:1
- Brand vars (same as short): {WB} {EXPOSURE} {BLACKS} {WHITES} {SAT} {GRAIN} {VIGNETTE} {ACCENT}
- Zoom ceiling: {ZOOM_MIN}–{ZOOM_MAX}
- Long-form visual-change cadence: {LONG_INTERRUPT_MIN}–{LONG_INTERRUPT_MAX}s
- Output dir: {OUT_DIR}

## A) LONG-FORM 16:9 (YouTube / LinkedIn / Facebook / embeds)
Canvas: 1920x1080

STRUCTURE (required):
Problem → Solution → Proof → How it works → CTA
Add chapter markers at each structural beat.

PROCESS:
1. GRADE — identical locked preset for {APP_NAME}.
2. MOTION — hold screens long enough to read. Ken Burns only on key reveals, still within {ZOOM_MIN}–{ZOOM_MAX}. Zoom punches rare.
3. SAFE ZONE
   - Title-safe: essentials inside ~ x:120–1800, y:70–1010
   - End-screen zone last 5–20s: central ~90%; avoid BR duration counter area
4. CAPTIONS
   - Kinetic 2–4 word ONLY in opening hook window (~2× short hook as starting point)
   - After hook: steady full-clause subtitles (constant kinetic fatigues multi-minute viewers)
   - {ACCENT} on numbers/key terms, used more sparingly than short-form
5. PATTERN INTERRUPTS — every {LONG_INTERRUPT_MIN}–{LONG_INTERRUPT_MAX}s OR whenever new info appears (not rigid timer only)
6. AUDIO — -14 LUFS / -1 dBTP; longer restrained music; fewer micro-SFX; educational VO tone
7. EXPORT — 1920x1080 H.264 High, 30fps, 15–25 Mbps if dense UI, MP4, no watermark
   Audio -ar 48000; mux apad + -shortest if needed

QA 16:9:
[ ] Title-safe respected
[ ] Chapters present
[ ] End-screen zone OK if cards used
[ ] Grade matches short version of same app
[ ] Muted check on hook segment (FB mute-heavy)
[ ] Faceless OK
[ ] Numbers legible

## B) FEED 4:5 PRIMARY + 1:1 ALT
Length target: 15–60s (feed scroll ≈ short energy)

PROCESS:
1. GRADE — same locked preset
2. MOTION — same zoom ceiling; holds slightly longer than Reels
3. REFRAME — do not blind-crop from 9:16; re-center key UI
4. SAFE ZONE (grid thumbnail protection — critical)
   - 4:5 1080x1350: key text/subject inside central 1080x1080 (approx y:135–1215)
   - 1:1 1080x1080: essentials central ~90%
   - Nothing essential in outer ~10% edges
5. CAPTIONS — kinetic hook in short-form window; then steady captions (mute-first feeds)
6. INTERRUPTS — short-form cadence held a beat longer
7. AUDIO — -14 LUFS / -1 dBTP
8. EXPORT
   - Primary: 1080x1350 (4:5), H.264, 30fps, 12–18 Mbps
   - Alt: 1080x1080 (1:1), same codec settings

QA FEED:
[ ] Preview in-feed AND profile grid crop
[ ] Outer 10% empty of essentials
[ ] Grade matches other formats
[ ] Faceless OK

## PLATFORM BIAS (apply after core)
- Dose / Dentist: prefer LinkedIn/Facebook restraint; optional skip zoom punches on LinkedIn
- Female: IG feed + Reels + carousel pairing
- Coach: YT short + long workout breakdowns; front-load energy 30–45s then teach
- All: never re-grade per platform — only pacing/crop/caption density change

## SEO + DISCOVERY (long-form / feed)
- YouTube title: primary keyword front-loaded; under ~60–70 chars when possible.
- Chapters: add markers at Problem / Solution / Proof / How / CTA.
- Description: first 150 chars = search intent summary; include 2–4 keyword variants; no keyword stuffing.
- Spoken SEO: say searchable phrases aloud (feature names) at least twice.
- Tags/hashtags: few relevant; LinkedIn uses keywords in first comment + native text more than tags.
- Thumbnail / first frame: high-contrast UI result + 3–5 word claim; protect grid crop on 4:5/1:1.
- End screen zone: keep last 5–20s free of essential text outside central 90%.

## HARD RULES
- Do not use 9:16 platform UI safe-zone numbers on 16:9.
- Do not use kinetic captions for entire long-form runtime.
- Do not invent medical numbers in AI frames — real values as graphic overlays only.
- Three-state QA: INCONCLUSIVE blocks done.

## OUTPUT
Write all requested formats to {OUT_DIR}. Report paths, durations, QA matrix per format.
3

Edit videos — general enhancing edits

Merged from: Effects craft · Apex hard rules · Virality mechanical steps · CLI toolkit · Python limits · QA gates

3.1 What “general enhance” means here

Universal improvements that apply to almost any short/mid video (screen or mixed stills), without platform-specific framing. This is the polish + retention spine. Effects are seasoning; story, pacing, captions, and clarity are the meal.

3.2 Priority order for any enhance job

  1. Hook reconstruction (0–3s multi-channel)
  2. Remove dead air / filler; inject pattern interrupts
  3. Kinetic or high-contrast captions in safe zone
  4. Audio (VO level, duck music, micro-SFX)
  5. Loop / ending payoff
  6. Technical export correctness
  7. Color grade / light effects (only if readability holds)
  8. Fancy transitions (last; hard cut remains default)

3.3 Color grades — when to use / avoid

GradeUseAvoid
Clean high-keyApp UI, SaaS, tech, tutorialsGritty / heavy emotion pieces
Teal & orangeEnergy, product reveal, travelTrust/testimonial talking heads
Bleach / moody tealTrue crime, hard truthsAspirational, food, clinical UI
Warm nostalgicMemory, storytimeFast info + sharp on-screen text
Vibrant popFood, fashion, dance, energy listiclesSerious/vulnerable topics
B&W accentSingle emotional peak / flashbackWhole video wallpaper

3.4 Transitions (general)

  • Hard cut — ~90% of cuts; invisible when timed to beat/motion.
  • J-cut / L-cut — narration continuity.
  • Zoom transition — listicle chapter breaks.
  • Whip / match cut — high energy creative only.
  • Light leak / glitch / long dissolve — rare accents; skip on UI demos.

3.5 Effects seasoning table

EffectReach forSkip when
Film grainNostalgic / cinematicClean tech UI (reads low quality)
Light leaksMemory / lifestyle accentsClinical / serious / every clip
Motion blurFast action/danceReadable UI/charts
VignetteCenter focus dramaWide UI / diagrams
Zoom punchHook / keyword / CTAContinuous walkthrough every second
Chromatic aberrationGlitch/horror aestheticCorporate / product trust

3.6 Cut rhythm by content type

  • Hook 0–3s: cut every 1–2s OK.
  • Motivational: 3–5s early → 7–10s mid → tight at CTA.
  • Listicle/edu: new visual every fact; caption locked to speech.
  • Story: cut on information, not a timer.
  • Tutorial: longer holds; don’t thrash the demo.
  • Comedy: cut on punchline immediately.

3.7 Motion primitives (still → video)

  • Ken Burns zoom-in / zoom-out / pan L→R / R→L
  • Zoom punch (~0.5s) at emphasis timestamps
  • 9:16 sharp-core + blurred-fill when source is not vertical
  • Always -framerate 30 on image inputs (VFR trap)

3.8 Audio enhance (universal)

  • VO compressed, peaks roughly −6 to −3 dB before loudnorm
  • Music ducked 8–12 dB under speech
  • Whoosh on cuts/zooms; soft pop on text appears; all SFX under VO
  • Loudnorm targets: social often I=−14, LRA=11, TP=−1 (EBU-style)
  • Final -ar 48000; apad + -shortest when muxing

3.9 Apex / verification invariants (never skip)

Six deadly sins (fail closed)

  • VFR trap → force constant framerate on image ingest
  • A/V drift → apad + shortest; drift < 0.5s
  • Context decay → checkpoint plan/state on disk for multi-step jobs
  • False positive “done” → 5-tier / final_gate style physical checks
  • Blind acceptance → inspect frames at ~25/50/75% when reviewing video
  • Face leak on faceless series → fail even if pixels “look fine”

3.10 Ready kits (pick one, don’t stack all)

ContentGradeTransitionsEffectsRhythm
App / techClean high-keyHard cut, rare zoomMinimalHold for readability
ListicleClean high-keyZoom between pointsArrows/circlesNew visual per fact
MotivationalWarm-neutralHard + 1 light-leak maxSoft grain/vignette3–5→7–10→tight CTA
StorytimeWarm nostalgicJ-cuts, whip for jumpsLight grainStory beats
True crimeBleach / moodyHard + 1 glitch at revealHeavy grain OKSlow then snap

Agent vs pure Python

Use a script for batch silence-cut / forced 9:16 / basic captions. Use an agent for hook language, claim framing, and taste. Do not expect pure FFmpeg code to invent good hooks.

3.11 AI-agent template — general enhance

Agent template · Section 3 Universal enhancing edit (any input video or image folder)
# AGENT BRIEF — GENERAL VIDEO ENHANCEMENT
You enhance videos (or image folders) for retention and clarity without platform-specific branding unless provided.

## IDENTITY
- Retention first, polish last.
- Faceless if {FORCE_FACELESS}=true (default true for this brand family).
- Readability beats style. Hard cuts ~80–90%.
- Effects are seasoning — name the tone in one word; if you need three effects to “cover” tone, simplify.
- Render laws: -framerate 30 on image inputs; apad + -shortest when muxing; -ar 48000; never claim done without QA PASS.

## INPUTS
- Input: {INPUT_PATH}   # video file OR folder of images
- Content type kit: {KIT}  # app-tech | listicle | motivational | story | true-crime | comedy | tutorial
- Pacing preset: {PACE}    # hyper | balanced | story
- Force faceless: {FORCE_FACELESS}
- Target aspect if known: {ASPECT}  # 9:16 | 16:9 | 4:5 | 1:1 | keep
- Output dir: {OUT_DIR}

## PACING PRESETS
- hyper: silence cutoff ~0.40s; interrupt every 2.0–2.6s
- balanced: silence ~0.55s; interrupt 2.8–3.8s
- story: silence ~0.75s; interrupt 4.0–5.5s (or on story beats)

## EXECUTION ORDER (do not reorder)

### 0) Ingest & analyze
- If images: build base video with mild Ken Burns (2.5–4s/image) + hard cuts or short xfade.
- Transcribe with word timestamps if speech exists.
- Detect silence / stillness / retention risks (long static, slow open, missing captions).
- Probe media → write media.json summary.

### 1) Hook (0–3s) — HIGHEST ROI
- Cold-open on strongest visual/outcome. Never logo/greeting/slow fade.
- Multi-channel: motion + bold kinetic text (5–9 words, start ≤0.3s) + audio impact at t=0.
- Prefer negative/mistake framing when content allows.
- Optional punch-in 10–22% but respect any provided zoom ceiling {ZOOM_MAX}.

### 2) Dead air + pattern interrupts
- Cut silences per {PACE}.
- Insert visual change (punch-in/out, new shot, caption pop, B-roll) on cadence.
- Speed ramp optional: 1.5–2× setup, normal/slow on payoff.

### 3) Captions
- Kinetic word or 2–4 word groups; high contrast.
- Highlight keywords; scale pop only on emphasis.
- Safe zone if vertical: centroid ~20–55% height; avoid top 15% / bottom 22%.
- Coverage ≥95% of speech.

### 4) Audio
- VO compress; music duck 8–12 dB; SFX under VO.
- Loudnorm ~ -14 LUFS / -1 dBTP unless platform override provided.
- Micro-SFX: whoosh on cuts/zooms; soft pop on text.

### 5) Loop / ending
- Payoff before loop point. Match end visual/fragment to start when possible.
- Soft CTA that does not kill rewatch.

### 6) Grade + effects (KIT)
Apply ONE kit only:
- app-tech: clean high-key; minimal effects; no grain on UI numbers
- listicle: clean high-key; zoom transitions between points; arrows/circles
- motivational: warm-neutral; subtle grain/vignette; one accent transition max
- story: warm nostalgic; J-cuts; light grain
- true-crime: bleach/moody; heavy grain OK; one glitch at reveal
- comedy: vibrant timing > grade; cut on punchline; SFX > filters
- tutorial: clean; minimal cuts; long holds

FORBIDDEN on app UI: stacked grain+leak+blur+CA; glitch; unreadable grades.

### 7) Export
- Respect {ASPECT} if set; else keep source aspect but strip watermarks.
- H.264 MP4, 30fps default, audio 48kHz.
- Produce ≥1 main file; if short-form material, also ultra-tight + standard variants when possible.

### 8) QA GATE (PASS required)
[ ] Hook multi-channel in first 3s
[ ] No dead air above preset
[ ] Captions safe + ≥95% if speech
[ ] Mute test communicates core message
[ ] Grade matches kit; UI still legible
[ ] No face leak if faceless forced
[ ] File exists, non-empty, has video stream, duration > 0
[ ] Optional: extract frames 25/50/75% and visually confirm not black/corrupt
[ ] A/V sync OK

If any critical FAIL → fix → re-render (max 3 attempts) → re-QA.
INCONCLUSIVE checks must be resolved or treated as FAIL.


## SCRIPT DENSITY (from Effects craft)
- Aim ~1 clear idea per ~15s of script (avoid cramming multiple claims in one breath).
- Force a visual change (cut/pan/crop/caption/new image) every 7–10s independent of script for feed content; for tutorials hold longer.

## VIRAL FAILURE MODES (hard-code)
- No greeting/logo/slow-fade open
- No text in top 15% or bottom 20–25% on 9:16
- No missing/static full-line-only captions when speech exists
- No dead air above pace preset
- No SFX louder than VO
- No wrong aspect / letterbox / watermark
- Produce ≥2 length variants when material allows
- Attempt loop when short-form

## SEO LITE (enhance pass)
- Ensure keyword phrases appear in captions + speech
- 3–5 relevant hashtags in publish package notes
- Save-reason CTA preferred over vanity follow CTA

## OUTPUT REPORT
- Paths of outputs
- Kit + pace used
- List of changes (hook, cuts, captions, audio, grade)
- QA matrix PASS/FAIL
- Anything you could not verify

## TOOLS
FFmpeg/ffprobe required. Whisper/pysubs2 optional. Prefer local free tools. No paid SaaS required.
4

Edit videos — specific edits for formats & platforms

Merged from: platform overrides · Promedic packs · virality platform notes · models dump (directional) · export specs

4.1 Principle

Core edit (Section 3) stays the same. Platforms change hook pressure, length variants, safe zones, loudness, caption density, and CTA style — not your brand grade. Never ship a watermarked cross-post when a native cut is possible.

4.2 Export matrix (canonical)

Format / surfaceCanvasFPSCodec notesLoudness
TikTok / Reels / Shorts1080×192030 (60 high motion)H.264, 8–20 Mbps, no watermark−14 or −11/−12 if feed fight
IG/FB Feed 4:51080×135030H.264 12–18 Mbps−14 / −1 TP
Feed / LinkedIn 1:11080×108030H.264−14 / −1 TP
YouTube long1920×108030H.264 15–25 Mbps UI−14 / −1 TP
Stories1080×192030Same as short; shorter hooks−14-ish

4.3 Platform-specific edit deltas

TikTok

  • Hardest first-second pressure; cold open mandatory.
  • Pattern interrupts aggressive; loop highly rewarded.
  • Captions non-negotiable; mute-first culture.
  • Test original audio vs trending bed — content quality > trend cargo-cult.
  • Optional hotter loudness (−11/−12 LUFS) when competing in feed.

Instagram Reels

  • Hook window slightly more breathing room than TT but still <~2s intent.
  • Safe zone same vertical overlay logic.
  • Saves/shares matter; design useful or emotionally intense payoffs.
  • Pair feed 4:5 + Reels from same project for topic clusters.

YouTube Shorts

  • Vertical same as others; discovery differs — clear spoken + on-screen keywords help.
  • Still mute-capable: captions on.
  • Can extend slightly longer when absolute watch time stays high.

YouTube long-form

  • Chapters, title-safe, educational VO, kinetic only in open.
  • Do not push TikTok loudness; stay −14 LUFS class.
  • End screens: protect final frame real estate.

LinkedIn

  • Trust > hype. Restrained motion. Skip glitch/energy spam.
  • Clinical apps (Dose/Dentist): often best surface for authority demos.
  • Captions still required (feed mute).
  • 1:1 or 16:9 both fine; prefer professional tone over jump-cut mania.

Facebook feed / Reels

  • Mute-first heavy → captions + strong first frame.
  • 4:5/1:1 for feed; 9:16 for Reels surface.

4.4 Promedic app × platform (specific edits)

AppBest surfacesSpecific edit notes
Dose Calculator LinkedIn, FB, Shorts educational Cool grade, tight zoom max 1.15×, never energetic meme grade; numbers count-up; zero hallucinated doses
Female ProMedic IG Reels + feed Warm rose grade; open on relatable claim then number; soft grain ≤4% OK off numbers
Coach ProMedic Shorts + YT long workouts Widest zoom 1.22×; fastest interrupts; energy front-load; still readable form cues
Dentist Pro LinkedIn / FB / careful Reels Most sterile desat; teal≠Dose blue; short-form still serious; avoid over-punch

4.5 Safe-zone quick map by format

  • 9:16 social: x60–930, y250–1450 outer; caption mid-upper.
  • 16:9: title-safe ~6% margins; end-screen central 90% late.
  • 4:5: protect central square for grid.
  • 1:1: central 90% for grid/cross-post.

4.6 CTA & ending by platform

  • Shorts/Reels/TT: soft CTA + loop continuity; save-reason specific (“Save this clinical reference”) beats “follow for more”.
  • YouTube long: explicit CTA + end screen; chapters for search.
  • LinkedIn: professional takeaway; invite comment with expertise question, not engagement bait spam.

Do not hard-code fragile research %

Models dump may quote exact completion % or multipliers. Use them as direction. Optimize your real retention graph. Virality hybrid already softens these claims.

4.7 AI-agent template — platform-specific edit

Agent template · Section 4 Take a master cut → platform-native variants
# AGENT BRIEF — PLATFORM / FORMAT SPECIFIC EDITS
You start from an approved master (or raw) and produce native variants per platform.
Do NOT re-invent brand grade. Only change pacing, crop, captions density, loudness, CTA, and export specs.

## INPUTS
- Master path: {MASTER_PATH}
- App (optional): {APP_NAME}
- Brand grade already applied? {GRADE_DONE}  # true|false
- Brand vars if grade needed: {WB} {EXPOSURE} {BLACKS} {WHITES} {SAT} {GRAIN} {VIGNETTE} {ACCENT}
- Zoom ceiling: {ZOOM_MIN}–{ZOOM_MAX}
- Platforms requested (multi): {PLATFORMS}
  # options: tiktok | reels | yt_shorts | yt_long | ig_feed_45 | feed_11 | linkedin | fb_feed | stories
- Output dir: {OUT_DIR}

## GLOBAL LAWS
- Faceless absolute if brand series.
- Readability beats style.
- Same grade across all variants.
- Hard cuts default.
- Three-state QA; INCONCLUSIVE blocks done.
- No watermarks. No logo cold-open on short surfaces.

## PER-PLATFORM RECIPES

### tiktok
- Canvas 1080x1920
- Hook pressure maximum; multi-channel by 1.0–1.3s intent
- Interrupts aggressive (use app short cadence if provided)
- Captions kinetic full runtime; mute-first
- Loop engineered
- Loudness: -14 default OR -11 to -12 if {LOUD_FEED}=true
- Length variants: 12–22s + 25–40s when possible
- CTA: soft + save-reason; keep rewatch path

### reels  (Instagram Reels)
- Canvas 1080x1920
- Hook <~2s intent; same safe zone as vertical social
- Captions on; saves/shares oriented payoff
- Grade identical to TikTok variant (only timing/crop tweaks if needed)
- Pair note: if ig_feed_45 also requested, share grade/project

### yt_shorts
- Canvas 1080x1920
- Captions on; keyword-rich speech + on-screen terms
- May allow slightly longer if retention holds
- Loudness -14 class
- No watermark

### yt_long
- Canvas 1920x1080
- Structure: Problem→Solution→Proof→How→CTA + chapters
- Kinetic captions ONLY in opening; then steady subtitles
- Holds longer; interrupts {LONG_INTERRUPT_MIN}–{LONG_INTERRUPT_MAX}s or on new info
- Title-safe margins; protect end-screen zone last 5–20s
- Loudness -14 LUFS / -1 dBTP (do not TikTok-hot this)
- Bitrate 15–25 Mbps if dense UI

### ig_feed_45
- Canvas 1080x1350
- 15–60s; kinetic hook then steady captions
- CRITICAL: key content in central 1080x1080 band for grid crop
- QA must include grid-thumbnail mental check

### feed_11
- Canvas 1080x1080
- Cross-platform feed; central ~90% essentials
- Same grade; slightly longer holds than Reels

### linkedin
- Prefer 16:9 or 1:1
- Restrained motion; skip glitch/meme energy
- For Dose/Dentist: optional zero zoom-punches
- Professional CTA; captions on (mute feeds)
- Trust > virality tricks; no engagement-bait spam

### fb_feed
- 4:5 or 1:1; mute-first captions; strong first frame
- Grade same; hook clear without sound

### stories
- 1080x1920; shorter; safe zone strict; quick hook; brand stickers optional later (not in render unless asked)

## APP OVERRIDES (if {APP_NAME} set)
- Dose: cool clinical; max zoom 1.15×; no fake medical numbers
- Female: warm rose; claim-then-number hooks; IG-first
- Coach: widest zoom up to 1.22×; fastest short interrupts; front-load long energy
- Dentist: sterile; teal accent ≠ Dose blue; serious tone even on short

## PIPELINE PER VARIANT
1. Load master
2. Apply grade only if GRADE_DONE=false
3. Reframe/crop for canvas (smart re-center UI)
4. Adjust pacing/interrupts to platform recipe
5. Rebuild captions density for platform
6. Audio loudnorm per recipe
7. Export per matrix
8. QA per platform checklist
9. Write {OUT_DIR}/{platform}_*.mp4

## QA PER VARIANT
[ ] Correct canvas
[ ] Grade matches siblings
[ ] Safe zone correct for THAT format (not wrong format’s numbers)
[ ] Captions readable muted
[ ] Hook appropriate to platform pressure
[ ] No watermark
[ ] Faceless OK
[ ] Numbers legible
[ ] File valid (stream, duration, resolution)


## PLATFORM SEO NOTES
- tiktok / reels / yt_shorts: keyword-rich speech + captions; 3–5 tags; save CTA; native no watermark
- yt_long: keyword title + chapters + description first 150 chars; spoken feature names; -14 LUFS
- linkedin: professional first-line text; keywords in post body; restrained edit; 1:1 or 16:9
- ig_feed_45 / feed_11: first frame = mini-thumbnail; central crop safe; caption keywords above fold
- Hashtags: fewer, relevant — evidence leans 3–5 not 8–12 spam

## SAVE / SHARE DESIGN
- Shares/saves > likes for distribution
- Design payoff worth saving (checklist, dose result, workout plan, myth correction)
- App-specific save language from brand register

## OUTPUT REPORT
Table: platform | path | duration | canvas | loudness target | QA PASS/FAIL | notes

If a platform cannot be produced from master without destroying UI, say so (INCONCLUSIVE) and propose re-record crop — do not force a broken crop.
B

Brand variable table (Promedic — inject into any template)

Canonical numbers — win all conflicts with older generic docs
Variable Dose Calculator Female ProMedic Coach ProMedic Dentist Pro
White balanceCool ~5900KWarm ~5200K + roseNeutral-warm ~5700KCool ~6100K clinical
Exposure+0.2 EV+0.2 EV+0.3 EV+0.2 EV
Black lift8–1010–125–88–10
Highlight cap245248250245
Saturation−8%−3%+2 to +5%−8 to −10%
Grain0 (≤2% off numbers)≤4% soft warm≤2%0%
VignetteVery light if flatVery light softNoneVery light if flat
Motion blurNoneNoneSubtle on transitionsNone
AccentSoft clinical blueRose-gold / blushOrange / electric blueTeal/cyan
Zoom ceiling1.08–1.15×1.08–1.18×1.10–1.22×1.08–1.15×
Hook (short)1.0–1.8s1.5–2.2s1.0–1.6s1.5–2.5s
Interrupt (short)2.0–3.0s2.5–3.5s1.8–2.8s2.5–3.5s
Visual change (long)6–12s6–12s6–10s8–14s
M

Master mega-template (all four jobs in one agent run)

Use when one agent must screen + multi-format export + enhance + platform variants
Master agent template Full pipeline orchestrator brief
# MASTER AGENT — SCREEN + ENHANCE + MULTI-FORMAT + PLATFORM VARIANTS
You execute a full production run for app screen content.

## LAWS (non-negotiable)
1. Faceless absolute. Readability beats style.
2. Brand table numbers win all grade/zoom conflicts.
3. Order: archive raw → SDR → grade → motion → safe zones → captions → interrupts → audio → export → QA.
4. Retention ROI before polish.
5. Hard cuts ~80–90%. Image inputs -framerate 30. Mux apad+-shortest. Audio -ar 48000.
6. QA three-state: only PASS means done. Max 3 re-render attempts.

## INPUTS
- Raw screen: {RAW_PATH}
- App: {APP_NAME}
- Brand vars: fill from brand table
- Jobs: {JOBS}  # subset of: short_916, long_169, feed_45, feed_11, enhance_only, platform_pack
- Platforms if platform_pack: {PLATFORMS}
- OUT: {OUT_DIR}

## STAGE MAP
A. CAPTURE HYGIENE — chrome/dock crop if needed; HDR→SDR; archive raw
B. SHORT 9:16 — Section 1 template fully → short_master.mp4
C. ENHANCE — Section 3 ROI + Script Density + failure modes on short_master
D. VIRAL PASS — Section 7 AGENTS.md steps 0–7 (hook→loop→variants) if short-form
E. LONG 16:9 — expand from short (Section 2A) → long_master.mp4
F. FEED — 4:5 + optional 1:1 (Section 2B)
G. PLATFORM PACK — Section 4 recipes from masters
H. SEO PACKAGE — Section 5: titles, captions, 3–5 hashtags, save CTA, first-frame check per variant
I. APP GUARDRAILS — Section 8 common mistakes for {APP_NAME}
J. FINAL GATE — Section 9 self-check + all QA PASS

## DELIVERABLES
{OUT_DIR}/
  raw_archive/
  short_916/
  long_169/
  feed_45/
  feed_11/
  platform/
  reports/qa_report.md

## REPORT
Write qa_report.md with matrix of every file × checks.
If anything INCONCLUSIVE, do not mark project complete.

Start now. Prefer local FFmpeg. Do not skip QA.
5

SEO + viral distribution package (upgrade)

Fills the SEO gap: on-video keywords, titles, hashtags, thumbnails, saves/shares — merged from virality hybrid + production guide

5.1 What “SEO” means for short/long video (2026)

Platforms index spoken words + on-screen text + title/caption metadata. Hashtags are secondary. Retention still decides distribution — SEO only helps discovery after the video is watchable.

LayerActionWhere it lives
On-video SEOKeyword phrases in speech + kinetic captionsBurn-in + VO script
Title / first lineMistake or outcome + specific result + audienceUpload title / caption line 1
Hashtags3–5 highly relevant (not 8–12 spam)Caption end / YT tags sparse
First frameReadable claim or big number at stamp sizet=0 frame / thumbnail
Saves / sharesSpecific save-reason CTA > “follow for more”End line + spoken CTA
Long-form SEOChapters + description first 150 chars + spoken keywordsYouTube package

5.2 Title / caption formulas (copy patterns)

  • Mistake frame: “Stop calculating [X] wrong — [app] does it live”
  • Curiosity + proof: “This one screen fixes [pain] in 10 seconds”
  • List/value: “3 checks before you prescribe [drug class]”
  • Coach: “Stop doing [exercise] wrong — form fix on screen”
  • LinkedIn: “Clinical workflow: [feature] without spreadsheet chaos”

5.3 Hashtag policy (anti-spam)

  • Prefer 3–5 relevant tags + strong keywords in speech/captions (virality hybrid consensus).
  • Mix: 1–2 niche + 1–2 mid + optional 1 broad (never all mega-tags).
  • Never paste identical 30-tag blocks across every post.

5.4 Shares & saves (distribution multipliers)

  • Algorithms weight shares and saves far above vanity likes.
  • Design a saveable artifact: dose result, checklist, workout block, myth correction.
  • CTA language by app: “Save this clinical reference” · “Save this workout” · “Save this checklist”.

5.5 Soft numbers (do not hard-code as law)

Directional only

1.3s TT / 2.1s Reels hook pressure, “60% past 3s”, exact completion % — treat as directional. Optimize your retention curve continuously (virality hybrid caveat).

5.6 AI-agent template — SEO + publish package

Agent template · Section 5 SEO + viral distribution package for finished video(s)
# AGENT BRIEF — SEO + VIRAL DISTRIBUTION PACKAGE
You do NOT re-edit pixels unless a first-frame/thumbnail crop is broken.
You produce a publish package for each finished video file.

## INPUTS
- Video path(s): {VIDEO_PATHS}
- App / brand: {APP_NAME}
- Platforms: {PLATFORMS}
- Core claim (1 sentence): {CORE_CLAIM}
- Primary keywords (3–6): {KEYWORDS}
- Output: {OUT_DIR}/publish_package.md

## RULES
1. Retention already done upstream — do not trade clarity for keyword stuffing.
2. Hashtags: exactly 3–5 relevant tags. No spam walls.
3. Keywords must appear in: spoken suggestion + on-screen caption lines + title.
4. Save CTA must be specific (not only "follow").
5. Soft research % are directional — do not invent "guaranteed viral" claims.

## PER VIDEO DELIVERABLE
For each platform in {PLATFORMS} write:

### A) Title / first line (≤70 chars ideal)
- Formula: [Mistake or Outcome] + [Specific result] + [Audience]
- Include 1 primary keyword naturally

### B) Caption / description
- Line 1: value claim (search intent)
- Line 2: proof or how-to hook
- Line 3: save CTA in brand register
- Line 4: 3–5 hashtags

### C) Spoken keyword checklist
- List phrases the VO/captions already contain
- Flag missing keywords that should appear in captions without clutter

### D) First-frame / thumbnail check
- [ ] Claim or number readable at small size
- [ ] No chrome/dock/watermark
- [ ] For 4:5/1:1: subject in grid-safe center
- [ ] For YT long: suggest 3–5 word thumbnail text

### E) YouTube-only (if yt_long)
- Chapter list (Problem / Solution / Proof / How / CTA)
- Description first 150 chars = search summary
- End-screen note (central 90% free)

### F) Hashtag set (3–5)
Return tags + one-line why each is relevant

## OUTPUT
Write publish_package.md. If first-frame fails crop/readability → mark FAIL and request re-export of frame 0 only.
Three-state: PASS only if all platform packages complete and first-frame checks pass.
6

Pro effects kits + transitions + Script Density (upgrade)

Absorbs Effects and edits.md craft that templates previously under-weighted

6.1 Script Density (retention secret)

  • ~1 idea per ~15 seconds of script — multi-claim breaths muddle memory.
  • Visual reset every 7–10s for feed short-form (cut/pan/crop/caption/new image) independent of speech.
  • Do not use 7–10s clock on long tutorials/interviews — cut on information; hold demos.

6.2 Ready-to-use kits (pick one stack)

ContentColor gradeTransitionsEffectsCut rhythm
App / tech / SaaSClean high-keyHard cut (~90%), rare zoomMinimal — no grain on numbersHold to read UI
Listicle / eduClean high-keyZoom between pointsArrows, circles, count-upsNew visual every fact
MotivationalWarm-neutralHard + max 1 light-leak accentSoft grain / vignette3–5s → 7–10s → tight CTA
StorytimeWarm nostalgicJ-cuts; whip for scene jumpsLight grainOn story beats
True crime / hard truthBleach / moody tealHard + 1 glitch at revealHeavier grain OKSlow then snap
Comedy / memeVibrant; timing > gradeHard on punchlineMinimal; SFX firstFastest
Clinical PromedicBrand §1 tableHard cuts only defaultNo leaks/glitch on dataPer-app interrupt table

6.3 Transition catalog (when / avoid)

  • Hard cut — default ~80–90%. Invisible when timed.
  • J-cut / L-cut — narration continuity.
  • Zoom transition — listicle chapters.
  • Whip pan / match cut — high-energy creative only; skip clinical UI.
  • Speed ramp — sports/dance/reveal; not dense UI text.
  • Light leak / glitch / long dissolve — rare accents; avoid app demos.

6.4 Fake BTS caution

Trust boundary

Showing real process as value is fine. Using “fake BTS” only to dodge AI labels is a trust risk and fragile. Do not instruct agents to evade disclosure systems.

6.5 Agent decision matrix (image → video)

InputDefault motionGradeCaptions
App screenshotsKen Burns 1.08–1.15× (or brand max)Clean high-key / brandKinetic + accent numbers
List of stills + VOPer-image KB + hard cutsOne LUT entire cutBurn to VO
Silent slideshowAlt zoom-in / panClean or nostalgicOptional big titles only
Single hero imageSlow zoom-in full durationMatch tone kitHook line only
7

Virality Ranked ROI + full AGENTS.md (upgrade)

From Video optimization-virality-hybrid.md — agent-executable viral law

7.1 Ranked ROI order (never invert)

  1. Multi-channel hook 0–3s
  2. Dead-air kill + pattern interrupts ~1.8–3.2s (or app table)
  3. Kinetic captions safe-zone ≥95% speech
  4. Seamless / near-seamless loop
  5. Audio engineering (duck, SFX under VO)
  6. Technical export + length variants
  7. Secondary polish (grain/fancy transitions) last

Likes/followers are low priority. Shares, saves, rewatches, retention curve shape win.

7.2 Key failure modes (hard-code)

  • Greeting / logo / slow fade open
  • Text in top 15% or bottom 20–25% on vertical
  • Missing or static full-line-only captions when speech exists
  • Dead air remaining; SFX louder than VO; wrong AR / letterbox / watermark
  • Only one length version; no loop attempt on short-form

7.3 AI-agent template — full viral AGENTS pipeline

Agent template · Section 7 Copy-paste System Prompt + AGENTS.md viral short-form pipeline
# SYSTEM PROMPT – Short-Form Viral Video Optimization Agent

You are a precise, deterministic video optimization agent for TikTok / Reels / YouTube Shorts.

Inputs: (1) existing video OR (2) folder of images.
Follow AGENTS.md exactly. Prefer rules over free artistic invention.
Use FFmpeg / Whisper / OpenCV as available. Output multiple length variants.
Run full QA before finishing. Report what changed.

ZOOM NOTE: Prefer brand zoom ceiling when {APP_NAME} is set (AI-Agent Guide §1).
If no brand: punch-in up to ~1.15× (≈15%) is allowed; do not invent medical numbers.

---

# AGENTS.md – Viral Short-Form Optimization Pipeline

## Global Settings
- Target: 1080x1920 (9:16), 30 fps default
- Pacing presets:
  - hyper (default): silence cutoff 0.40s; interrupt every 2.0–2.6s
  - balanced: silence 0.55s; interrupt 2.8–3.8s
  - story: silence 0.75s; interrupt 4.0–5.5s (or on story beats)
- Always generate ≥2 variants: ultra-tight 12–22s + standard 25–40s when material allows
- Caption safe zone: centroid 20–55% height (avoid top 15% / bottom 22%)
- Faceless if brand series: NO eyes/nose/mouth/eye-circles

## Pipeline (execute in order)

### Step 0 – Ingest
- Images → base video with Ken Burns (2.5–4s/image) + hard cuts
- Whisper word timestamps → words.json
- Silence → silence.json; stillness → stillness.json; probe → media.json

### Step 1 – Hook (0–3s) — HIGHEST ROI
- Strongest visual/outcome at t=0 — never logo/greeting/slow fade
- Punch-in in first 0.5s within allowed zoom ceiling
- Kinetic text 5–9 words starting ≤0.3s; high contrast; safe zone
- Audio impact at frame 0
- Prefer negative/mistake framing when content allows

### Step 2 – Jump cuts + pattern interrupts
- Remove silence/stillness per {PACE}
- Visual change on cadence (punch, new shot, caption pop)
- Prefer interrupts on spoken emphasis words

### Step 3 – Kinetic captions
- Word-level or 2–4 word groups; bold white + accent on keywords
- Scale pop 110–120% only on emphasis
- Coverage ≥95% of speech

### Step 4 – Audio
- VO compress peaks roughly -6 to -3 dB pre-loudnorm
- Music duck ~10 dB under speech
- Whoosh on cuts/zooms; soft pop on text; SFX under VO
- loudnorm ~ -14 LUFS / -1 dBTP (or -11/-12 if TikTok loud-feed priority)
- Final -ar 48000; mux apad + -shortest

### Step 5 – Seamless loop
- Match end visual + last spoken fragment to open
- Hard cut if continuity high; else short bridge

### Step 6 – Export
- 1080x1920 H.264, 30fps, AAC 160–192k, no watermark
- variant_short.mp4 + variant_standard.mp4 (+ loop variant if possible)

### Step 7 – QA (PASS required)
[ ] Multi-channel hook in first 3s
[ ] No dead air above preset
[ ] Captions safe + ≥95% if speech
[ ] Correct 9:16 1080x1920
[ ] ≥2 length variants when possible
[ ] Mute test communicates core message
[ ] Faceless OK if required
[ ] No watermark / letterbox

If critical FAIL → fix → re-render (max 3) → re-QA.
INCONCLUSIVE is not PASS.

## SEO LITE (after QA PASS)
- Draft title (mistake/outcome formula)
- 3–5 relevant hashtags
- Save-reason CTA line
- Confirm keyword appears in speech or captions

## REPORT
Paths, pace, changes list, QA matrix, publish package draft.
8

Per-app agent prompts + common mistakes (upgrade)

From Effects hybrid FILE 1–4 — ready prompts agents can paste with brand guardrails

Universal for all four apps

Faceless absolute. Readability of medical/UI data outranks style. Same caption font family/weight mechanic across the brand family; only grade/accent/zoom/pace differ.

8.1 Dose Calculator (clinical)

  • Feel: cool clean high-key · accent soft clinical blue · zoom max 1.15× · hook 1.0–1.8s · interrupt 2.0–3.0s
  • Hooks: “Most clinicians miss this interaction” · “Stop using the old method”
  • Save CTA: “Save this clinical reference”
  • Platforms: LinkedIn/FB often strong; Shorts OK if serious

Ready prompts

P1 Short calc: Record Dose Calculator for [case]. 9:16 1080×1920, cool Clean High-Key, Ken Burns max 1.15×, kinetic captions soft blue on numbers/drug names, highlight circle on final dose, faceless absolute, whoosh on screen change + pop on result. Hook: “Most clinicians miss this interaction”.

P2 Long case: Educational walkthrough, same grade, longer holds, YouTube chapters, professional tone, faceless.

P3 Myth short: Negative open 1.5s, wrong method → correct calc in app, clinical system, faceless.

Mistakes: grade that shifts data colors · fast cuts that hide dose · grain/leaks on numbers · faces · playful energy on clinical content

8.2 Female ProMedic

  • Feel: soft warm + rose/peach · accent rose-gold · zoom to 1.18× · hook 1.5–2.2s · interrupt 2.5–3.5s
  • Hooks: life-stage truth · “what most apps get wrong about [topic]” — claim then number
  • Platforms: Instagram strongest; pair Reels + 4:5 + carousel

Ready prompts

P1 Reel: Female ProMedic on [topic]. Soft warm-neutral + rose, elegant Ken Burns, rose-gold caption accents, faceless, 9:16. Hook: “What most apps get wrong about [topic]”.

P2 Life-stage: Calm supportive short; full Female system; zero faces.

Mistakes: childish pink · cold sterile · harsh aggressive cutting · any faces

8.3 Coach ProMedic

  • Feel: higher contrast + warmth · orange/electric blue · zoom to 1.22× · hook 1.0–1.6s · interrupt 1.8–2.8s
  • Hooks: “Stop doing this exercise wrong” · form corrections
  • Save CTA: “Save this workout”
  • Platforms: TT/Reels + YT short/long workouts; front-load long energy 30–45s

Ready prompts

P1 Form fix: Coach screen [exercise]. Clean high-contrast warm energy, dynamic KB + zoom punches, bold captions orange/blue, faceless, 9:16. Hook: “Stop doing this exercise wrong”.

P2 Plan/timer: High-energy plan demo; timers readable; faceless.

Mistakes: too dark/cinematic · slow low energy · faces · unreadable timers

8.4 Dentist Pro

  • Feel: sterile cool · teal/cyan ≠ Dose blue · zoom max 1.15× · hook 1.5–2.5s · interrupt 2.5–3.5s (long 8–14s)
  • Tone: serious even in short-form; LinkedIn/FB often best

Ready prompts

P1 Feature: Dentist Pro [feature]. Cool Clean High-Key, slow precise KB, soft teal highlights on clinical data, kinetic captions, faceless, 9:16.

P2 Case walkthrough: Slow holds on charts/plans; professional; faceless.

Mistakes: playful/meme energy · heavy cinema · unreadable charts · faces · Coach-level motion language

8.5 Mini agent template — pick app pack

Agent template · Section 8 Apply one app pack + common mistakes as hard constraints
# AGENT BRIEF — PROMEDIC APP PACK GUARDRAILS
App: {APP_NAME}  # Dose | Female | Coach | Dentist
Task: {TASK}     # short | long | myth | form-fix | feature

## LOAD
1. Brand variable table for {APP_NAME} (zoom/hook/interrupt/grade) — wins all conflicts.
2. Section 8 pack for {APP_NAME}: hooks, save CTA, platforms, ready prompt closest to {TASK}.
3. Common mistakes list = HARD FAILS if violated.

## EXECUTE
- Use matching ready prompt as seed; fill [brackets].
- Faceless absolute. Readability beats style.
- Short-form: Section 1 + Section 7 ROI order.
- Long-form: Section 2A; chapters if YouTube.
- SEO package: Section 5 after pixel QA PASS.

## STOP CONDITIONS
If any Common Mistake for this app appears in plan or render → FAIL → fix → re-QA.
Never mix Coach energy into Dose/Dentist.
Never use childish pink for Female or teal identical to Dose blue for Dentist.

## OUTPUT
Render path(s) + which pack prompt used + mistakes checklist all clear + publish package.
9

Failure modes + self-check gate (upgrade)

From virality failure modes + Effects self-check + Apex three-state QA

9.1 Binary self-check (run after every render)

  • File exists, size > trivial, has video stream, duration > 0
  • Resolution matches target (1080×1920 / 1920×1080 / 1080×1350 / 1080×1080)
  • FPS ≈ 30 (or 60 if intentional high-motion)
  • Mute test: core message understandable
  • Safe zone / grid crop OK for format
  • Zoom ≤ brand max including hook
  • No watermark; no chrome/dock
  • Faceless if required; numbers legible
  • A/V drift < 0.5s if measurable; audio 48 kHz when muxed

Three-state law

PASS / FAIL / INCONCLUSIVE. INCONCLUSIVE ≠ PASS. Agent cannot say done until final checks are PASS. Max 3 re-render attempts with evidence.

9.2 AI-agent template — final gate

Agent template · Section 9 Final gate / self-check before claiming done
# AGENT BRIEF — FINAL GATE / SELF-CHECK
Inputs: {OUTPUT_PATHS}  expected format(s): {FORMATS}  app: {APP_NAME or none}

For EACH output file, produce CheckResult rows (never crash):

| check_id | result | detail | evidence |
|----------|--------|--------|----------|
| exists_nonzero | PASS/FAIL/INCONCLUSIVE | ... | path, bytes |
| has_video_stream | ... | ffprobe | ... |
| resolution_match | ... | WxH | ... |
| fps_ok | ... | ... | ... |
| duration_gt_0 | ... | ... | ... |
| mute_message_ok | ... | captions/hook | frame or note |
| safe_zone_ok | ... | format rules | ... |
| zoom_ceiling_ok | ... | brand max | ... |
| no_watermark | ... | ... | ... |
| faceless_ok | ... | if required | ... |
| numbers_legible | ... | UI/dose | ... |
| av_sync_ok | ... | if A+V | ... |
| variants_count | ... | short-form ≥2 if required | ... |
| seo_package_present | ... | title+3–5 tags+save CTA | ... |

## RULES
- Any FAIL → fix root cause → re-render → re-run this gate (max 3 loops)
- Any INCONCLUSIVE on critical checks → do not claim done
- all_pass true only if every critical row is PASS

## OUTPUT
final_gate.json + human summary. If all_pass: list publish-ready paths. Else: blocked reasons.