# Editor Pro-Tips & Commands

> Companion for **editor.addict.best** — the single HTML app.
> Commands, pro-tips, and combination recipes that make the 6 unified templates work.
> **All tools are free and local.** No paid APIs, no SaaS subscriptions. Your AI agent API is the only external dependency.

---

## How the 6 Templates Connect

```
Raw screen recording or image folder
        │
        ▼
   ┌─── U1 or U2 ───┐       Pick ONE entry point:
   │  Screen → 9:16  │       • U1 = short-form (TikTok/Reels/Shorts)
   │  Screen → 16:9  │       • U2 = long-form (YouTube) + feed (4:5, 1:1)
   └────────┬────────┘
            ▼
        U3 (Enhance)          Always run after U1/U2 — retention polish
            │
            ▼
   U4 (Platform + SEO)        Multi-platform export + publish package
            │
            ▼
   U5 (Viral + Final Gate)    Short-form viral pipeline + QA gate
            │
            ▼
   U6 (Master + App Pack)     OR skip U1–U5 and use U6 as full orchestrator
```

### Combination Rules

| Workflow | Templates to chain | When |
|:---|:---|:---|
| Quick short-form | U1 → U3 → U5 | One app, one platform, fast turnaround |
| Quick long-form | U2 → U3 → U4 | YouTube + feed variants |
| Full multi-platform | U1 → U3 → U4 → U5 | Short-form master → all platform exports |
| One-shot everything | U6 alone | Full production run, all formats, all QA |
| SEO-only pass | U4 (SEO section only) | Video already rendered, need publish package |
| QA-only gate | U5 (gate section only) | Check existing renders before shipping |

### Pro-tip: Template Variables

Every template uses `{VARIABLES}`. Fill them before running:

```bash
# ponytail: These are the variables every template needs.
# Copy this block, fill values, paste at top of your agent prompt.

RAW_PATH="/path/to/raw_screen.mp4"
APP_NAME="Dose Calculator"        # Dose Calculator | Female ProMedic | Coach ProMedic | Dentist Pro | Generic
OUT_DIR="/path/to/output"
FORCE_FACELESS=true

# Brand vars (auto-fill from editor.addict.best #brand table)
WB="5900"           # Kelvin
EXPOSURE="+0.2"     # EV
BLACKS="8"          # RGB lift
WHITES="245"        # Highlight cap
SATURATION="-8"     # percent
GRAIN="0"           # percent
VIGNETTE="light"    # none | light
ACCENT="blue"       # Dose=blue | Female=rose | Coach=orange | Dentist=teal
ZOOM_MIN="1.00"
ZOOM_MAX="1.15"     # Per-app ceiling — NEVER exceed
HOOK_MIN="1.0"
HOOK_MAX="1.8"
INTERRUPT_MIN="2.0"
INTERRUPT_MAX="3.0"
```

---

## FFmpeg Command Recipes

### 1. Probe any file first (always start here)

```bash
ffprobe -v quiet -print_format json -show_format -show_streams input.mp4
```

Pro-tip: Pipe to `jq` for quick checks:

```bash
# Duration only
ffprobe -v quiet -show_entries format=duration -of csv=p=0 input.mp4

# Resolution
ffprobe -v quiet -show_entries stream=width,height -of csv=p=0 -select_streams v:0 input.mp4

# FPS
ffprobe -v quiet -show_entries stream=r_frame_rate -of csv=p=0 -select_streams v:0 input.mp4
```

### 2. Archive raw (always before any edit)

```bash
mkdir -p "$OUT_DIR/raw_archive"
cp "$RAW_PATH" "$OUT_DIR/raw_archive/"
```

### 3. HDR → SDR (run if ffprobe shows bt2020/hlg/pq)

```bash
ffmpeg -i "$RAW_PATH" \
  -vf "zscale=t=linear:npl=100,format=gbrpf32le,zscale=p=bt709:t=bt709:m=bt709,tonemap=hable:desat=0,zscale=t=bt709,format=yuv420p" \
  -c:v libx264 -preset slow -crf 18 -c:a copy \
  "$OUT_DIR/sdr.mp4"
```

### 4. Crop browser chrome / dock

