parallax

name	parallax
description	Use when operating the Parallax CLI to produce AI-generated short-form videos. Covers project setup, brief authoring, the plan→produce loop, asset locking, model selection, and cost management.
version	0.5.34

Parallax CLI — Operator Skill

Version: 0.5.34 — run parallax --version on load. If the installed version is higher, warn the user that the skill may be behind and suggest running parallax update to check the changelog.

Agentic creative production CLI. A brief.yaml goes in; a finished short-form video comes out — stills, voiceover, animated clips, captions, all routed through OpenRouter.

Install check:

parallax --version
parallax update   # uv tool upgrade parallax --reinstall

Required env var:

export OPENROUTER_API_KEY=sk-or-...

---

Core loop

Two artifacts drive every project:

• brief.yaml — human spec. Author once; edit between iterations.
• plan.yaml — engine spec. Generated by parallax plan; edit to lock assets.

brief.yaml → parallax plan → plan.yaml → parallax produce → output/vN/video.mp4

One-shot (plan + produce in one command):

parallax produce --folder ./my-project --brief ./my-project/brief.yaml

Two-step (inspect/edit the plan before spending):

parallax plan    --folder ./my-project --brief ./my-project/brief.yaml
# plan lands at ./my-project/parallax/scratch/plan.yaml — inspect, edit
parallax produce --folder ./my-project --plan ./my-project/parallax/scratch/plan.yaml

Non-interactive (skip confirmation prompt — required for sub-agents):

parallax produce --folder ./my-project --brief ./my-project/brief.yaml -y

Resolution override (sets both output and animate resolution):

parallax produce --folder ./my-project --brief ./my-project/brief.yaml --resolution 480x854
parallax plan    --folder ./my-project --brief ./my-project/brief.yaml --resolution 480x854

Validate without spending:

parallax validate --folder ./my-project --brief ./my-project/brief.yaml

Paths: Always use absolute paths for --folder. Never construct paths relative to $PWD inside a worktree — it resolves by accident and breaks. Use the repo-root sandbox: /Users/ianburke/Documents/GitHub/parallax-v0/sandbox/<project>. Paths with spaces must be quoted.

---

brief.yaml format

goal: "30-second direct-response ad"
aspect: "9:16"          # 9:16 | 16:9 | 1:1 | 4:3 | 3:4
voice: Fenrir           # default: nova
voice_speed: 1.1        # default: 1.0
animate_resolution: null # set to e.g. "720x1280" for HQ video gen

pronunciations:
  Tongkat Ali: tongkat ali

success_criteria:
  - "All scenes use consistent character"

script:
  scenes:
    - index: 0
      shot_type: broll         # broll | character | screen
      vo_text: "[rapidly] Hook line here."
      prompt: "Cinematic shot of..."

    - index: 1
      shot_type: character
      vo_text: "[dramatically] Second beat."
      prompt: "Close-up of..."
      animate: true
      motion_prompt: "Slow zoom in"
      aspect: null             # per-scene aspect override

Per-scene reference images — pass one or more images as generation references for a specific scene:

script:
  scenes:
    - index: 0
      shot_type: broll
      vo_text: "..."
      prompt: "..."
      image_refs:
        - brand/product.png
        - brand/product_alt.png

Character consistency — set character_reference: true at the brief level so every shot_type: character scene automatically uses character_image as its reference during still generation:

character_reference: true

assets:
  provided:
    - path: brand/founder.png
      kind: character_ref   # planner resolves this to plan.character_image

Providing existing footage — add to assets.provided; reference in scenes via prompt:

assets:
  provided:
    - path: brand/product.mp4
      kind: product_ref
      description: "Existing product footage"

clip_path and still_path are plan.yaml fields (asset locks set after the first run), not brief fields.

---

plan.yaml — production settings

Model, caption, and transition settings live in plan.yaml (not brief.yaml). Set them before running parallax produce:

voice_model: tts-mini        # tts-mini (default) | tts-gemini
image_model: grok-image      # RECOMMENDED for image quality + ref fidelity
video_model: mid             # mid = Grok Imagine Video (RECOMMENDED) | draft | premium | wan | sora
caption_style: bangers        # bangers (default) | anton | or custom dict
fontsize: 55
words_per_chunk: smart        # smart (default) | integer
caption_shift_s: 0.0
default_transition: null      # transition type
default_transition_duration_s: 0.5
stills_only: false            # true = Ken Burns only, no video gen
trim_pauses: true             # true | false | float (max pause seconds)
style: null                   # global style hint for image gen
style_hint: null              # additional style guidance
resolution: null              # output resolution e.g. "480x854"
animate_resolution: null      # video gen resolution e.g. "480x854"
headline: null                # persistent headline text overlay
headline_fontsize: null
headline_bg: null             # e.g. "0x000000"
headline_color: null          # e.g. "0xFFFFFF"
captions: null                # caption mode override
caption_animation: null       # animation style for captions
titles: null                  # list of title card objects
avatar: null                  # avatar config object
voice_postprocess: null       # post-processing pipeline for voice audio

plan.yaml — asset locking

After a run, output/vN/plan.yaml is a read-only snapshot. The working plan is parallax/plan.yaml (or wherever you pointed --plan). Lock approved assets so only changed scenes regenerate:

# Lock a still
- index: 0
  still_path: parallax/output/v1/stills/openrouter_mid_1234567_n1080x1920.png
  vo_text: "..."

# Lock audio
- index: 1
  audio_path: parallax/output/v1/audio/voiceover.wav
  words_path: parallax/output/v1/audio/vo_words.json
  vo_text: "..."   # must match what was rendered

# Lock a generated clip
- index: 2
  clip_path: parallax/output/v1/video/openrouter_kling_1234567.mp4
  vo_text: "..."

# Per-scene reference controls
- index: 3
  reference: true          # use plan.character_image as the still-generation reference
  reference_images:        # explicit list overrides the reference: true fallback
    - brand/hero.png
  vo_text: "..."

Re-run to regenerate only unlocked scenes:

parallax produce --folder ./my-project --plan ./my-project/parallax/plan.yaml

---

Models

parallax models list          # full catalog grouped by kind
parallax models show mid --kind image
parallax models show tts-gemini

Image:

Alias	Cost	Notes
grok-image	~$0.05/img	Recommended. xAI Grok Imagine. Strong ref fidelity, all aspects
draft	$0.039/img	Gemini 2.5 Flash. Sometimes ignores non-square aspect ratios — prefer mid or grok-image for 9:16/16:9
mid	$0.039/img	Gemini 3.1 Flash. Honors aspect natively
premium	$0.080/img	Gemini 3 Pro. Best Gemini fidelity
nano-banana	$0.039/img	Gemini 2.5 Flash. Multi-ref compositing
gemini-3-flash	$0.039/img	Gemini 3.1 Flash. Same as mid
gemini-3-pro	$0.080/img	Gemini 3 Pro. Same as premium

Video:

Alias	Cost	Notes
mid / grok-video	~$0.05/s	Recommended. xAI Grok Imagine Video. 480p/720p. Strong prompt adherence
draft	$0.054/s	Seedance 2.0 Fast. $0.054/s at 480p, $0.121/s at 720p, $0.272/s at 1080p
premium	$0.400/s	Veo 3.1. $0.40/s 1080p w/ audio, $0.20/s w/o, $0.60/s 4K
wan	$0.100/s	Wan 2.7. Open-weights baseline. Flat $0.10/s
sora	$0.500/s	OpenAI Sora 2 Pro. Text-to-video only. $0.30/s 720p, $0.50/s 1080p

TTS:

Alias	Notes
tts-mini	Default. OpenAI gpt-audio-mini. Strips [emotional] tags
tts-gemini	Expressive. Supports inline [emotional] tags: [dramatically], [rapidly], [excitedly], [softly], [whispering]

Voices (tts-gemini):

• Dramatic: Fenrir (excitable), Kore (firm), Charon (informative), Puck (upbeat)
• Warm: Aoede (breezy), Sulafat (warm), Achird (friendly), Sadaltager (knowledgeable)
• Soft: Achernar (soft), Enceladus (breathy), Vindemiatrix (gentle)

