@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/sora/references/codex-network.md

@@ -0,0 +1,28 @@
+# Codex network approvals / sandbox notes
+
+This guidance is intentionally isolated from `SKILL.md` because it can vary by environment and may become stale. Prefer the defaults in your environment when in doubt.
+
+## Why am I asked to approve every video generation call?
+Video generation uses the OpenAI Video API, so the CLI needs outbound network access. In many Codex setups, network access is disabled by default (especially under stricter sandbox modes), and/or the approval policy may require confirmation before networked commands run.
+
+## How do I reduce repeated approval prompts (network)?
+If you trust the repo and want fewer prompts, enable network access for the relevant sandbox mode and relax the approval policy.
+
+Example `~/.codex/config.toml` pattern:
+
+```
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+
+[sandbox_workspace_write]
+network_access = true
+```
+
+Or for a single session:
+
+```
+codex --sandbox workspace-write --ask-for-approval never
+```
+
+## Safety note
+Use caution: enabling network and disabling approvals reduces friction but increases risk if you run untrusted code or work in an untrusted repository.

package/skills/sora/references/prompting.md

@@ -0,0 +1,137 @@
+# Prompting best practices (Sora)
+
+## Contents
+- [Mindset & tradeoffs](#mindset--tradeoffs)
+- [API-controlled params](#api-controlled-params)
+- [Structure](#structure)
+- [Specificity](#specificity)
+- [Style & visual cues](#style--visual-cues)
+- [Camera & composition](#camera--composition)
+- [Motion & timing](#motion--timing)
+- [Lighting & palette](#lighting--palette)
+- [Character continuity](#character-continuity)
+- [Multi-shot prompts](#multi-shot-prompts)
+- [Ultra-detailed briefs](#ultra-detailed-briefs)
+- [Image input](#image-input)
+- [Constraints & invariants](#constraints--invariants)
+- [Text, dialogue & audio](#text-dialogue--audio)
+- [Avoiding artifacts](#avoiding-artifacts)
+- [Remixing](#remixing)
+- [Iterate deliberately](#iterate-deliberately)
+
+## Mindset & tradeoffs
+- Treat the prompt like a cinematography brief, not a contract.
+- The same prompt can yield different results; rerun for variants.
+- Short prompts give more creative freedom; longer prompts give more control.
+- Shorter clips tend to follow instructions better; consider stitching two 4s clips instead of a single 8s if precision matters.
+
+## API-controlled params
+- Model, size, and seconds are controlled by API params, not prose.
+- Put desired duration in the `seconds` param; the prompt cannot make a clip longer.
+
+## Structure
+- Use short labeled lines; omit sections that do not matter.
+- Keep one main subject and one main action.
+- Put timing in beats or counts if it matters.
+- If you prefer a prose-first template, use:
+```
+<Prose scene description in plain language. Describe subject, setting, time of day, and key visual details.>
+
+Cinematography:
+Camera shot: <framing + angle>
+Mood: <tone>
+
+Actions:
+- <clear action beat>
+- <clear action beat>
+
+Dialogue:
+<short lines if needed>
+```
+
+## Specificity
+- Name the subject and materials (metal, fabric, glass).
+- Use camera language (lens, angle, shot type) for stability.
+- Describe the environment with time of day and atmosphere.
+
+## Style & visual cues
+- Set style early (e.g., "1970s film", "IMAX-scale", "16mm black-and-white").
+- Use visible nouns and verbs, not vague adjectives.
+- Weak: "A beautiful street at night."
+- Strong: "Wet asphalt, zebra crosswalk, neon signs reflecting in puddles."
+
+## Camera & composition
+- Prefer one camera move: dolly, orbit, lateral slide, or locked-off.
+- Straight-on framing is best for UI and text.
+- For close-ups, use longer lenses (85mm+); for wide scenes, 24-35mm.
+- Depth of field is a strong lever: shallow for subject isolation, deep for context.
+- Example framings: wide establishing, medium close-up, aerial wide, low angle.
+- Example camera motions: slow tilt, gentle handheld drift, smooth lateral slide.
+
+## Motion & timing
+- Use short beats: "0-2s", "2-4s", "4-6s".
+- Keep actions sequential, not simultaneous.
+- For 4s clips, limit to 1-2 beats.
+- Describe actions as counts or steps when possible (e.g., "takes four steps, pauses, turns in the final second").
+
+## Lighting & palette
+- Describe light quality and direction (soft window light, hard rim, backlight).
+- Name 3-5 palette anchors to stabilize color across shots.
+- If continuity matters, keep lighting logic consistent across clips.
+
+## Character continuity
+- Keep character descriptors consistent across shots; reuse phrasing.
+- Avoid mixing competing traits that can shift identity or pose.
+
+## Multi-shot prompts
+- You can describe multiple shots in one prompt, but keep each shot block distinct.
+- For each shot, specify one camera setup, one action, one lighting recipe.
+- Treat each shot as a creative unit you can later edit or stitch.
+
+## Ultra-detailed briefs
+- Use when you need a specific, filmic look or strict continuity.
+- Call out format/look, lensing/filters, grade/palette, lighting direction, texture, and sound.
+- If needed, include a short shot list with timing beats.
+
+## Image input
+- Use an input image to lock composition, character design, or set dressing.
+- The input image should match the target size and be jpg/png/webp.
+- The image anchors the first frame; the prompt describes what happens next.
+- If you lack a reference, generate one first and pass it as `input_reference`.
+
+## Constraints & invariants
+- State what must not change: "same shot", "same framing", "keep background".
+- Repeat invariants in every remix to reduce drift.
+
+## Text, dialogue & audio
+- Keep text short and specific; quote exact strings.
+- Specify placement and avoid motion blur.
+- For dialogue, use a dedicated block and keep lines short.
+- Label speakers consistently for multi-character scenes.
+- If silent, you can still add a small ambient sound cue to set rhythm.
+- Sora can generate audio; include an `Audio:` line and a short dialogue block when needed.
+- As a rule of thumb, 4s clips fit 1-2 short lines; 8s clips can handle a few more.
+
+Example:
+```
+Audio: soft ambient café noise, clear warm voiceover
+Dialogue:
+<dialogue>
+- Speaker: "Let's get started."
+</dialogue>
+```
+
+## Avoiding artifacts
+- Avoid multiple actions in 4-8 seconds.
+- Keep camera motion smooth and limited.
+- Add explicit negatives when needed: "avoid flicker", "avoid jitter", "no fast motion".
+
+## Remixing
+- Change one thing at a time: palette, lighting, or action.
+- Keep camera and subject consistent unless the change requests otherwise.
+- If a shot misfires, simplify: freeze the camera, reduce action, clear background, then add complexity back in.
+
+## Iterate deliberately
+- Start simple, then add one constraint per iteration.
+- If results look chaotic, reduce motion and simplify the scene.
+- When a result is close, pin it as a reference and describe only the tweak.

package/skills/sora/references/sample-prompts.md

@@ -0,0 +1,95 @@
+# Sample prompts (copy/paste)
+
+Use these as starting points. Keep user-provided requirements and constraints; do not invent new creative elements.
+
+For prompting principles (structure, invariants, iteration), see `references/prompting.md`.
+
+## Contents
+- [Product teaser (single shot)](#product-teaser-single-shot)
+- [UI demo (screen recording style)](#ui-demo-screen-recording-style)
+- [Cinematic detail shot](#cinematic-detail-shot)
+- [Social ad (6s with beats)](#social-ad-6s-with-beats)
+- [Motion graphics explainer](#motion-graphics-explainer)
+- [Ambient loop (atmosphere)](#ambient-loop-atmosphere)
+
+## Product teaser (single shot)
+```
+Use case: product teaser
+Primary request: close-up of a matte black wireless speaker on a stone pedestal
+Scene/background: dark studio cyclorama, subtle haze
+Subject: compact speaker with soft fabric texture
+Action: slow 20-degree orbit over 4 seconds
+Camera: 85mm, shallow depth of field, steady dolly
+Lighting/mood: soft key, gentle rim, premium studio feel
+Color palette: charcoal, slate, warm amber accents
+Constraints: no logos, no text
+Avoid: harsh bloom; oversharpening; clutter
+```
+
+## UI demo (screen recording style)
+```
+Use case: UI product demo
+Primary request: a clean mobile budgeting app demo showing a weekly spend chart
+Scene/background: neutral gradient backdrop
+Subject: smartphone UI, centered, screen content crisp and legible
+Action: tap the "Add expense" button, modal opens, amount typed, save
+Camera: locked-off, straight-on, no tilt
+Lighting/mood: soft studio light, minimal reflections
+Color palette: off-white, slate, mint accent
+Text (verbatim): "Add expense", "$24.50", "Groceries"
+Constraints: no brand logos; keep UI text readable; avoid motion blur
+```
+
+## Cinematic detail shot
+```
+Use case: cinematic product detail
+Primary request: macro shot of raindrops sliding across a car hood
+Scene/background: night city bokeh, soft rain mist
+Subject: glossy hood surface with water beads
+Action: slow push-in over 4 seconds
+Camera: 100mm macro, shallow depth of field
+Lighting/mood: moody, high-contrast reflections, soft speculars
+Color palette: deep navy, teal, silver highlights
+Constraints: no logos, no text
+Avoid: flicker; unstable reflections; excessive noise
+```
+
+## Social ad (6s with beats)
+```
+Use case: social ad
+Primary request: minimal coffee subscription ad with three quick beats
+Scene/background: warm kitchen counter, morning light
+Subject: ceramic mug, coffee bag, steam
+Action: beat 1 (0-2s) pour coffee; beat 2 (2-4s) steam rises; beat 3 (4-6s) mug slides to center
+Camera: 50mm, gentle handheld drift
+Lighting/mood: warm, cozy, natural light
+Text (verbatim): "Fresh roast" (top-left), "Weekly delivery" (bottom-right)
+Constraints: no logos; text must be legible; avoid fast motion
+```
+
+## Motion graphics explainer
+```
+Use case: explainer clip
+Primary request: clean motion-graphics animation showing data flowing into a dashboard
+Scene/background: soft gradient background
+Subject: abstract nodes and lines, simple dashboard cards
+Action: nodes connect, data pulses, cards fill with charts
+Camera: locked-off, no depth, flat design
+Lighting/mood: minimal, modern
+Color palette: off-white, graphite, teal, coral accents
+Constraints: no logos; keep shapes simple; avoid heavy texture
+```
+
+## Ambient loop (atmosphere)
+```
+Use case: ambient background loop
+Primary request: fog drifting through a pine forest at dawn
+Scene/background: tall pines, soft fog layers, distant hills
+Subject: drifting fog and light rays
+Action: slow lateral drift, subtle light change
+Camera: wide, locked-off, no tilt
+Lighting/mood: calm, soft dawn light
+Color palette: muted greens, cool gray, pale gold
+Constraints: no text, no logos, no people
+Avoid: fast motion; flicker; abrupt lighting shifts
+```

package/skills/sora/references/social-ads.md

@@ -0,0 +1,42 @@
+# Social ad templates (4-8s)
+
+Short clips work best with clear beats. Use 2-3 beats and keep text minimal.
+
+## Default template
+```
+Use case: social ad
+Primary request: <ad concept>
+Scene/background: <simple backdrop>
+Subject: <product or scene>
+Action: beat 1 (0-2s) <action>; beat 2 (2-4s) <action>; beat 3 (4-6s) <action>
+Camera: <shot type + motion>
+Lighting/mood: <mood>
+Text (verbatim): "<short headline>", "<short subhead>"
+Constraints: no logos; keep text legible; avoid fast motion
+```
+
+## Example: product benefit
+```
+Use case: social ad
+Primary request: a compact humidifier emphasizing quiet operation
+Scene/background: minimal bedroom nightstand
+Subject: matte white humidifier with soft vapor
+Action: beat 1 (0-2s) vapor begins; beat 2 (2-4s) soft glow turns on; beat 3 (4-6s) device slides to center
+Camera: 50mm, gentle push-in
+Lighting/mood: calm, warm night light
+Text (verbatim): "Quiet mist", "Sleep better"
+Constraints: no logos; text must be legible; avoid harsh highlights
+```
+
+## Example: before/after
+```
+Use case: social ad
+Primary request: before/after of a cluttered desk becoming tidy
+Scene/background: home office desk, neutral wall
+Subject: desk surface, organizer tray
+Action: beat 1 (0-2s) cluttered desk; beat 2 (2-4s) quick tidy motion; beat 3 (4-6s) clean desk with organizer
+Camera: top-down, locked-off
+Lighting/mood: soft daylight
+Text (verbatim): "Before", "After"
+Constraints: no logos; keep motion minimal; avoid blur
+```

package/skills/sora/references/troubleshooting.md

@@ -0,0 +1,58 @@
+# Troubleshooting
+
+## Job fails with size or seconds errors
+- Cause: size not supported by model, or seconds not in 4/8/12.
+- Fix: match size to model; use only "4", "8", or "12" seconds (see `references/video-api.md`).
+- If you see `invalid_type` for seconds, update `scripts/sora.py` or pass a string value for `--seconds`.
+
+## openai SDK not installed
+- Cause: running `python "$SORA_CLI" ...` without the OpenAI SDK available.
+- Fix: run with `uv run --with openai python "$SORA_CLI" ...` instead of using pip directly.
+
+## uv cache permission error
+- Cause: uv cache directory is not writable in CI or sandboxed environments.
+- Fix: set `UV_CACHE_DIR=/tmp/uv-cache` (or another writable path) before running `uv`.
+
+## Prompt shell escaping issues
+- Cause: multi-line prompts or quotes break the shell.
+- Fix: use `--prompt-file prompt.txt` (see `references/cli.md` for an example).
+
+## Prompt looks double-wrapped ("Primary request: Use case: ...")
+- Cause: you structured the prompt manually but left CLI augmentation on.
+- Fix: add `--no-augment` when passing a structured prompt file, or use the CLI fields (`--use-case`, `--scene`, etc.) instead of pre-formatting.
+
+## Input reference rejected
+- Cause: file is not jpg/png/webp, or has a human face, or dimensions do not match target size.
+- Fix: convert to jpg/png/webp, remove faces, and resize to match `--size`.
+
+## Download fails or returns expired URL
+- Cause: download URLs expire after about 1 hour.
+- Fix: re-download while the link is fresh; save to your own storage.
+
+## Video completes but looks unstable or flickers
+- Cause: multiple actions or aggressive camera motion.
+- Fix: reduce to one main action and one camera move; keep beats simple; add constraints like "avoid flicker" or "stable motion".
+
+## Text is unreadable
+- Cause: text too long, too small, or moving.
+- Fix: shorten text, increase size, keep camera locked-off, and avoid fast motion.
+
+## Remix drifts from the original
+- Cause: too many changes requested at once.
+- Fix: state invariants explicitly ("same shot and camera move") and change only one element per remix.
+
+## Job stuck in queued/in_progress for a long time
+- Cause: temporary queue delays.
+- Fix: increase poll timeout, or retry later; avoid high concurrency if you are rate-limited.
+
+## create-and-poll times out in CI/sandbox
+- Cause: long-running CLI commands can exceed CI time limits.
+- Fix: run `create` (capture the ID) and then `poll` separately, or set `--timeout`.
+
+## Audio or voiceover missing / incorrect
+- Cause: audio wasn't explicitly requested, or the dialogue/audio cue was too long or vague.
+- Fix: add a clear `Audio:` line and a short `Dialogue:` block.
+
+## Cleanup blocked by sandbox policy
+- Cause: some environments block `rm`.
+- Fix: skip cleanup, or truncate files instead of deleting.

package/skills/sora/references/video-api.md

@@ -0,0 +1,45 @@
+# Sora Video API quick reference
+
+Keep this file short; the full docs live in the OpenAI platform docs.
+
+## Models
+- sora-2: faster, flexible iteration
+- sora-2-pro: higher fidelity, slower, more expensive
+
+## Sizes (by model)
+- sora-2: 1280x720, 720x1280
+- sora-2-pro: 1280x720, 720x1280, 1024x1792, 1792x1024
+Note: higher resolutions generally yield better detail, texture, and motion consistency.
+
+## Duration
+- seconds: "4", "8", "12" (string enum; set via API param; prose will not change clip length)
+Shorter clips tend to follow instructions more reliably; consider stitching multiple 4s clips for precision.
+
+## Input reference
+- Optional `input_reference` image (jpg/png/webp).
+- Input reference should match the target size.
+
+## Jobs and status
+- Create is async. Status values: queued, in_progress, completed, failed.
+- Prefer polling every 10-20s or use webhooks in production.
+
+## Endpoints (conceptual)
+- POST /videos: create a job
+- GET /videos/{id}: retrieve status
+- GET /videos/{id}/content: download video data
+- GET /videos: list
+- DELETE /videos/{id}: delete
+- POST /videos/{id}/remix: remix a completed job
+
+## Download variants
+- video (mp4)
+- thumbnail (webp)
+- spritesheet (jpg)
+
+Download URLs expire after about 1 hour; copy files to your own storage for retention.
+
+## Guardrails (content restrictions)
+- Only content suitable for audiences under 18
+- No copyrighted characters or copyrighted music
+- No real people (including public figures)
+- Input images with human faces are currently rejected