```bash
# Pro-tip: measure chrome height with ffprobe frame grab first
# Top 80px chrome + bottom 80px dock = crop 160px total
ffmpeg -i raw.mp4 \
  -vf "crop=in_w:in_h-160:0:80" \
  -c:v libx264 -preset slow -crf 18 -c:a copy \
  cropped.mp4
```

### 5. Brand grade (Clean High-Key — Dose/Dentist default)

```bash
ffmpeg -i sdr.mp4 \
  -vf "eq=brightness=0.03:contrast=1.05:saturation=0.92,curves=m='0/0.03 0.5/0.52 1/0.96'" \
  -c:v libx264 -preset slow -crf 18 -c:a copy \
  graded.mp4
```

Pro-tip: For **Female ProMedic** (warm rose), shift saturation up and add warmth:

```bash
ffmpeg -i sdr.mp4 \
  -vf "eq=brightness=0.03:contrast=1.04:saturation=0.97,colorbalance=rs=0.04:gs=-0.01:bs=-0.03,curves=m='0/0.04 0.5/0.53 1/0.97'" \
  -c:v libx264 -preset slow -crf 18 -c:a copy \
  graded_female.mp4
```

Pro-tip: For **Coach ProMedic** (neutral-warm, slightly saturated):

```bash
ffmpeg -i sdr.mp4 \
  -vf "eq=brightness=0.04:contrast=1.06:saturation=1.03,curves=m='0/0.02 0.5/0.53 1/0.98'" \
  -c:v libx264 -preset slow -crf 18 -c:a copy \
  graded_coach.mp4
```

### 6. Ken Burns from still image → clip

```bash
# ponytail: ALWAYS -framerate 30 on image inputs (VFR trap kills sync)
ffmpeg -framerate 30 -loop 1 -t 4 -i still.png \
  -vf "scale=3840:2160,zoompan=z='min(zoom+0.001,1.15)':d=120:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':s=1080x1920" \
  -c:v libx264 -t 4 -pix_fmt yuv420p \
  ken_burns.mp4
```

Pro-tip: Change `1.15` to your app's `{ZOOM_MAX}`. For Coach use `1.22`, for Dose/Dentist use `1.15`.

### 7. Image folder → slideshow video

```bash
# ponytail: -framerate 30 is mandatory, not optional
ffmpeg -framerate 30 -pattern_type glob -i 'images/*.png' \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2:black,zoompan=z='min(zoom+0.0008,1.12)':d=90:s=1080x1920" \
  -c:v libx264 -pix_fmt yuv420p -r 30 \
  slideshow.mp4
```

### 8. 9:16 blurred-fill from landscape source

```bash
ffmpeg -i landscape.mp4 \
  -filter_complex "[0:v]scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,boxblur=20:5[bg];[0:v]scale=1080:-2:force_original_aspect_ratio=decrease[fg];[bg][fg]overlay=(W-w)/2:(H-h)/2" \
  -c:v libx264 -preset slow -crf 18 \
  vertical_blurred.mp4
```

### 9. Mux voiceover — no A/V drift

```bash
# ponytail: apad + -shortest is the A/V drift killer. Never skip both.
ffmpeg -i video.mp4 -i voiceover.wav \
  -c:v copy -c:a aac -b:a 192k -ar 48000 \
  -af "apad" -shortest \
  muxed.mp4
```

### 10. Loudnorm (EBU R128 — all platforms)

```bash
# Standard: -14 LUFS (YouTube, IG, FB, LinkedIn)
ffmpeg -i input.mp4 \
  -af "loudnorm=I=-14:LRA=11:TP=-1" \
  -c:v copy -c:a aac -b:a 192k -ar 48000 \
  normalized.mp4

# TikTok loud-feed variant: -11 to -12 LUFS
ffmpeg -i input.mp4 \
  -af "loudnorm=I=-11:LRA=11:TP=-1" \
  -c:v copy -c:a aac -b:a 192k -ar 48000 \
  normalized_loud.mp4
```

### 11. Duck music under voiceover

