@scenerok/sdk 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenerok/sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "TypeScript-first SceneRok authoring SDK — build IRTimeline for complex agent-authored scenes",
   "type": "module",
   "main": "./dist/index.js",

package/skills/scenerok/references/catalog-index.json

@@ -1,6 +1,6 @@
 {
   "schema": "https://scenerok.com/catalog-index/v1",
-  "generatedAt": "2026-10-06T08:56:17.740Z",
+  "generatedAt": "2026-10-06T17:39:55.472Z",
   "cdnBase": "https://assets-public.scenerok.com/catalog",
   "categories": [
     {

package/skills/scenerok/references/editing-actions.md

@@ -260,6 +260,18 @@ input b = "shot-b.mp4"
 output to "video.mp4", resolution: "1920x1080", fps: 24
 ```
 
+Timecode literals are `HH:MM:SS:FF@rate`, non-drop-frame (`;` is an error),
+FF below the rate, hours 0-23. Without `@rate` they use the literal output fps:
+
+```vidscript
+[00:00:01:12@24 .. 00:00:03:00@24] = text "1.5 s to 3 s"
+output to "video.mp4", resolution: "1920x1080", fps: 24
+```
+
+NTSC `fps:` values (23.976, 29.97, 47.952, 59.94, 119.88) are encoded at the
+exact `24000/1001` style rate, and block start/end times snap to whole frames
+of the output (`[0.1s .. 0.35s]` at 30 fps is frames 3 to 11).
+
 ### Transitions and handles
 
 Transitions come from `@scenerok/transitions` (full list in
@@ -295,6 +307,24 @@ input frames = "renders/shot.%04d.png", rate: 12, first: 1, count: 24
 `Trim`, `Speed`, and `Loop` work on it. For cloud renders the pattern must be
 an `https` URL pattern.
 
+### Mixed frame rates
+
+`rate:` on a plain video input says what frame rate the footage runs at, for a
+timeline at another rate. Each output frame shows the source frame its time falls
+in, so 23.976 footage in a 30 fps timeline repeats frames in a 2:3-like cadence
+and never skips one:
+
+```vidscript
+input clip = "clip.mp4", rate: 23.976
+[0s .. 4s] = clip.Trim(1s, 5s)
+output to "out.mp4", resolution: "1920x1080", fps: 30
+```
+
+Write it only when the footage rate differs from `fps`. It is an error on audio
+or a still image; `first:` and `count:` stay sequence-only. A probed rate is never
+applied for you: if the probe differs from the declared rate by more than 0.1%
+the compile warns and the declared rate wins. Audio is not conformed.
+
 ## Sound
 
 Every sound is an `audio` line with its own window, so J- and L-cuts need no
@@ -488,13 +518,25 @@ output to "master.mp4", resolution: "1920x1080", fps: 25, codec: "h264", bitrate
 `start_timecode` is `HH:MM:SS:FF` and its frame field must be below `fps`.
 `burn_in: "timecode"` draws the running timecode on the picture.
 
+### Offline media
+
+```vidscript
+input a = "shot-a.mp4"
+input b = "shot-b.mp4"   # not delivered yet
+[0s .. 4s] = a
+[4s .. 8s] = b
+output to "draft.mp4", resolution: "1920x1080", fps: 25, allow_offline: true
+```
+
+With `allow_offline: true`, an input whose file is missing at compile time becomes an offline clip (OTIO `MissingReference`): it keeps its place and source path, lasts the block or `Trim` length, and draws as a flat `#2b2b2b` slate labelled `MEDIA OFFLINE` and the input name. `Resize`, `x`/`y`, `opacity` and `animate:` still apply. Its sound is dropped with a warning, and a transition at its seam is an error. Without the option a missing local file is a compile error. Media that disappears only at render time still fails the render.
+
 ## What VidScript can't do yet
 
 Don't try to work around these. Tell the user when a request needs one.
 
 | Request | Today |
 | --- | --- |
-| Two aspect ratios from one script | One `output` per script; a second `output` line replaces the first. Write one script per format. |
+| Two aspect ratios from one script | Two `output` statements compile to two canvases, but only the local headless renderer renders both (one file per output). The render queue (web app, CLI, API) rejects a script with more than one `output` before billing, so write one script per format for a hosted render. |
 | Transparent video (alpha) | `alpha: true` is a compile error; renders are H.264 MP4. |
 | Multicam angle switching | No syntax. Cut between the angle clips with time blocks. |
 | Mixed frame rates | A timeline has one frame rate, the output `fps`. |

package/skills/scenerok/references/vidscript-guide.md

@@ -70,7 +70,7 @@ input frames = "shots/shot.%04d.png", rate: 12, first: 1, count: 24
 [0s .. 2s] = frames
 ```
 
-Place it by name like a video; `Trim`, `Speed`, and `Loop` work on it. `rate:`, `first:`, `count:` on a plain file are errors. On the render workers the pattern must be an `https` URL pattern (or a path on the worker).
+Place it by name like a video; `Trim`, `Speed`, and `Loop` work on it. `first:` and `count:` on a plain file are errors. `rate:` on a plain video file declares the footage's frame rate for a timeline at another rate (`input clip = "clip.mp4", rate: 23.976` in a 30 fps output; each output frame shows the source frame its time falls in). It is an error on audio or a still, never auto-applied from a probe, and a probed rate more than 0.1% off the declared one warns. On the render workers the pattern must be an `https` URL pattern (or a path on the worker).
 
 For ads based on a supplied URL, browser tools can capture real website visuals and save product images or logos when useful. Use screenshots sparingly: favor above-fold, cropped, or focused captures that remain legible at video size. Avoid full-page or long scrolling screenshots as backgrounds because their text will usually become unreadable.
 
@@ -114,6 +114,8 @@ output to "video.mp4", resolution: "1080x1920", fps: 30
 output to "reel.mp4", resolution: "720x1280", format: "mp4", codec: "h264", bitrate: "5M", background: "#0D0D0D"
 ```
 
+Several `output` statements make several canvases (`compileVidscript` returns one IR each in `irs`; `ir` is the first). Each output is the whole script lowered against its own `resolution`, `fps`, and `background`, so percent positions and `grid` areas resolve per canvas. Every output needs its own path (two with the same path is a compile error). Where it renders: the headless renderer (`renderVidscriptOutputsToMP4`, local scripts) writes one file per output. Where it errors: the render queue (the web app, the CLI, and the API) delivers one artifact per render, so a script with more than one `output` is rejected with `N outputs are rendered … only one output per render is supported by the render queue yet` before anything is billed. Use one `output` for a hosted render.
+
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `resolution` | string | `"1080x1920"` | Width×Height or single number |
@@ -124,6 +126,7 @@ output to "reel.mp4", resolution: "720x1280", format: "mp4", codec: "h264", bitr
 | `background` | string | `"#000000"` | Background color hex |
 | `start_timecode` | string | none | Timecode of the first frame, `"HH:MM:SS:FF"` (non-drop-frame; the frame field must be below `fps`). Written to the mp4's timecode track |
 | `burn_in` | string | none | `"timecode"` draws the running timecode (from `start_timecode`, else `00:00:00:00`) onto the picture |
+| `allow_offline` | boolean | `false` | `true` renders an input whose file is missing at compile time (media probing on) as a "MEDIA OFFLINE" slate: a flat `#2b2b2b` frame labelled with the input name, over the clip's block or `Trim` length. `Resize`, `x`/`y`, `opacity` and `animate:` still apply; its sound is dropped with a warning; a transition at its seam is an error. Without it a missing local file is a compile error. Media that goes missing only at render time still fails the render |
 | `alpha` | boolean | `false` | Needs `format: "mov", codec: "prores"` or `format: "webm", codec: "vp9"`. No render path delivers alpha yet (renders are H.264 mp4), so `alpha: true` is a compile error for now |
 
 ### Variable Assignment

package/skills/scenerok/references/vidscript-strict.md

@@ -237,7 +237,7 @@ input logo = "logo.png"
 - A placed value lasts its own length (trimmed range ÷ speed × loops). Make the window that long.
 - Put one video over another with `Overlay`, `Composite`, or `blend:`. Two plain clips in the same window have no defined order.
 - `Mask` on its own line after the clip is placed is a compile error.
-- Frame counts are written `48 frame` and use the output fps (30 if `output` has none).
+- Frame counts are written `48 frame` and use the output fps (30 if `output` has none). Timecodes are `01:00:02:12@24` (`@rate` optional; non-drop-frame only). Block times snap to the output frame grid; NTSC fps (23.976, 29.97) encodes at the exact rational rate.
 
 All editing actions (masks, speed ramps, ducking, LUTs, timecode): `editing-actions.md`.