Skip to content

The VS Code of video editing, built for agents.

TypeScript

Update scene and stage documentation, and adjust default camera settings

konstantin-paulus287473593651
diff --git a/docs/reference/jsx/scene.md b/docs/reference/jsx/scene.md
index 1235b501..292771a3 100644
--- a/docs/reference/jsx/scene.md
+++ b/docs/reference/jsx/scene.md
@@ -19,7 +19,7 @@ A scene is the **clipped, playable frame** a composition is made in, and the onl
| `name` | `string` | none | Human-readable node name; what labels the scene in the editor. Recommended. |
| `volume` | `number` | `0` | Decibels on the scene's own bus, which everything in it mixes into — the master fader. `0` = unity, negative attenuates (`-6` ≈ half as loud), `-Infinity` = silence. A clip's own `volume` composes with this one. |
| `active` | `boolean` | absent | Whether this is the scene the playhead, the timeline and `capture` operate on. |
-| `workarea` | `[in, out] \| null` | `null` | The stretch of the scene that plays and exports, in any [time format](./timing.md#time-formats). |
+| `workarea` | `[in, out] \| null` | `null` | The stretch of the scene that plays and exports, in any [time format](./timing.md#time-formats). Without one the whole scene plays and exports, first frame to last |
| `selected` | `boolean` | absent | Whether the editor has the scene selected. |
| `timeline` | `[zoom, x, y]` | absent | Where the scene's timeline is looking: `zoom` in pixels per second of timeline, horizontal scroll in seconds, vertical scroll in pixels. Absent means the default zoom, at the beginning. |
@@ -33,7 +33,7 @@ Two rules the runtime holds for `active`: **at most one element is active**, and
**Mark one scene `active` in every project you author.** Nothing activates on its own, and a project that opens with no active scene opens on an empty timeline: there is no playhead to scrub, `capture` has nothing pointed at it, and an export has no scene to render. One scene, one `active`; with several, the one the project should open on — pair it with the [`<stage>`](./stage.md) `camera` that frames it.
-`workarea` is the exception among them: it is carried by the source the way `active` is (the timeline's brackets have nowhere else to go), but it is read wherever the file is, so **what it says is what comes out of a render**. Playback loops within it, and an export is of it and nothing else.
+`workarea` is the exception among them: it is carried by the source the way `active` is (the timeline's brackets have nowhere else to go), but it is read wherever the file is, so **what it says is what comes out of a render**. Playback loops within it, and an export is of it and nothing else. It is not required: a scene without one is rendered whole, and that is the normal case.
```tsx
// Renders seconds 2–8 of the scene, and nothing else.
diff --git a/docs/reference/jsx/stage.md b/docs/reference/jsx/stage.md
index f69900b9..d5d9f9f9 100644
--- a/docs/reference/jsx/stage.md
+++ b/docs/reference/jsx/stage.md
@@ -22,9 +22,9 @@ The stage is a **singleton**: it is the canvas already on screen rather than som
| Prop | Type | Default | Meaning |
| ---- | ---- | ------- | ------- |
| `background` | `string` | `#161616` | Canvas color behind the scenes, any CSS color. Not part of a render: it is what surrounds the frame, not what is in it. |
-| `camera` | `[a, b, c, d, e, f]` | `[1, 0, 0, 1, 0, 0]` | The editor's viewport when the project is opened, as a 2D affine matrix in the order CSS `matrix()` and canvas `setTransform` take: `a`/`d` scale, `b`/`c` skew, `e`/`f` translate. |
+| `camera` | `[a, b, c, d, e, f]` | `[0.3, 0, 0, 0.3, 85, 150]` | The editor's viewport when the project is opened, as a 2D affine matrix in the order CSS `matrix()` and canvas `setTransform` take: `a`/`d` scale, `b`/`c` skew, `e`/`f` translate. |
-Both are editor state rather than composition: nothing rendered or exported depends on either, but the source is the document, so a panned canvas has nowhere else to be written back to. A project that never says where to look opens at the origin, at 100% — the frame's top-left corner in the canvas's top-left corner, most of it off screen. **Write a camera into every project you author**, so the first open is already framed on the composition.
+Both are editor state rather than composition: nothing rendered or exported depends on either, but the source is the document, so a panned canvas has nowhere else to be written back to. A project that never says where to look opens framed on a 1920×1080 frame at the origin, roughly centered in a default window — so a single landscape scene at `x={0} y={0}` needs no camera. Write one when the composition is anything else: a portrait or unusual format, a scene placed away from the origin, or several scenes side by side.
The matrix that frames a scene sitting at the origin is `[s, 0, 0, s, x, y]`: `s` scales the frame to fit the canvas — roughly 750×620 CSS pixels in a default window — and `x`/`y` inset it from the corner. A landscape frame around 580 px wide, a portrait one around 480 px tall, leaves room for the scene's label above it and the floating toolbar below:
diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.ts
index 3b8374af..ec8d325d 100644
--- a/packages/jsx/src/types.ts
+++ b/packages/jsx/src/types.ts
@@ -405,16 +405,17 @@ export type StageProps = {
/** Canvas color, any CSS color. */
background?: string;
/**
- * The editor's viewport when the project is opened: `[1, 0, 0, 1, 0, 0]` is
+ * The editor's viewport when the project is opened; `[1, 0, 0, 1, 0, 0]` is
* the origin at 100%. Not part of the composition — nothing rendered or
- * exported depends on it — so a project that never says where to look opens
- * at the origin, with most of the frame off screen.
+ * exported depends on it. A project that never says where to look opens on
+ * `[0.3, 0, 0, 0.3, 85, 150]`, which frames a 1920×1080 scene at the origin,
+ * so such a project needs no camera.
*
- * Give every authored project one, so it opens framed on its composition:
- * `[s, 0, 0, s, x, y]` for a scene at the origin, `s` sized to fit the frame
- * in roughly 580×330 screen pixels — `[0.3, 0, 0, 0.3, 85, 150]` for
- * 1920×1080, `[0.6, 0, 0, 0.6, 85, 150]` for 960×540. The first pan or zoom
- * overwrites it, so the exact numbers do not matter.
+ * Give a project one when its composition is anything else, so it still
+ * opens framed: `[s, 0, 0, s, x, y]` for a scene at the origin, `s` sized to
+ * fit the frame in roughly 580×330 screen pixels — `[0.25, 0, 0, 0.25, 235,
+ * 70]` for 1080×1920, `[0.6, 0, 0, 0.6, 85, 150]` for 960×540. The first pan
+ * or zoom overwrites it, so the exact numbers do not matter.
*/
camera?: CameraMatrix;
children?: SolidJSX.Element;
diff --git a/packages/runtime/src/traits/world.ts b/packages/runtime/src/traits/world.ts
index 46705bc7..e5523e6f 100644
--- a/packages/runtime/src/traits/world.ts
+++ b/packages/runtime/src/traits/world.ts
@@ -23,7 +23,7 @@ export const Root = trait(() => null as Entity | null);
* stage. The render system multiplies this by RenderSurface.resolution
* to derive the canvas transform.
*/
-export const Camera = trait({ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+export const Camera = trait({ a: 0.3, b: 0, c: 0, d: 0.3, e: 85, f: 150 });
export type Camera2D = { a: number; b: number; c: number; d: number; e: number; f: number };