```bash
# ponytail: volume=0.3 ducks music to ~10dB below VO; amix merges them
ffmpeg -i voiceover.wav -i music.mp3 \
  -filter_complex "[1:a]volume=0.3[music];[0:a][music]amix=inputs=2:duration=first:dropout_transition=2[out]" \
  -map "[out]" -c:a aac -b:a 192k -ar 48000 \
  mixed_audio.aac
```

Pro-tip: For dynamic ducking (music dips only when VO is speaking), use FFmpeg's `sidechaincompress`:

```bash
ffmpeg -i voiceover.wav -i music.mp3 \
  -filter_complex "[0:a]asplit=2[vo][sc];[1:a][sc]sidechaincompress=threshold=0.02:ratio=6:attack=200:release=1000[ducked];[vo][ducked]amix=inputs=2:duration=first[out]" \
  -map "[out]" -c:a aac -b:a 192k -ar 48000 \
  mixed_dynamic.aac
```

### 12. Silence detection (for dead-air cuts)

```bash
# Find silences longer than 0.4s at -30dB threshold (hyper pace)
ffmpeg -i input.mp4 -af "silencedetect=noise=-30dB:d=0.4" -f null - 2>&1 | grep "silence_"

# For balanced pace, use d=0.55
# For story pace, use d=0.75
```

### 13. Extract frames for QA check

```bash
# Grab frames at 25%, 50%, 75% of duration for visual QA
DURATION=$(ffprobe -v quiet -show_entries format=duration -of csv=p=0 input.mp4)
for pct in 25 50 75; do
  T=$(echo "$DURATION * $pct / 100" | bc -l)
  ffmpeg -ss "$T" -i input.mp4 -frames:v 1 "qa_frame_${pct}pct.png" -y
done
```

### 14. Final export — short-form (U1/U5 output)

```bash
ffmpeg -i processed.mp4 \
  -c:v libx264 -profile:v high -level 4.1 \
  -b:v 15M -maxrate 20M -bufsize 30M \
  -r 30 -g 60 \
  -c:a aac -b:a 192k -ar 48000 \
  -movflags +faststart \
  -vf "scale=1080:1920" \
  "$OUT_DIR/short_916.mp4"
```

### 15. Final export — long-form (U2 output)

```bash
ffmpeg -i processed.mp4 \
  -c:v libx264 -profile:v high -level 4.1 \
  -b:v 20M -maxrate 25M -bufsize 40M \
  -r 30 -g 60 \
  -c:a aac -b:a 192k -ar 48000 \
  -movflags +faststart \
  -vf "scale=1920:1080" \
  "$OUT_DIR/long_169.mp4"
```

### 16. Re-crop for feed formats (U4 output)

```bash
# 4:5 feed (1080x1350) — re-center, don't blind-crop
ffmpeg -i master.mp4 \
  -vf "scale=1080:1350:force_original_aspect_ratio=decrease,pad=1080:1350:(ow-iw)/2:(oh-ih)/2:black" \
  -c:v libx264 -crf 18 -c:a copy \
  "$OUT_DIR/feed_45.mp4"

# 1:1 feed (1080x1080)
ffmpeg -i master.mp4 \
  -vf "scale=1080:1080:force_original_aspect_ratio=decrease,pad=1080:1080:(ow-iw)/2:(oh-ih)/2:black" \
  -c:v libx264 -crf 18 -c:a copy \
  "$OUT_DIR/feed_11.mp4"
```

### 17. Whisper transcription (for captions — U3 step 0)

```bash
# ponytail: word-level timestamps are required for kinetic captions
# Whisper is 100% free, local, no API key — runs on CPU or GPU
whisper input.mp4 --model base --language en --output_format json --word_timestamps True --output_dir "$OUT_DIR"
```

Pro-tip: For better accuracy on medical/technical terms, use `--model small` or `--model medium` (still free, just slower).

### 18. Caption burn-in from SRT (free, local)

```bash
# Burn .srt subtitles directly into the video
ffmpeg -i input.mp4 -vf "subtitles=captions.srt:force_style='FontName=Arial,FontSize=22,PrimaryColour=&HFFFFFF,OutlineColour=&H000000,BorderStyle=3,Outline=2'" \
  -c:v libx264 -crf 18 -c:a copy \
  captioned.mp4
```

