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.
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· muxapad+-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.
Screen videos — 9:16 Shorts / Reels / TikTok / Shorts
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
hvc1tag;no-sao=1helps 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)
- Grade — locked preset from brand table (or Clean High-Key default for generic apps). Do not re-derive per video.
- Motion — Ken Burns / punch-in only within app zoom ceiling; ease in/out; target the result element.
- Safe zone — place captions/graphics inside safe bounds from the start (not “check later”).
- Captions — burn-in, kinetic, 2–4 word groups; hook treatment first 1–2.5s.
- Pattern interrupts & numbers — visual change every app cadence; count-up anim on results.
- 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).
- Loop — end frame + spoken fragment can restart into open.
- Export — 1080×1920, H.264 High, 30 fps (60 only if fast scroll), 15–20 Mbps typical for UI, MP4, no watermark.
- 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):
- 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.
- Dead air out + pattern interrupt every ~1.8–3.2s (use per-app table when Promedic).
- Kinetic captions ≥95% speech coverage, high contrast, safe zone.
- Seamless / near-seamless loop.
- Audio engineering (compression, ducking, micro-SFX).
- Correct export + variants.
- 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)
| App | Zoom max | Hook window | Interrupt | Accent |
|---|---|---|---|---|
| Dose Calculator | 1.08–1.15× | 1.0–1.8s | 2.0–3.0s | Soft clinical blue |
| Female ProMedic | 1.08–1.18× | 1.5–2.2s | 2.5–3.5s | Rose-gold / blush |
| Coach ProMedic | 1.10–1.22× | 1.0–1.6s | 1.8–2.8s | Orange or electric blue |
| Dentist Pro | 1.08–1.15× | 1.5–2.5s | 2.5–3.5s | Teal/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 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.
Screen videos — 16:9 long-form + Feed (4:5 primary · 1:1 alt)
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
| Element | Short 9:16 | Long 16:9 |
|---|---|---|
| Hook window | 1.0–2.5s | 5–12s still strong, can breathe |
| Visual change | ~1.8–3.5s | ~6–14s per app tier (or on new info) |
| Ken Burns | Most screens | Sparing — key reveals only |
| Captions | Kinetic most of runtime | Kinetic in hook only; then steady full-clause subtitles |
| Structure | Hook–body–loop | Problem → Solution → Proof → How → CTA + chapters |
| SFX density | Higher | Sparser, restrained |
| Export | 1080×1920 | 1920×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)
| App | Long-form visual change | Notes |
|---|---|---|
| Dose | 6–12s | LinkedIn/FB often outperform pure entertainment |
| Female | 6–12s | IG feed + Reels combo; carousels help |
| Coach | 6–10s | Front-load energy 30–45s then teach |
| Dentist | 8–14s | Most 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 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.
Edit videos — general enhancing edits
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
- Hook reconstruction (0–3s multi-channel)
- Remove dead air / filler; inject pattern interrupts
- Kinetic or high-contrast captions in safe zone
- Audio (VO level, duck music, micro-SFX)
- Loop / ending payoff
- Technical export correctness
- Color grade / light effects (only if readability holds)
- Fancy transitions (last; hard cut remains default)
3.3 Color grades — when to use / avoid
| Grade | Use | Avoid |
|---|---|---|
| Clean high-key | App UI, SaaS, tech, tutorials | Gritty / heavy emotion pieces |
| Teal & orange | Energy, product reveal, travel | Trust/testimonial talking heads |
| Bleach / moody teal | True crime, hard truths | Aspirational, food, clinical UI |
| Warm nostalgic | Memory, storytime | Fast info + sharp on-screen text |
| Vibrant pop | Food, fashion, dance, energy listicles | Serious/vulnerable topics |
| B&W accent | Single emotional peak / flashback | Whole 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
| Effect | Reach for | Skip when |
|---|---|---|
| Film grain | Nostalgic / cinematic | Clean tech UI (reads low quality) |
| Light leaks | Memory / lifestyle accents | Clinical / serious / every clip |
| Motion blur | Fast action/dance | Readable UI/charts |
| Vignette | Center focus drama | Wide UI / diagrams |
| Zoom punch | Hook / keyword / CTA | Continuous walkthrough every second |
| Chromatic aberration | Glitch/horror aesthetic | Corporate / 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 30on 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+-shortestwhen 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)
| Content | Grade | Transitions | Effects | Rhythm |
|---|---|---|---|---|
| App / tech | Clean high-key | Hard cut, rare zoom | Minimal | Hold for readability |
| Listicle | Clean high-key | Zoom between points | Arrows/circles | New visual per fact |
| Motivational | Warm-neutral | Hard + 1 light-leak max | Soft grain/vignette | 3–5→7–10→tight CTA |
| Storytime | Warm nostalgic | J-cuts, whip for jumps | Light grain | Story beats |
| True crime | Bleach / moody | Hard + 1 glitch at reveal | Heavy grain OK | Slow 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 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.
Edit videos — specific edits for formats & platforms
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 / surface | Canvas | FPS | Codec notes | Loudness |
|---|---|---|---|---|
| TikTok / Reels / Shorts | 1080×1920 | 30 (60 high motion) | H.264, 8–20 Mbps, no watermark | −14 or −11/−12 if feed fight |
| IG/FB Feed 4:5 | 1080×1350 | 30 | H.264 12–18 Mbps | −14 / −1 TP |
| Feed / LinkedIn 1:1 | 1080×1080 | 30 | H.264 | −14 / −1 TP |
| YouTube long | 1920×1080 | 30 | H.264 15–25 Mbps UI | −14 / −1 TP |
| Stories | 1080×1920 | 30 | Same 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.
- 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)
| App | Best surfaces | Specific 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 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.
Brand variable table (Promedic — inject into any template)
| Variable | Dose Calculator | Female ProMedic | Coach ProMedic | Dentist Pro |
|---|---|---|---|---|
| White balance | Cool ~5900K | Warm ~5200K + rose | Neutral-warm ~5700K | Cool ~6100K clinical |
| Exposure | +0.2 EV | +0.2 EV | +0.3 EV | +0.2 EV |
| Black lift | 8–10 | 10–12 | 5–8 | 8–10 |
| Highlight cap | 245 | 248 | 250 | 245 |
| Saturation | −8% | −3% | +2 to +5% | −8 to −10% |
| Grain | 0 (≤2% off numbers) | ≤4% soft warm | ≤2% | 0% |
| Vignette | Very light if flat | Very light soft | None | Very light if flat |
| Motion blur | None | None | Subtle on transitions | None |
| Accent | Soft clinical blue | Rose-gold / blush | Orange / electric blue | Teal/cyan |
| Zoom ceiling | 1.08–1.15× | 1.08–1.18× | 1.10–1.22× | 1.08–1.15× |
| Hook (short) | 1.0–1.8s | 1.5–2.2s | 1.0–1.6s | 1.5–2.5s |
| Interrupt (short) | 2.0–3.0s | 2.5–3.5s | 1.8–2.8s | 2.5–3.5s |
| Visual change (long) | 6–12s | 6–12s | 6–10s | 8–14s |
Master mega-template (all four jobs in one agent run)
# 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.
SEO + viral distribution package (upgrade)
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.
| Layer | Action | Where it lives |
|---|---|---|
| On-video SEO | Keyword phrases in speech + kinetic captions | Burn-in + VO script |
| Title / first line | Mistake or outcome + specific result + audience | Upload title / caption line 1 |
| Hashtags | 3–5 highly relevant (not 8–12 spam) | Caption end / YT tags sparse |
| First frame | Readable claim or big number at stamp size | t=0 frame / thumbnail |
| Saves / shares | Specific save-reason CTA > “follow for more” | End line + spoken CTA |
| Long-form SEO | Chapters + description first 150 chars + spoken keywords | YouTube 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 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.
Pro effects kits + transitions + Script Density (upgrade)
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)
| Content | Color grade | Transitions | Effects | Cut rhythm |
|---|---|---|---|---|
| App / tech / SaaS | Clean high-key | Hard cut (~90%), rare zoom | Minimal — no grain on numbers | Hold to read UI |
| Listicle / edu | Clean high-key | Zoom between points | Arrows, circles, count-ups | New visual every fact |
| Motivational | Warm-neutral | Hard + max 1 light-leak accent | Soft grain / vignette | 3–5s → 7–10s → tight CTA |
| Storytime | Warm nostalgic | J-cuts; whip for scene jumps | Light grain | On story beats |
| True crime / hard truth | Bleach / moody teal | Hard + 1 glitch at reveal | Heavier grain OK | Slow then snap |
| Comedy / meme | Vibrant; timing > grade | Hard on punchline | Minimal; SFX first | Fastest |
| Clinical Promedic | Brand §1 table | Hard cuts only default | No leaks/glitch on data | Per-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)
| Input | Default motion | Grade | Captions |
|---|---|---|---|
| App screenshots | Ken Burns 1.08–1.15× (or brand max) | Clean high-key / brand | Kinetic + accent numbers |
| List of stills + VO | Per-image KB + hard cuts | One LUT entire cut | Burn to VO |
| Silent slideshow | Alt zoom-in / pan | Clean or nostalgic | Optional big titles only |
| Single hero image | Slow zoom-in full duration | Match tone kit | Hook line only |
Virality Ranked ROI + full AGENTS.md (upgrade)
7.1 Ranked ROI order (never invert)
- Multi-channel hook 0–3s
- Dead-air kill + pattern interrupts ~1.8–3.2s (or app table)
- Kinetic captions safe-zone ≥95% speech
- Seamless / near-seamless loop
- Audio engineering (duck, SFX under VO)
- Technical export + length variants
- 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
# 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.
Per-app agent prompts + common mistakes (upgrade)
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 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.
Failure modes + self-check gate (upgrade)
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 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.