@scenerok/cli 1.0.0 → 1.0.1

package/skills/claude/vidscript-guide.md

@@ -0,0 +1,356 @@
+# VidScript Language Reference (v2)
+
+VidScript is a declarative DSL for composing short-form videos. Write a script, render an MP4.
+
+## Program Structure
+
+A VidScript program is a sequence of statements separated by newlines.
+
+```vidscript
+# Single-line comment
+/* Multi-line
+   comment */
+```
+
+## Statements
+
+### Input Declaration
+
+```vidscript
+input hero = "https://cdn.example.com/hero.mp4"
+input logo = "./assets/logo.png"
+```
+
+Supports HTTP(S) URLs, `/uploads/` paths, and local paths.
+
+### Output Declaration
+
+```vidscript
+output to "video.mp4", resolution: "1080x1920", fps: 30
+output to "reel.mp4", resolution: "720x1280", format: "mp4", codec: "h264", bitrate: "5M", background: "#0D0D0D"
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `resolution` | string | `"1080x1920"` | Width×Height or single number |
+| `fps` | number | `30` | Frames per second |
+| `format` | string | `"mp4"` | Container format |
+| `codec` | string | `"h264"` | Video codec |
+| `bitrate` | string | `"5M"` | Encoding bitrate |
+| `background` | string | `"#000000"` | Background color hex |
+
+### Variable Assignment
+
+```vidscript
+let brandColor = "#6366F1"
+let fadeTime = 0.5s
+let titleSize = 72
+let clipName = "hero"
+```
+
+Variables can hold strings, numbers, time literals, and object expressions. Variables are evaluated at compile time.
+
+### Import / Export (Module System)
+
+```vidscript
+# Export a constant
+export const BRAND_COLOR = "#FF5733"
+
+# Export a timeline
+export timeline intro(clip: string, title_text: string) {
+  [-] = clip
+  [- 2s] = text title_text, size: 72
+}
+
+# Import from another file
+import { intro, BRAND_COLOR } from "./timelines.vid"
+
+# Import namespace
+import * as transitions from "@scenerok/transitions"
+
+# Use a timeline
+use intro at 0s .. 5s with { clip: hero, title_text: "Hello" }
+```
+
+## Time Blocks
+
+Time blocks are the core of VidScript. They define when instructions execute on the timeline.
+
+### Dynamic Playhead (recommended)
+
+```vidscript
+[-] = hero                            # auto-append: starts after previous block
+[- 3s] = text "Title", size: 72       # auto-start, last 3 seconds 
+[- 2.5s] = filter "glow", intensity: 0.8
+```
+
+The playhead cursor (`prev`) tracks where the timeline is. Each `[-]` block advances the cursor by the block's content duration. `[- duration]` advances by an explicit duration.
+
+### Explicit Range
+
+```vidscript
+[0s .. 5s] = hero                      # absolute range
+[0.5s .. 3s] = text "Hello"            # explicit times
+[prev + 1s .. prev + 4s] = filter "glow"  # expression-based
+```
+
+Use `..` (not `-`) as the range separator to avoid ambiguity with subtraction.
+
+### Time Formats
+
+```vidscript
+5s           # 5 seconds
+300ms        # 300 milliseconds
+frame 90     # 90 frames at 30fps = 3 seconds  
+0:30         # 30 seconds
+1:30:00      # 1 hour 30 minutes
+```
+
+### The `prev` Keyword
+
+`prev` refers to the current playhead position — the end time of the previous block.
+
+```vidscript
+[- 2s] = text "Hello"                              # plays from cursor to cursor+2s
+[prev + 1s .. prev + 3s] = filter "glow"           # 1s after text ends, for 2s
+```
+
+## Instructions (inside time blocks)
+
+Multiple instructions in the same time block go on separate lines:
+
+```vidscript
+[0s .. 5s] = hero
+hero.Trim(start: 0s, end: 5s)
+hero.Speed(factor: 1.5)
+```
+
+### Clip Reference
+
+```vidscript
+[-] = hero              # just play the input clip
+```
+
+### Text Overlay
+
+```vidscript
+[- 3s] = text "Hello World", font: "Bebas Neue", x: "50%", y: "45%", align: center, color: "#FFFFFF", size: 72, stroke: "#000000", stroke_width: 3, letter_spacing: 4, shadow_color: "#FF0055", shadow_blur: 8
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `style` | string | `title` (64px), `subtitle` (54px), `caption` (36px), or `default` (48px) |
+| `position` | string | `center`, `top`, `bottom`, `top-left`, `top-right`, `bottom-left`, `bottom-right` |
+| `x` | number \| string | Horizontal position. Number = px from left. `"50%"` = percent of width. Overrides `position`. |
+| `y` | number \| string | Vertical position. Number = px from top. `"50%"` = percent of height. Overrides `position`. |
+| `color` | string | Hex color |
+| `size` | number | Font size in pixels |
+| `font` | string | Font family. System fonts or Google Fonts: `"Inter"`, `"Bebas Neue"`, `"Space Grotesk"`, `"Outfit"`, etc. |
+| `align` | string | `left`, `center`, `right`. Default: `center` |
+| `line_height` | number | Line height multiplier for multi-line text. Default: 1.2 |
+| `letter_spacing` | number | Extra letter spacing in pixels. Default: 0 |
+| `rotation` | number | Rotation in degrees. Positive = clockwise. Default: 0 |
+| `opacity` | number | Opacity 0–1. Default: 1 |
+| `stroke` | string | Outline color |
+| `stroke_width` | number | Outline thickness |
+| `shadow_color` | string | Drop shadow color |
+| `shadow_blur` | number | Shadow blur radius |
+| `shadow_offset_x` | number | Shadow horizontal offset |
+| `shadow_offset_y` | number | Shadow vertical offset |
+| `animation` | string | Parsed but not yet rendered |
+
+Params are optional and comma-separated. Params can be on the same line as the content.
+
+### Video Methods
+
+```vidscript
+hero.Trim(start: 0s, end: 5s)         # trim clip (positional: hero.Trim(0s, 5s))
+hero.Resize(width: 720, height: 1280)  # resize (positional: hero.Resize(720, 1280))
+hero.Speed(factor: 1.5)                # playback rate
+hero.Loop(count: 3)                    # loop count
+hero.Opacity(value: 0.5, duration: 2s) # opacity with duration
+```
+
+Arguments can be positional or named using `:`.
+
+### Compositing
+
+```vidscript
+hero.Overlay(logo, x: 50, y: 100, opacity: 0.8)
+hero.Composite(overlay, x: 0, y: 0, opacity: 0.5, mode: "screen")
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `x` | number | Horizontal offset |
+| `y` | number | Vertical offset |
+| `opacity` | number | 0–1 transparency |
+| `mode` | string | Blend mode for Composite |
+
+### Filters
+
+```vidscript
+[- 2s] = filter "glow", intensity: 0.8
+[0s .. 5s] = filter "vignette", intensity: 0.3
+```
+
+Built-in filters: `monochrome`, `sepia`, `blur`, `chromatic`, `glitch`, `vignette`, `contrast`, `saturation`, `brightness`.
+
+### Shaders
+
+```vidscript
+import shader glow from "shader-pack/glow.glsl"
+
+[0s .. 5s] = shader glow, intensity: 0.8
+```
+
+### Audio
+
+```vidscript
+audio music, volume: 0.5, fade_in: 1s, fade_out: 2s
+```
+
+Audio sources can be MP3 inputs, audio plugin results, or the embedded audio stream from an input video. Video clips are visually silent unless you explicitly add `audio clip`.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `volume` | number | 0–1 |
+| `fade_in` | number | Fade-in duration (seconds) |
+| `fade_out` | number | Fade-out duration (seconds) |
+
+### Plugin Calls (explicit default import — the only supported form)
+
+```vidscript
+import xai from "@scenerok/xai"
+import eleven from "@elevenlabs/tts"   # example future scoped package
+
+[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16")
+[-] = audio xai.tts("Welcome to SceneRok", voice: "eve")
+[-] = audio eleven.tts("Hello", voice: "Rachel")
+[-] = audio music("upbeat launch soundtrack", duration: 12, instrumental: true)
+```
+
+**Rule:** Always start with `import name from "@scope/pkg"`. No more bare globals or named imports. This is the single obvious syntax for both humans and LLMs.
+
+Plugins are npm packages that add new function names. The built-in server registration includes xAI media/TTS (via `@scenerok/xai`) and others when keys are configured. They run at compile time.
+
+## Animations, Effects & Plugins (v2 Extensibility)
+
+VidScript v2 uses a **minimal-grammar, plugin-first** architecture for animations and effects.
+
+Instead of adding dozens of animation keywords to the language, we use two powerful parameters:
+
+- `animate:`
+- `effects:`
+
+These accept either plugin function calls or plain object descriptors.
+
+### animate: parameter
+
+Attach animations to **any** text or video surface.
+
+```vidscript
+text "Hello", animate: fadeIn(0.8s)
+
+video hero, animate: [fadeIn(0.5s), slideY(-40, 0, 1.2s)]
+
+text "Title", animate: {
+  type: "fade",
+  from: { opacity: 0 },
+  to: { opacity: 1 },
+  start: 0,
+  end: 1.5
+}
+```
+
+### effects: parameter
+
+Attach post-processing effects, with support for animated parameters.
+
+```vidscript
+text "Dramatic", effects: [grayscale(intensity: 0.8)]
+
+video hero, effects: [{
+  name: "glitch",
+  strength: animate: { type: "fade", from: { strength: 0 }, to: { strength: 1 } }
+}]
+```
+
+### Currently Available Animation Functions (`basic-animations` plugin)
+
+| Function                  | Description                  |
+|---------------------------|------------------------------|
+| `fadeIn(duration?)`       | Opacity 0 → 1                |
+| `fadeOut(duration?)`      | Opacity 1 → 0                |
+| `slideX(from, to, dur?)`  | Horizontal slide             |
+| `slideY(from, to, dur?)`  | Vertical slide               |
+| `popIn(duration?)`        | Scale + fade entrance        |
+| `riseIn(duration?, dist?)` | Upward fade entrance         |
+| `swingIn(duration?)`      | Rotating slide/fade         |
+| `glitchIn(duration?)`     | Jitter + flash entrance      |
+| `float(duration?, amp?)`   | Gentle vertical bob          |
+| `typewriter(duration?)`   | Character reveal             |
+
+More plugins (advanced text animations, pixel effects, 3D, etc.) are planned.
+
+The full architecture and IR details live in `plan-v1/29-surface-animation-effect-plugin-architecture.md`.
+
+## Expressions
+
+Used in time specs, `let` values, and function arguments:
+
+```vidscript
+let x = 5s                    # Time literals
+let y = x * 2                 # Arithmetic
+let prompt = "Scene: " + title_text  # String concatenation
+let z = prev + 0.5s           # Playhead reference
+let a = { primary: "#FF5733" } # Objects
+```
+
+Operators: `+`, `-`, `*`, `/` with standard precedence.
+
+## Template Placeholders
+
+```vidscript
+[- 3s] = text "{{headline | Default Text}}", color: "{{color | #FFFFFF}}"
+```
+
+Placeholders are filled before parsing via `fillPlaceholders()`.
+
+## CLI Commands
+
+```bash
+# Authenticate
+scenerok auth login
+
+# Validate a script
+scenerok validate my-video.vid
+
+# Render a video
+scenerok project upload my-video.vid --assets ./assets --render --watch --download ./renders
+scenerok project render <project-id> --watch --download ./renders
+scenerok render my-video.vid --project-id <project-id> --watch
+scenerok cache pull
+
+# Check render status  
+scenerok status <render-id>
+
+# Install agent skills
+scenerok skills install <platform>
+
+# Set API secrets for plugins
+scenerok secrets set ELEVENLABS_API_KEY=your-key
+```
+
+## Best Practices
+
+1. **Use dynamic timeblocks** — `[-]` auto-advances the cursor, reducing calculation errors
+2. **Use `prev` for offsets** — `[prev + 0.5s .. prev + 2s]` for gaps after previous content
+3. **1080×1920 for vertical** (TikTok, Reels, Shorts), **1920×1080 for horizontal** (YouTube)
+4. **Hook viewers in the first 3 seconds** — place the most compelling content early
+5. **High-contrast text** — use `stroke` and `stroke_width` on text overlays over video
+6. **Test with `scenerok validate` first** — catch syntax errors before spending render credits
+7. **Keep text content short** — text disappears when the time block ends
+8. **One instruction per line** — each instruction inside a timeblock goes on its own line
+9. **Text-only auto blocks** — `[-] = text ...` lasts 2 seconds by default; use `[- 3s]` for custom timing
+10. **Named arguments are clearer** — `hero.Trim(start: 0s, end: 5s)` over `hero.Trim(0s, 5s)`

package/skills/claude/vidscript-sample.md

@@ -0,0 +1,21 @@
+# VidScript v2 Sample — Product Launch Promo
+# A 6-second vertical video for TikTok / Instagram Reels
+# Demonstrates dynamic timeblocks, video shorthand, named args, expressions, and filters
+
+input hero = "{{hero_clip}}"
+
+# Auto-append: cursor starts at 0, each [-] advances automatically
+[-] = video hero
+hero.Trim(start: 0s, end: 6s)
+
+# Text overlays with comma-separated named params
+[0.3s .. 2.3s] = text "NEW DROP", style: title, position: top, color: "#FFFFFF", size: 64, stroke: "#000000", stroke_width: 3
+
+[2.5s .. 4.5s] = text "The most anticipated release of the season", style: caption, position: center, color: "#F3F4F6", size: 36, stroke: "#000000", stroke_width: 2
+
+[4.5s .. 5.8s] = text "SHOP NOW", style: title, position: bottom, color: "#F59E0B", size: 52, stroke: "#000000", stroke_width: 3
+
+# Filter applied from start to end of the clip
+[0s .. 6s] = filter "vignette", intensity: 0.35
+
+output to "product-launch.mp4", resolution: "1080x1920", fps: 30

package/skills/codex/SKILL.md

@@ -0,0 +1,171 @@
+# SceneRok Skill for Claude Code
+
+## Overview
+
+You are a VidScript composer and video generation expert integrated with Claude Code. You help users create video content using the SceneRok platform directly from their terminal.
+
+## Capabilities
+
+- Compose VidScript files for video generation
+- Validate VidScript syntax before rendering
+- Submit render jobs to SceneRok
+- Check render status and retrieve output
+- Guide users through video creation workflows
+- Fill template placeholders and customize system templates
+
+## VidScript Language
+
+VidScript is a declarative language for describing video compositions using time blocks, inputs, text overlays, video operations, filters, and compositing.
+
+### Core Concepts
+
+**Inputs** - Declare video sources:
+```vidscript
+input hero = "https://cdn.example.com/hero.mp4"
+input logo = "/uploads/logo.png"
+```
+
+**Time Blocks** - Define what happens during a time range:
+```vidscript
+[-] = hero                               # auto-append: starts after previous block
+hero.Trim(start: 0s, end: 5s)
+
+[- 3s] = text "Hello", style: title, color: "#FFF"   # auto-start, 3s duration
+[0s .. 5s] = hero                                     # explicit range
+[prev + 0.5s .. prev + 2s] = filter "glow"            # expression-based
+```
+
+**Video Operations** - Modify how video plays:
+```vidscript
+hero.Trim(start: 0s, end: 5s)      # trim clip
+hero.Speed(factor: 1.5)             # 50% faster
+hero.Resize(width: 1080, height: 1920)
+hero.Loop(count: 3)                 # play 3 times
+hero.Opacity(value: 0.5, duration: 2s)
+```
+
+**Compositing** - Layer videos:
+```vidscript
+base.Overlay(logo, x: 50, y: 50, opacity: 0.8)
+```
+
+**Filters & Shaders** - Post-processing effects:
+```vidscript
+[0s .. 5s] = filter "vignette", intensity: 0.4
+[2s .. 4s] = filter "sepia", intensity: 0.6
+```
+
+Built-in filters: `monochrome`, `sepia`, `blur`, `chromatic`, `glitch`, `vignette`, `contrast`, `saturation`, `brightness`
+
+**Text Overlays** - Add on-screen text:
+```vidscript
+[0.5s .. 3s] = text "Headline", style: title, position: center, color: "#FFF", size: 72, stroke: "#000", stroke_width: 3
+```
+
+**Output** - Specify render settings:
+```vidscript
+output to "video.mp4", resolution: "1080x1920", fps: 30
+```
+
+### Module System
+
+```vidscript
+export const BRAND_COLOR = "#FF5733"
+export timeline intro(clip: string, headline: string) {
+  [-] = clip                                # auto-append
+  clip.Trim(start: 0s, end: 3s)
+  [- 2s] = text headline, style: title      # auto-start, 2s duration
+}
+```
+
+```vidscript
+import { intro } from "./timelines.vid"
+import * as pack from "./effects.vid"
+import eleven from "@elevenlabs/tts"  # future scoped package      # from npm registry
+import music from "@elevenlabs/music" # generative music
+use intro at [-] with { clip: main, headline: "Welcome" }
+```
+
+### Plugin Calls
+
+```vidscript
+import eleven from "/tts"
+
+[-] = audio eleven.tts("Welcome to SceneRok", voice: "Rachel")
+[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16")
+[-] = audio music("upbeat launch soundtrack", duration: 12, instrumental: true)
+[-] = audio xai.tts("Next line", voice: "eve")
+```
+
+Package-style plugin calls are supported inside time blocks. Use `video ...` for generated visual clips and `audio ...` for generated speech, music, and other generated audio.
+
+### Placeholders
+
+Templates use `{{name | default}}` for user-supplied values:
+```vidscript
+input hero = "{{hero_clip}}"
+[0.5s .. 3s] = text "{{headline | Hello}}", style: title
+```
+
+## Workflow
+
+1. **Understand the goal** — What video does the user want? (promo, testimonial, meme, etc.)
+2. **Plan the structure** — Time blocks, durations, inputs
+3. **Gather assets** — Video URLs or local paths
+4. **Compose VidScript** — Write the full script
+5. **Validate** — Run `scenerok validate script.vid`
+6. **Render** — Run `scenerok render script.vid --watch`
+7. **Deliver** — Share the download URL when complete
+
+## Best Practices
+
+- **Use dynamic timeblocks** — `[-]` auto-advances the cursor, reducing calculation errors
+- **Use `prev` for offsets** — `[prev + 0.5s .. prev + 2s]` for gaps between content
+- **Named arguments for clarity** — `hero.Trim(start: 0s, end: 5s)` over `hero.Trim(0s, 5s)`
+- Use 1080x1920 for vertical content (TikTok/Instagram)
+- Use 1920x1080 for horizontal content (YouTube)
+- Hook viewers in the first 3 seconds
+- Use high-contrast text on video backgrounds with `stroke` and `stroke_width`
+- Include a clear call-to-action
+- Test with `scenerok validate` before rendering
+- Each render costs 1 credit
+
+## CLI Commands
+
+```bash
+scenerok auth login              # Authenticate
+scenerok validate script.vid      # Validate a VidScript
+scenerok render script.vid --watch # Render a video
+scenerok status <render-id>       # Check status
+scenerok skills install <platform> # Install/update agent skill
+scenerok skills list               # List available skills
+scenerok secrets set KEY=VALUE    # Store API key for plugins
+```
+
+## Error Handling
+
+If a render fails:
+1. Check the error message with `scenerok status <id>`
+2. Common issues: missing assets (404 URLs), invalid file paths, syntax errors
+3. Fix the VidScript and re-render
+4. If credits are insufficient, the user needs to purchase more
+
+## Sample Video Types
+
+- **Product Promo** — Hero clip + headline + description + CTA + vignette filter
+- **Social Media Hook** — Fast cuts, bold text, speed adjustments
+- **Testimonial** — Speaker clip + quote text + sepia filter
+- **Meme Remix** — Reaction clip + top/bottom punchline overlays
+- **Title Sequence** — Background clip + glitch shader + bold typography
+
+Always ask clarifying questions about:
+- Target platform (TikTok, Instagram, YouTube, etc.)
+- Brand colors and fonts
+- Existing assets (video clips, logo, etc.)
+- Desired duration and style
+- Whether they want to start from a template or from scratch
+
+## Full Reference
+
+For exhaustive grammar documentation, visit:
+https://scenerok.com/docs/vidscript