Pro-tip: For kinetic-style word-highlight, use `pysubs2` to split SRT into 2–4 word groups:

```bash
python3 -c "
import pysubs2
subs = pysubs2.load('captions.srt')
# pysubs2 is free: pip install pysubs2
for line in subs:
    words = line.text.split()
    # Split into 3-word chunks with even timing
    chunk_size = 3
    duration = line.end - line.start
    chunks = [words[i:i+chunk_size] for i in range(0, len(words), chunk_size)]
    for i, chunk in enumerate(chunks):
        t0 = line.start + (duration * i // len(chunks))
        t1 = line.start + (duration * (i+1) // len(chunks))
        print(f'{pysubs2.time.ms_to_str(t0)} --> {pysubs2.time.ms_to_str(t1)}')  
        print(' '.join(chunk))
"
```

### 19. Scene/shot detection (free, for interrupt placement)

```bash
# Detect scene changes — useful for finding where to place pattern interrupts
ffmpeg -i input.mp4 -vf "select='gt(scene,0.3)',showinfo" -f null - 2>&1 | grep showinfo
# Adjust 0.3 threshold: lower = more sensitive, higher = fewer cuts
```

### 20. Speed ramp (setup fast, payoff slow)

```bash
# 1.5× speed on setup (0-10s), normal speed on payoff (10s-end)
ffmpeg -i input.mp4 \
  -filter_complex "[0:v]trim=0:10,setpts=PTS/1.5[fast];[0:v]trim=10,setpts=PTS-STARTPTS[slow];[fast][slow]concat=n=2:v=1:a=0[v];[0:a]atrim=0:10,atempo=1.5[afast];[0:a]atrim=10,asetpts=PTS-STARTPTS[aslow];[afast][aslow]concat=n=2:v=0:a=1[a]" \
  -map "[v]" -map "[a]" -c:v libx264 -crf 18 -c:a aac -ar 48000 \
  speed_ramped.mp4
```

---

## Pro-Tips by Template

### U1 — Screen → 9:16 Short-Form

1. **Always probe before grading.** If source is already 1080×1920, skip reframe.
2. **Hook must work on mute.** Test by playing first 3s with volume at zero — if message is unclear, your captions/visuals failed.
3. **Count-up numbers > static pop.** For Dose Calculator results, animate 0→final in 0.5–0.8s with a soft pop SFX. Never just flash the number.
4. **Two variants minimum.** Always cut an ultra-tight (12–22s) AND a standard (25–40s). Different platforms reward different lengths.
5. **Zoom target = the number, not the full screen.** Ken Burns should drift toward the result/dose/value on screen.

### U2 — Screen → 16:9 Long + Feed

1. **Build 9:16 first, then expand.** Never start with long-form — you'll drift the grade. Short is the locked reference.
2. **Kinetic captions only in the hook.** After the first 5–12s, switch to steady full-clause subtitles. Constant kinetic text fatigues viewers on 3+ minute videos.
3. **Chapters are mandatory for YouTube.** Mark: Problem / Solution / Proof / How it works / CTA.
4. **Grid crop test for 4:5.** The key content must sit inside the central 1080×1080 band (y:135–1215) because Instagram crops to square on the profile grid.
5. **End-screen zone.** Keep the last 5–20s clear in the central 90% for YouTube end-screen cards.

### U3 — General Enhance

> **Promedic pack is conditional:** apply only for Dose / Female / Coach / Dentist. If not Promedic, skip brand rules and use general KIT+PACE.


1. **Name the tone in one word.** If you need three effects to describe your look, simplify. "Clinical." "Warm." "Gritty." One word.
2. **Script density = ~1 idea per 15s.** Don't cram multiple claims into one breath.
3. **Visual change every 7–10s minimum** for feed content (not just when the script changes — independently).
4. **Effects on app UI are poison.** Never stack grain + light-leak + blur + chromatic aberration on clinical numeric screens. Use `app-tech` kit = clean high-key, zero grain on numbers.
5. **Speed ramp recipe:** 1.5–2× on setup/context, normal or slight slow on payoff/result reveal.
6. **Promedic pack is conditional.** Detect Dose / Female / Coach / Dentist ProMedic first. If not Promedic → skip brand table, per-app zoom tiers, app CTAs, and platform picks; use general KIT+PACE only. If Promedic → force `app-tech`, inject brand table, enforce per-app zoom ceilings (hook included), format safe zones, short-form-first multi-export, save-reason CTAs, and app platform emphasis. Report `promedic_pack=applied|skipped`.
7. **When Promedic: identity = pacing, not only color.** Coach must feel faster (interrupts ~1.8–2.8s, wider zoom). Dose/Dentist stay precise. Female warmer/honest — not clinical-cold. Color alone does not brand the family.

