The VS Code of video editing, built for agents.
TypeScript
Update audio and video documentation to reflect volume changes in decibels
konstantin-paulus8fcf8884b896
diff --git a/apps/cli/reference/jsx/README.md b/apps/cli/reference/jsx/README.mdindex efa27864..99316488 100644--- a/apps/cli/reference/jsx/README.md+++ b/apps/cli/reference/jsx/README.md@@ -95,7 +95,7 @@ export default function Project() {src="https://my.videoarchive.com/audio/video-xyz.wav"sourceIn={6}sourceOut={16}- volume={0.5}+ volume={-6}/><captions />diff --git a/apps/cli/reference/jsx/audio.md b/apps/cli/reference/jsx/audio.mdindex cffd686b..d738fa5d 100644--- a/apps/cli/reference/jsx/audio.md+++ b/apps/cli/reference/jsx/audio.md@@ -3,7 +3,7 @@An audio clip: no visual output, no spatial props; carries volume. When timing is omitted, the node fits its natural duration (see [timing.md](./timing.md)).```tsx-<audio src="https://my.videoarchive.com/audio/clip.wav" start={2.2} sourceOut={16} volume={0.5} />+<audio src="https://my.videoarchive.com/audio/clip.wav" start={2.2} sourceOut={16} volume={-6} />```## Props@@ -13,6 +13,6 @@ An audio clip: no visual output, no spatial props; carries volume. When timing i| `src` | `string \| AssetRef` | **required** | See [media.md](./media.md). || `name` | `string` | none | Human-readable node name. || `start`, `end`, `sourceIn`, `sourceOut` | `Time` | see [timing.md](./timing.md) | Temporal placement. |-| `volume` | `Animatable<number>` | `1` | `0`-`1`; `1` = unity gain. |+| `volume` | `Animatable<number>` | `0` | Decibels: `0` = unity, negative attenuates (`-6` ≈ half as loud), `-Infinity` = silence. Not linear. || `muted` | `boolean` | `false` | Excludes the node's audio from the mix; independent of `volume`. || `syncTo` | `string` | none | Key of another element carrying audio; derives `start` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `start`. |diff --git a/apps/cli/reference/jsx/video.md b/apps/cli/reference/jsx/video.mdindex 65da57e9..2b7e26f9 100644--- a/apps/cli/reference/jsx/video.md+++ b/apps/cli/reference/jsx/video.md@@ -3,7 +3,7 @@A video clip. `src` resolves to a video asset (see [media.md](./media.md)); when timing is omitted, the node fits its natural duration (see [timing.md](./timing.md)).```tsx-<video src="/Movies/main.mp4" start={0} sourceIn={1} sourceOut={13} volume={0.8} />+<video src="/Movies/main.mp4" start={0} sourceIn={1} sourceOut={13} volume={-3} />```## Props@@ -14,7 +14,7 @@ All [common props](./elements.md#common-props), plus:| ---- | ---- | ------- | ------- || `src` | `string \| AssetRef` | **required** | See [media.md](./media.md). || `objectFit` | `"cover" \| "contain" \| "fill"` | `"cover"` | How the source maps into the box. |-| `volume` | `Animatable<number>` | `1` | `0`-`1`; `1` = unity gain. |+| `volume` | `Animatable<number>` | `0` | Decibels: `0` = unity, negative attenuates (`-6` ≈ half as loud), `-Infinity` = silence. Not linear. || `muted` | `boolean` | `false` | Excludes the node's audio from the mix; independent of `volume`. || `syncTo` | `string` | none | Key of another element carrying audio; derives `start` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `start`. |diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.tsindex ad028c98..b5395f8a 100644--- a/apps/cli/src/index.ts+++ b/apps/cli/src/index.ts@@ -1310,7 +1310,7 @@ node.command("ls").aliases(["list", "get"]).description(- `Print raw entity records, exactly as persisted: every component the entity carries, keyed by component name (Name, Size, Position, Paint, Trim, ChildOf, ...). With no ids, lists the top-level nodes. Values are raw engine units: times are frames at 30 fps, colors packed 0xRRGGBB, volume in dB.`,+ `Print raw entity records, exactly as persisted: every component the entity carries, keyed by component name (Name, Size, Position, Paint, Trim, ChildOf, ...). With no ids, lists the top-level nodes. Values are raw engine units: times are frames at 30 fps, colors packed 0xRRGGBB, volume in dB (0 = unity).`,).argument("[ids...]", "entity ids to list (optional)").action((ids: string[]) => listNodes(ids));diff --git a/apps/web/src/context/editor-api/node.ts b/apps/web/src/context/editor-api/node.tsindex b730b527..b56473f3 100644--- a/apps/web/src/context/editor-api/node.ts+++ b/apps/web/src/context/editor-api/node.ts@@ -148,7 +148,7 @@ function describeEntity(world: EngineWorld, eid: number): string {}if (hasComponent(world, eid, c.Volume)) {const db = c.Volume[eid] ?? 0;- parts.push(`volume: ${db === -Infinity ? 0 : Math.round(10 ** (db / 20) * 100) / 100}`);+ parts.push(`volume: ${db === -Infinity ? "-inf" : Math.round(db * 10) / 10} dB`);}if (hasComponent(world, eid, c.AssetId)) parts.push(`asset: ${c.AssetId[eid]}`);if (hasComponent(world, eid, c.TextStyle)) {diff --git a/apps/web/src/utils/jsx.ts b/apps/web/src/utils/jsx.tsindex 4b780d97..c80c3abf 100644--- a/apps/web/src/utils/jsx.ts+++ b/apps/web/src/utils/jsx.ts@@ -639,22 +639,18 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {case "volume": {if (Array.isArray(value)) {const keyframes = parseKeyframes(name, value, (v) => {- assert(typeof v === "number", "`volume` must be a number" + `, value: ${v}`);- assert(v >= 0, "`volume` must be >= 0");+ assert(typeof v === "number", "`volume` must be a number (dB)" + `, value: ${v}`);// Keyframed silence floors at -60 dB so segments toward it// interpolate over finite values.- return Math.max(v <= 0 ? -Infinity : 20 * Math.log10(v), -60);+ return Math.max(v, -60);});setComponent(world, eid, c.Volume, keyframes[0].value);setKeyframeTrack(world, eid, "volume", keyframes);break;}setKeyframeTrack(world, eid, "volume", []);- assert(typeof value === "number", "`volume` must be a number" + `, value: ${value}`);- assert(value >= 0, "`volume` must be >= 0");- // Convert linear volume to decibels- const db = value <= 0 ? -Infinity : 20 * Math.log10(value);- setComponent(world, eid, c.Volume, db);+ assert(typeof value === "number", "`volume` must be a number (dB)" + `, value: ${value}`);+ setComponent(world, eid, c.Volume, value);break;} case "muted": {assert(typeof value === "boolean", "`muted` must be a boolean" + `, value: ${value}`);diff --git a/docs/composition.md b/docs/composition.mdindex 1f399945..c4a74223 100644--- a/docs/composition.md+++ b/docs/composition.md@@ -68,9 +68,9 @@ Animatable props also take a keyframe list — see [Animation](#animation).- **`<scene>`**: `key`, `width`, `height` (all required), `name`, `fill`. No timing or transform props.- **`<rect>` / `<group>`**: `fill` (any CSS color; alpha is ignored, use `opacity`).-- **`<video>`**: `src` (required), `objectFit` (`"cover"` | `"contain"` | `"fill"`, default `"cover"`), `volume` (`0`–`1`), `muted`, `syncTo` (see [Audio sync](#audio-sync)).+- **`<video>`**: `src` (required), `objectFit` (`"cover"` | `"contain"` | `"fill"`, default `"cover"`), `volume` (dB; `0` = unity, negative attenuates), `muted`, `syncTo` (see [Audio sync](#audio-sync)).- **`<image>`**: `src` (required), `objectFit` (default `"contain"`).-- **`<audio>`**: `src` (required), `volume`, `muted`, `syncTo`, timing props.+- **`<audio>`**: `src` (required), `volume` (dB; `0` = unity, negative attenuates), `muted`, `syncTo`, timing props.- **`<text>`**: string children (required), `fontFamily` (see `dapi fonts`), `fontSize`, `fontWeight`, `fontStyle`, `fill`, `textAlign`, `textBaseline`.These same props are what `dapi node patch` assigns on existing nodes.diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.tsindex 0010f563..bf5a6325 100644--- a/packages/jsx/src/types.ts+++ b/packages/jsx/src/types.ts@@ -126,7 +126,7 @@ export type PatchProps = {src?: string | AssetRef;/** How the source maps into the box. Default "cover" on `<video>`, "contain" on `<image>`. */objectFit?: Fit;- /** 0–1; 1 = unity gain. Animatable. */+ /** Decibels: 0 = unity gain, negative attenuates (-6 ≈ half as loud), -Infinity = silence. Use `muted` to silence. Animatable. */volume?: Animatable<number>;/** Excludes the node's audio from the mix; independent of `volume`. */muted?: boolean;