Skip to content

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.md
index 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.md
index 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.md
index 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.ts
index 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.ts
index 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.ts
index 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.md
index 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.ts
index 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;