### U4 — Platform-Specific

1. **Same grade, different pacing.** Never re-grade for a platform. Only change: crop, caption density, interrupts cadence, loudness, CTA language.
2. **LinkedIn is a different animal.** Skip zoom-punches for Dose/Dentist. Professional CTA. Trust > virality tricks. 16:9 or 1:1 preferred.
3. **TikTok vs Reels:** Almost identical pipeline, but TikTok rewards slightly louder (-11 LUFS vs -14) and faster hook pressure (1.0–1.3s intent vs ~2s for Reels).
4. **If master can't crop cleanly for a format, say so.** Mark INCONCLUSIVE and request a re-record. Don't force a broken crop.

### U5 — Viral Pipeline + Final Gate

1. **Step 1 (Hook) is highest ROI.** Spend 80% of your optimization time on the first 3 seconds.
2. **Loop engineering:** Match the last spoken word/visual fragment to flow back into the opening. Users rewatching = algorithm signal.
3. **QA is three-state.** PASS / FAIL / INCONCLUSIVE. "I think it's fine" = INCONCLUSIVE = not done.
4. **Max 3 re-render attempts.** If you can't pass QA in 3 tries, the input needs to change, not the render settings.

### U6 — Master Orchestrator

1. **Use U6 when you have raw material and want everything.** It chains A→J (capture → short → enhance → viral → long → feed → platform → SEO → app guardrails → final gate).
2. **Stage checkpoints.** After each stage (B, C, D...), verify the intermediate file before proceeding. Don't discover a grade problem at stage J.
3. **App guardrails are STOP conditions.** If any common mistake for the app appears in your plan or render → FAIL immediately. Don't finish and then check.

---

## Common Mistakes (from editor.addict.best §8)

### All Apps
- ❌ Starting with logo / greeting / slow fade → always cold-open
- ❌ Dead air longer than interrupt budget
- ❌ Captions outside safe zone
- ❌ Wrong safe-zone numbers for wrong format (e.g., using 9:16 zones on 16:9)
- ❌ SFX louder than voiceover
- ❌ Missing `-framerate 30` on image inputs
- ❌ Missing `apad` + `-shortest` when muxing audio
- ❌ Missing `-ar 48000` on final audio
- ❌ Claiming "done" without QA PASS