Default voice: nova

---

Standalone commands

# Image generation
parallax image generate "prompt" --aspect 9:16 --model grok-image
parallax image generate "prompt" --ref ./face.png       # with reference
parallax image generate "prompt" --size 480x854          # explicit WxH
parallax image analyze ./frame.png "color palette?"

# Voiceover synthesis
parallax audio voiceover --text "Hello world" --out /tmp/vo.mp3 --voice Fenrir --voice-model tts-gemini
parallax audio voiceover --text "Hello world" --out /tmp/vo.mp3 --speed 1.2  # with atempo

# Video generation
parallax video animate --prompt "Slow zoom in" --start ./frame.png --model mid --out ./clip.mp4
parallax video animate --prompt "Motion" --ref ./ref.png --duration 5

# Audio utilities
parallax audio transcribe ./clip.mp4
parallax audio detect-silences ./clip.mp4
parallax audio trim ./clip.mp4 --start 1.5 --end 8.0
parallax audio cap-pauses       # cap inter-word gaps (word-driven, not amplitude)
parallax audio pad-onsets        # ensure minimum lead-in silence per word
parallax audio speed ./clip.mp3 --rate 1.2   # or --by 20%

# Video utilities
parallax video frame ./clip.mp4 --at 2.5     # extract frame at timestamp
parallax video color ./clip.mp4              # sample pixel color → 0xRRGGBB

# Index footage for search
parallax ingest ./clips/
parallax ingest video.mov --estimate         # dry-run cost report

# Cost + credits
parallax credits          # OpenRouter balance
parallax usage            # spend by model/session
parallax log latest       # last run summary
parallax log list         # all runs

# Validation + schema
parallax validate --folder ./project --brief ./project/brief.yaml
parallax validate --folder ./project --plan ./project/parallax/plan.yaml
parallax schema           # human-readable overview of brief + plan fields
parallax schema brief     # JSON schema for brief.yaml
parallax schema plan      # JSON schema for plan.yaml

# Verify suite
parallax verify run                    # run all verify cases
parallax verify scaffold <case-name>   # scaffold a new verify case

---

Dry run (no spend)

PARALLAX_TEST_MODE=1 parallax produce --folder ./my-project --brief ./my-project/brief.yaml

Full pipeline runs end-to-end with stub assets. Use to validate brief structure before spending.

---

Output layout

my-project/
  brief.yaml
  parallax/
    plan.yaml             ← working plan (edit between iterations)
    scratch/
      plan.yaml           ← landing zone for `parallax plan` output
    output/
      v1/
        project-v1-<hash>.mp4
        plan.yaml         ← snapshot — do not edit
        manifest.yaml
        cost.json
        run.log
        stills/
        audio/
        video/
      v2/
        ...

---

Rules

• --folder is the project root; all paths in plan.yaml are relative to it
• Never edit output/vN/plan.yaml — it's a snapshot
• Lock assets before re-running — unlocked scenes regenerate and cost money
• Use tts-gemini + [emotional] tags for any ad that needs pacing variation
• Default to grok-image for image and mid (Grok Imagine Video) for video — best quality-per-dollar, strong aspect ratio support
• STOP before calling parallax image generate with --model draft and a non-square aspect (9:16, 16:9, 3:4, 4:3): draft sometimes ignores the aspect ratio. Use grok-image or mid instead.
• For non-interactive / sub-agent runs, always pass -y to parallax produce
• Run parallax validate before parallax produce to catch brief/plan errors without spending credits
• Output flag is --out <path>, never --output — that flag does not exist.
• macOS screenshot filenames use Unicode characters (middle dots, narrow no-break spaces), not regular spaces — they cannot be constructed by hand. Always resolve via find and copy to /tmp/ first:

  SRC=$(find . -maxdepth 1 -name "Screenshot*" -type f | head -1)
  cp "$SRC" /tmp/source.png
  

  Then pass /tmp/source.png to --ref.