### Per-App Traps
| App | Never do this |
|:---|:---|
| Dose Calculator | Invent/hallucinate medical numbers. Use energetic meme grade. Exceed 1.15× zoom. |
| Female ProMedic | Use childish pink (it's rose-gold/blush). Mix Coach energy/pacing. |
| Coach ProMedic | Use clinical restraint — Coach is the highest-energy app. Forget readability on form cues. |
| Dentist Pro | Use teal identical to Dose blue (Dentist = teal/cyan, Dose = clinical blue). Over-punch on short-form. |

---

## Quick Shell One-Liners

```bash
# Check if video is HDR
ffprobe -v quiet -select_streams v:0 -show_entries stream=color_transfer -of csv=p=0 input.mp4
# If output is "smpte2084" or "arib-std-b67" → needs HDR→SDR

# Verify A/V sync drift
ffprobe -v quiet -show_entries stream=start_time -of csv=p=0 input.mp4
# Both streams should start at ~0.000000

# Check final loudness (post-loudnorm verification)
ffmpeg -i final.mp4 -af "loudnorm=I=-14:LRA=11:TP=-1:print_format=json" -f null - 2>&1 | tail -20

# Batch probe all outputs
for f in "$OUT_DIR"/*.mp4; do
  echo "=== $f ==="
  ffprobe -v quiet -show_entries stream=width,height,r_frame_rate,codec_name -show_entries format=duration,size -of flat "$f"
done

# Verify no watermark (check for alpha/overlay in bottom-right)
ffmpeg -ss 1 -i input.mp4 -frames:v 1 -vf "crop=200:50:iw-200:ih-50" check_watermark.png

# Quick safe-zone overlay for 9:16 (visual check)
ffmpeg -i short.mp4 -vf "drawbox=x=60:y=250:w=870:h=1200:color=red@0.3:t=2" -t 5 safezone_check.mp4
```

---

## Combining Templates — Real Examples

### Example 1: Dose Calculator → TikTok + Reels

```
1. Fill variables:  APP_NAME="Dose Calculator"  ZOOM_MAX="1.15"  WB="5900" ...
2. Run U1 (Screen → 9:16):
   - Archive raw → HDR check → crop chrome → grade (clean high-key) →
     Ken Burns on dose result → safe zone 1080×1920 →
     kinetic captions → count-up numbers → audio normalize →
     export short (12-22s) + standard (25-40s)
3. Run U3 (Enhance):
   - KIT=app-tech  PACE=balanced
   - Hook check → dead air cut → caption coverage check → loop attempt
4. Run U5 gate section:
   - QA all outputs → verify resolution, faceless, safe zone, zoom ≤ 1.15×
5. Run U4 SEO section:
   - Title: "Most clinicians miss this interaction — live dose fix"
   - Hashtags: #dosecalculator #clinicaltools #medicalapp
   - Save CTA: "Save this clinical reference"
```

### Example 2: Coach ProMedic → YouTube Long + IG Feed

```
1. Fill variables:  APP_NAME="Coach ProMedic"  ZOOM_MAX="1.22"  WB="5700" ...
2. Run U1 first (short master as grade reference)
3. Run U2 (Screen → 16:9 Long + Feed):
   - Expand from short master → 1920×1080 → chapters →
     kinetic hook only, then steady subtitles →
     interrupts every 6-10s → export long
   - Feed: re-center UI → 1080×1350 (4:5) + 1080×1080 (1:1)
4. Run U3 (Enhance) on long master
5. Run U5 (Final Gate) on all outputs
6. Run U4 SEO for YouTube:
   - Chapters: 0:00 Problem | 0:45 Solution | 1:30 Proof | 2:15 How | 3:00 CTA
   - Description first 150 chars = search intent
```

### Example 3: Full Production — U6 One-Shot

```
1. Fill variables + set JOBS="short_916,long_169,feed_45,feed_11,platform_pack"
2. U6 runs stages A→J automatically:
   A. Archive + HDR→SDR + chrome crop
   B. Short 9:16 master
   C. Enhance pass (retention ROI)
   D. Viral pipeline (hook→loop→variants)
   E. Long 16:9 from short
   F. Feed 4:5 + 1:1
   G. Platform pack (tiktok, reels, yt_shorts, yt_long, ig_feed_45, linkedin)
   H. SEO publish package per variant
   I. App guardrails check
   J. Final gate — all_pass required
3. Output: qa_report.md in {OUT_DIR}/reports/
```

---

## Six Deadly Sins (memorize these)

1. **VFR trap** — always `-framerate 30` on image inputs
2. **A/V drift** — always `apad` + `-shortest` when muxing, always `-ar 48000`
3. **Context decay** — save state checkpoints after every stage
4. **False positive "done"** — only QA PASS counts (INCONCLUSIVE = not done)
5. **Blind acceptance** — visually verify frames at 25/50/75% duration
6. **Face leak** — faceless absolute on all brand content, always check generated assets

---

## Safe Zone Quick Reference

| Format | Canvas | Safe area for text/captions | Grid-crop safe |
|:---|:---|:---|:---|
| 9:16 short | 1080×1920 | x: 60–930, y: 250–1450 | N/A |
| 16:9 long | 1920×1080 | x: 120–1800, y: 70–1010 | N/A |
| 4:5 feed | 1080×1350 | Central 1080×1080 (y: 135–1215) | Square center |
| 1:1 feed | 1080×1080 | Central ~90% | Full frame |
| Stories | 1080×1920 | Same as 9:16 but stricter top/bottom | N/A |

---

## Pacing Cheat Sheet

| Preset | Silence cutoff | Interrupt cadence | Best for |
|:---|:---|:---|:---|
| `hyper` | 0.40 s | 2.0–2.6 s | TikTok, Reels, Coach short-form |
| `balanced` | 0.55 s | 2.8–3.8 s | General short-form, Dose/Dentist |
| `story` | 0.75 s | 4.0–5.5 s | Long-form, tutorials, Female storytime |

---

## Free Tools Stack (zero paid dependencies)

Every command in this file uses free, open-source, locally-run tools. No paid API keys needed (your AI agent API is the only external dependency).

| Tool | What it does | Install | Cost |
|:---|:---|:---|:---|
| **FFmpeg** | All video/audio processing, export, grade, crop, mux | `brew install ffmpeg` (mac) / `apt install ffmpeg` (linux) | Free |
| **ffprobe** | Media analysis, duration, resolution, codec detection | Included with FFmpeg | Free |
| **Whisper** | Speech → text with word timestamps (captions) | `pip install openai-whisper` (runs locally, no API key) | Free |
| **pysubs2** | SRT/ASS caption manipulation, chunking, timing | `pip install pysubs2` | Free |
| **ImageMagick** | Image resize, overlay, thumbnail generation | `brew install imagemagick` / `apt install imagemagick` | Free |
| **bc** | Math in shell (duration calculations) | Pre-installed on mac/linux | Free |
| **jq** | JSON parsing (ffprobe output, Whisper JSON) | `brew install jq` / `apt install jq` | Free |
| **Python 3** | Scripting for batch ops, caption splitting | Pre-installed | Free |

**Not used, not needed:** No Adobe, no CapCut API, no RunwayML, no Eleven Labs, no paid cloud vision. The AI agent (your existing API) handles creative decisions; these tools handle execution.

---

## How to Merge This .md with editor.addict.best HTML

The goal: the HTML app has the 6 unified templates (the **what**). This .md has the commands and pro-tips (the **how**). Together they form one unified system. Here's how to combine them correctly.

### Method 1: AI Agent reads both files (simplest — recommended)

Give your AI agent both references in the system prompt or context:

```
You have two reference documents:
1. https://editor.addict.best — the master HTML app with 6 unified templates,
   conflict resolution laws, brand table, and full template text.
   Sections: #s1–#s9, #six-templates (u1–u6), #brand, #master
2. editor-pro-tips-and-commands.md — FFmpeg commands, pro-tips per template,
   combination recipes, free tool stack, QA one-liners.

Workflow:
- Pick template from the HTML (e.g. copy U1 from #u1-body)
- Fill {VARIABLES} using the brand table from HTML #brand
- Execute using FFmpeg commands from the .md
- QA using the shell one-liners from the .md
- SEO package using the .md combination examples
```

Pro-tip: The HTML has a search bar (press `/`) — tell the agent to use section IDs (`#s1`, `#u3`, `#brand`) to locate content fast.

### Method 2: Embed .md as a linked companion in the HTML

Add a single link in the HTML's nav or site-inventory section pointing to this file:

```html
<!-- Add to editor.addict.best nav section -->
<a href="/editor-pro-tips-and-commands.md">📋 Pro-Tips & Commands</a>
```

The .md is already served from the same web root at:
`https://editor.addict.best/editor-pro-tips-and-commands.md`

So the agent can fetch either file from the same domain. No merge needed — the HTML is the template source, the .md is the execution guide.

### Method 3: Section-to-section cross-reference

When chaining templates, map HTML sections to .md sections:

| Step | Read from HTML | Execute with .md |
|:---|:---|:---|  
| Pick template | `#u1-body` through `#u6-body` | — |
| Fill brand vars | `#brand` table | "Template Variables" block |
| Grade | Template's PHASE 2 step 1 | Recipe #5 (brand grade commands) |
| Motion / Ken Burns | Template's PHASE 2 step 2 | Recipe #6 (Ken Burns) or #7 (slideshow) |
| Captions | Template's PHASE 2 step 4 | Recipe #17 (Whisper) + #18 (burn-in) |
| Audio mux | Template's PHASE 2 step 6 | Recipe #9 (mux) + #10 (loudnorm) + #11 (duck) |
| Export | Template's PHASE 2 step 8 | Recipe #14 (short) or #15 (long) or #16 (feed) |
| QA | Template's PHASE 3 checklist | "Shell One-Liners" + Recipe #13 (frame extract) |
| SEO | Template's SEO section | "Combining Templates" examples |

### Method 4: Agent self-check loop

After any render, the agent should run this verification sequence (all free, all local):

```bash
# 1. File exists and has video stream?
ffprobe -v quiet -show_entries stream=codec_type -of csv=p=0 "$OUTPUT" | grep -q video && echo "PASS: has video" || echo "FAIL: no video stream"

# 2. Resolution correct?
RES=$(ffprobe -v quiet -show_entries stream=width,height -of csv=p=0 -select_streams v:0 "$OUTPUT")
echo "Resolution: $RES"  # Compare to expected canvas

# 3. Duration > 0?
DUR=$(ffprobe -v quiet -show_entries format=duration -of csv=p=0 "$OUTPUT")
echo "Duration: ${DUR}s"  # Must be > 0

# 4. FPS = 30?
FPS=$(ffprobe -v quiet -show_entries stream=r_frame_rate -of csv=p=0 -select_streams v:0 "$OUTPUT")
echo "FPS: $FPS"  # Should be 30/1

# 5. Audio sample rate = 48000?
SR=$(ffprobe -v quiet -show_entries stream=sample_rate -of csv=p=0 -select_streams a:0 "$OUTPUT")
echo "Sample rate: $SR"  # Must be 48000

# 6. Visual QA frames
for pct in 25 50 75; do
  T=$(echo "$DUR * $pct / 100" | bc -l)
  ffmpeg -ss "$T" -i "$OUTPUT" -frames:v 1 "qa_${pct}.png" -y 2>/dev/null
done
echo "QA frames saved — visually inspect for black/corrupt/face-leak"

# 7. Loudness check
ffmpeg -i "$OUTPUT" -af "loudnorm=I=-14:LRA=11:TP=-1:print_format=json" -f null - 2>&1 | grep input_i
```

All 7 checks use free tools. The AI agent reads the results and decides PASS / FAIL / INCONCLUSIVE per the HTML template's QA checklist.

---

*This .md supports editor.addict.best. The HTML app owns the templates — this file owns the commands, pro-tips, and merge logic. Both are served from the same domain. Together they are the complete system.*


---

## PROMEDIC BRAND PACK — CONDITIONAL (Template 3 / U3)

Use with **General Enhance (Template 3)** and screen templates when relevant.

### Detect
Set `IS_PROMEDIC=true` only if the job is clearly **Dose Calculator**, **Female ProMedic**, **Coach ProMedic**, or **Dentist Pro** (operator name, APP_NAME, or obvious app UI). If unclear → `false`.

### If NOT Promedic
- Skip this pack entirely.
- Do not invent Promedic CTAs, zoom tiers, or platform picks.
- Use general KIT + PACE + failure modes only.
- Report `promedic_pack=skipped`.

### If Promedic — selective rules only
1. Force/prefer `KIT=app-tech`; inject brand variable table for the app (table wins conflicts).
2. Zoom ceilings include hook: Dose/Dentist 1.08–1.15× · Female 1.08–1.18× · Coach 1.10–1.22×.
3. Identity = pacing, not only color (Coach faster; Dose/Dentist precise; Female warmer/honest).
4. Zoom target = on-screen result/number, not full chrome.
5. Safe zones: 9:16 caption centroid 20–55% + outer box; 16:9 title-safe + end-screen clear; feed 4:5 central 1080×1080 grid protection.
6. Cut 9:16 first, then expand long/feed from same project (no grade drift).
7. Save-reason CTAs per app register (e.g. Dose “Save this clinical reference”, Coach “Save this workout”).
8. Platforms: Dose/Dentist → LinkedIn/FB emphasis; Female → IG + carousel; Coach → Shorts + long-form energy curve.
9. Report `promedic_pack=applied | app=...`.

Source selective tips: AI-Agent Video Production Guide.md (brand pack only — not a full Template 3 replacement).