Skip to content

The VS Code of video editing, built for agents.

TypeScript

Enhance `<Captions />` component with `verticalAlign` property and update related functionality

konstantin-paulus7180de47ae99
diff --git a/apps/cli/reference/jsx/captions.md b/apps/cli/reference/jsx/captions.md
index 55e6d5a3..e0f2b291 100644
--- a/apps/cli/reference/jsx/captions.md
+++ b/apps/cli/reference/jsx/captions.md
@@ -3,7 +3,7 @@
`<Captions />` inside a scene transcribes that scene's audio into a caption node: a styled, timed transcript, produced on import. To caption an already-open scene, insert one with [`dapi node insert`](../node/insert.md).
```tsx
-<Captions preset="spotlight" colors={["#FF0055"]} />
+<Captions preset="spotlight" colors={["#FF0055"]} verticalAlign="bottom" />
```
Transcription is **asynchronous and non-blocking**: the caption node is inserted at commit and its transcript attaches once ready. Because it reads the scene's audio, it runs **after** any generated assets in the scene have landed and after [audio sync](./audio-sync.md) has resolved; captioning a generated `voice`/`audio` track transcribes the finished audio at its final placement. The scene must contain an unmuted audio or video source; otherwise the caption node is left empty.
@@ -16,6 +16,10 @@ Transcripts are **cached**: every transcript asset records a fingerprint of the
| ---- | ---- | ------- | ------- |
| `preset` | see below | `"classic"` | Caption style preset. |
| `colors` | `string[]` | preset defaults | Fills the preset's color slots in order; any CSS color, alpha ignored. Ignored by presets without slots. |
+| `verticalAlign` | `"top" \| "center" \| "bottom"` | preset default | Vertical placement of the caption block: anchored to the top or bottom safe margin (100 px), or centered. Horizontal placement stays with the preset. |
+| `offsetX`, `offsetY` | `Animatable<number>` | `0` | Render-time nudge in px on top of the preset placement; subpixel values are kept. A slide animation drives the same channel and wins while it plays. |
+
+The preset positions the caption block; `verticalAlign` overrides only its vertical anchor (`whisper` and `cascade` default to `bottom`, all other presets to `center`), and `offsetX`/`offsetY` nudge the drawn result from there.
## Presets
diff --git a/apps/web/src/components/engine/api/observers.ts b/apps/web/src/components/engine/api/observers.ts
index 77965a4d..9f584a0f 100644
--- a/apps/web/src/components/engine/api/observers.ts
+++ b/apps/web/src/components/engine/api/observers.ts
@@ -111,9 +111,10 @@ export function observeWorld(world: EngineWorld) {
utils.persistEntity(world, eid);
});
- observe(world, "set", c.Caption, (eid, { type, colors }) => {
+ observe(world, "set", c.Caption, (eid, { type, colors, verticalAlign }) => {
c.Caption.type[eid] = type ?? c.Caption.type[eid] ?? CaptionType.CLASSIC;
c.Caption.colors[eid] = colors ?? c.Caption.colors[eid] ?? [0xFFFFFF];
+ c.Caption.verticalAlign[eid] = verticalAlign ?? c.Caption.verticalAlign[eid];
utils.persistEntity(world, eid);
});
diff --git a/apps/web/src/components/engine/api/serialize.ts b/apps/web/src/components/engine/api/serialize.ts
index 319244f0..9cb7de03 100644
--- a/apps/web/src/components/engine/api/serialize.ts
+++ b/apps/web/src/components/engine/api/serialize.ts
@@ -222,6 +222,7 @@ export function serializeEntity(world: EngineWorld, eid: number): DBEntity {
record.Caption = {
type: c.Caption.type[eid],
colors: c.Caption.colors[eid]?.map(v => v),
+ verticalAlign: c.Caption.verticalAlign[eid],
};
}
if (hasComponent(world, eid, c.Chars)) {
diff --git a/apps/web/src/components/engine/components/components.ts b/apps/web/src/components/engine/components/components.ts
index be31247e..e1b6fae4 100644
--- a/apps/web/src/components/engine/components/components.ts
+++ b/apps/web/src/components/engine/components/components.ts
@@ -69,6 +69,7 @@ export const Stroke = {};
export const Caption = {
type: [] as number[], // CaptionType enum index,
colors: [] as number[][],
+ verticalAlign: [] as (number | undefined)[], // CaptionAlign enum index; unset = the preset's default
};
export const Name = [] as string[];
diff --git a/apps/web/src/components/engine/components/constants.ts b/apps/web/src/components/engine/components/constants.ts
index 281c38fc..54147082 100644
--- a/apps/web/src/components/engine/components/constants.ts
+++ b/apps/web/src/components/engine/components/constants.ts
@@ -151,6 +151,12 @@ export enum CaptionType {
STARK,
}
+export enum CaptionAlign {
+ TOP,
+ CENTER,
+ BOTTOM,
+}
+
export enum ToolType {
MOVE,
HAND,
diff --git a/apps/web/src/components/engine/decoders/caption/cascade.ts b/apps/web/src/components/engine/decoders/caption/cascade.ts
index 658a147c..d4d86122 100644
--- a/apps/web/src/components/engine/decoders/caption/cascade.ts
+++ b/apps/web/src/components/engine/decoders/caption/cascade.ts
@@ -2,14 +2,14 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
+import { CaptionAlign, CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
import { renderText } from '../../utils/text';
import { loadWebFont } from '../../font/utils';
import { groupBy, findActiveGroup, resolveTranscript } from './utils';
-import { getParentEntity, createEntity } from '../../api';
+import { placeCaption } from './position';
+import { createEntity } from '../../api';
import { appendChild } from '../../api/hierarchy';
import { setComponent } from '../../api/events';
-import { resizeEntity } from '../../api/resize';
import type { EngineWorld } from '../../api/world';
import type { Asset } from '../../db';
@@ -38,15 +38,14 @@ export class CascadeCaptionDecoder implements CaptionDecoder {
this.ready = true;
}
+ public reposition(world: EngineWorld, eid: number): boolean {
+ return placeCaption(world, eid, { width: WIDTH, height: HEIGHT, x: 100, defaultAlign: CaptionAlign.BOTTOM });
+ }
+
public applyStyles(world: EngineWorld, eid: number): void {
const c = world.components;
- const parentEid = getParentEntity(world, eid);
- if (parentEid === null) return;
- const parentHeight = c.Computed.height[parentEid];
-
- resizeEntity(world, eid, { width: WIDTH, height: HEIGHT });
- setComponent(world, eid, c.Position, { x: 100, y: parentHeight - HEIGHT - 50 });
+ if (!this.reposition(world, eid)) return;
setComponent(world, eid, c.TextStyle, {
fontFamily: 'Inter',
fontWeight: '300',
diff --git a/apps/web/src/components/engine/decoders/caption/classic.ts b/apps/web/src/components/engine/decoders/caption/classic.ts
index 16522683..8cdc833e 100644
--- a/apps/web/src/components/engine/decoders/caption/classic.ts
+++ b/apps/web/src/components/engine/decoders/caption/classic.ts
@@ -2,14 +2,14 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
+import { CaptionAlign, CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
import { renderText } from '../../utils/text';
import { loadWebFont } from '../../font/utils';
import { groupBy, findActiveGroup, resolveTranscript } from './utils';
-import { getParentEntity, createEntity } from '../../api';
+import { placeCaption } from './position';
+import { createEntity } from '../../api';
import { appendChild } from '../../api/hierarchy';
import { addComponent, setComponent } from '../../api/events';
-import { resizeEntity } from '../../api/resize';
import type { EngineWorld } from '../../api/world';
import type { Asset } from '../../db';
@@ -38,24 +38,18 @@ export class ClassicCaptionDecoder implements CaptionDecoder {
this.ready = true;
}
- public applyStyles(world: EngineWorld, eid: number): void {
- const c = world.components;
-
- const parentEid = getParentEntity(world, eid);
- if (parentEid === null) return;
-
- const parentWidth = c.Computed.width[parentEid];
- const parentHeight = c.Computed.height[parentEid];
-
- resizeEntity(world, eid, {
+ public reposition(world: EngineWorld, eid: number): boolean {
+ return placeCaption(world, eid, {
width: CLASSIC_PRESET_WIDTH,
height: CLASSIC_PRESET_HEIGHT,
+ defaultAlign: CaptionAlign.CENTER,
});
+ }
- setComponent(world, eid, c.Position, {
- x: (parentWidth - CLASSIC_PRESET_WIDTH) / 2,
- y: (parentHeight - CLASSIC_PRESET_HEIGHT) / 2,
- });
+ public applyStyles(world: EngineWorld, eid: number): void {
+ const c = world.components;
+
+ if (!this.reposition(world, eid)) return;
setComponent(world, eid, c.TextStyle, {
fontFamily: 'Urbanist',
diff --git a/apps/web/src/components/engine/decoders/caption/guinea.ts b/apps/web/src/components/engine/decoders/caption/guinea.ts
index b0180da1..27fe682d 100644
--- a/apps/web/src/components/engine/decoders/caption/guinea.ts
+++ b/apps/web/src/components/engine/decoders/caption/guinea.ts
@@ -2,14 +2,14 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
+import { CaptionAlign, CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
import { renderText } from '../../utils/text';
import { loadWebFont } from '../../font/utils';
import { groupBy, findActiveGroup, splitSequence, clearTextRanges, resolveTranscript } from './utils';
-import { getParentEntity, createEntity } from '../../api';
+import { placeCaption } from './position';
+import { createEntity } from '../../api';
import { appendChild } from '../../api/hierarchy';
import { setComponent } from '../../api/events';
-import { resizeEntity } from '../../api/resize';
import type { EngineWorld } from '../../api/world';
import type { Asset } from '../../db';
@@ -47,16 +47,14 @@ export class GuineaCaptionDecoder implements CaptionDecoder {
this.ready = true;
}
+ public reposition(world: EngineWorld, eid: number): boolean {
+ return placeCaption(world, eid, { width: WIDTH, height: HEIGHT, defaultAlign: CaptionAlign.CENTER });
+ }
+
public applyStyles(world: EngineWorld, eid: number): void {
const c = world.components;
- const parentEid = getParentEntity(world, eid);
- if (parentEid === null) return;
- const parentWidth = c.Computed.width[parentEid];
- const parentHeight = c.Computed.height[parentEid];
-
- resizeEntity(world, eid, { width: WIDTH, height: HEIGHT });
- setComponent(world, eid, c.Position, { x: (parentWidth - WIDTH) / 2, y: (parentHeight - HEIGHT) / 2 });
+ if (!this.reposition(world, eid)) return;
setComponent(world, eid, c.TextStyle, {
fontFamily: 'The Bold Font',
fontWeight: '500',
diff --git a/apps/web/src/components/engine/decoders/caption/paper.ts b/apps/web/src/components/engine/decoders/caption/paper.ts
index 025b52f4..7d050f92 100644
--- a/apps/web/src/components/engine/decoders/caption/paper.ts
+++ b/apps/web/src/components/engine/decoders/caption/paper.ts
@@ -2,14 +2,14 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
+import { CaptionAlign, CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
import { renderText } from '../../utils/text';
import { loadWebFont } from '../../font/utils';
import { groupBy, findActiveGroup, splitSequence, clearTextRanges, resolveTranscript } from './utils';
-import { getParentEntity, createEntity } from '../../api';
+import { placeCaption } from './position';
+import { createEntity } from '../../api';
import { appendChild } from '../../api/hierarchy';
import { setComponent } from '../../api/events';
-import { resizeEntity } from '../../api/resize';
import type { EngineWorld } from '../../api/world';
import type { Asset } from '../../db';
@@ -39,23 +39,14 @@ export class PaperCaptionDecoder implements CaptionDecoder {
this.ready = true;
}
+ public reposition(world: EngineWorld, eid: number): boolean {
+ return placeCaption(world, eid, { width: WIDTH, height: HEIGHT, defaultAlign: CaptionAlign.CENTER });
+ }
+
public applyStyles(world: EngineWorld, eid: number): void {
const c = world.components;
- const parentEid = getParentEntity(world, eid);
- if (parentEid === null) return;
- const parentWidth = c.Computed.width[parentEid];
- const parentHeight = c.Computed.height[parentEid];
-
- resizeEntity(world, eid, {
- width: WIDTH,
- height: HEIGHT,
- });
-
- setComponent(world, eid, c.Position, {
- x: (parentWidth - WIDTH) / 2,
- y: (parentHeight - HEIGHT) / 2,
- });
+ if (!this.reposition(world, eid)) return;
setComponent(world, eid, c.TextStyle, {
fontFamily: 'Montserrat',
diff --git a/apps/web/src/components/engine/decoders/caption/position.ts b/apps/web/src/components/engine/decoders/caption/position.ts
new file mode 100644
index 00000000..40a3214b
--- /dev/null
+++ b/apps/web/src/components/engine/decoders/caption/position.ts
@@ -0,0 +1,48 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import { CaptionAlign } from '../../components';
+import { getParentEntity } from '../../api';
+import { setComponent } from '../../api/events';
+import { resizeEntity } from '../../api/resize';
+
+import type { EngineWorld } from '../../api/world';
+
+// Margin between the caption box and the parent edge for top/bottom alignment.
+export const CAPTION_MARGIN = 100;
+
+/**
+ * Sizes the caption box and places it within its parent. Horizontal placement
+ * belongs to the preset (centered unless a fixed `x` is given); vertical
+ * placement follows the entity's `Caption.verticalAlign`, falling back to the
+ * preset's default. Returns false when the entity has no parent to place
+ * against.
+ */
+export function placeCaption(
+ world: EngineWorld,
+ eid: number,
+ preset: { width: number; height: number; x?: number; defaultAlign: CaptionAlign },
+): boolean {
+ const c = world.components;
+
+ const parentEid = getParentEntity(world, eid);
+ if (parentEid === null) return false;
+ const parentWidth = c.Computed.width[parentEid];
+ const parentHeight = c.Computed.height[parentEid];
+
+ resizeEntity(world, eid, { width: preset.width, height: preset.height });
+
+ const align = c.Caption.verticalAlign[eid] ?? preset.defaultAlign;
+ const y = align === CaptionAlign.TOP
+ ? CAPTION_MARGIN
+ : align === CaptionAlign.BOTTOM
+ ? parentHeight - preset.height - CAPTION_MARGIN
+ : (parentHeight - preset.height) / 2;
+
+ setComponent(world, eid, c.Position, {
+ x: preset.x ?? (parentWidth - preset.width) / 2,
+ y,
+ });
+ return true;
+}
diff --git a/apps/web/src/components/engine/decoders/caption/spotlight.ts b/apps/web/src/components/engine/decoders/caption/spotlight.ts
index 94b98212..5bb5d5d0 100644
--- a/apps/web/src/components/engine/decoders/caption/spotlight.ts
+++ b/apps/web/src/components/engine/decoders/caption/spotlight.ts
@@ -2,14 +2,14 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
+import { CaptionAlign, CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
import { renderText } from '../../utils/text';
import { loadWebFont } from '../../font/utils';
import { groupBy, findActiveGroup, clearTextRanges, resolveTranscript } from './utils';
-import { getParentEntity, createEntity } from '../../api';
+import { placeCaption } from './position';
+import { createEntity } from '../../api';
import { appendChild } from '../../api/hierarchy';
import { setComponent } from '../../api/events';
-import { resizeEntity } from '../../api/resize';
import type { EngineWorld } from '../../api/world';
import type { Asset } from '../../db';
@@ -42,23 +42,14 @@ export class SpotlightCaptionDecoder implements CaptionDecoder {
this.ready = true;
}
+ public reposition(world: EngineWorld, eid: number): boolean {
+ return placeCaption(world, eid, { width: WIDTH, height: HEIGHT, defaultAlign: CaptionAlign.CENTER });
+ }
+
public applyStyles(world: EngineWorld, eid: number): void {
const c = world.components;
- const parentEid = getParentEntity(world, eid);
- if (parentEid === null) return;
- const parentWidth = c.Computed.width[parentEid];
- const parentHeight = c.Computed.height[parentEid];
-
- resizeEntity(world, eid, {
- width: WIDTH,
- height: HEIGHT,
- });
-
- setComponent(world, eid, c.Position, {
- x: (parentWidth - WIDTH) / 2,
- y: (parentHeight - HEIGHT) / 2,
- });
+ if (!this.reposition(world, eid)) return;
setComponent(world, eid, c.TextStyle, {
fontFamily: 'The Bold Font',
diff --git a/apps/web/src/components/engine/decoders/caption/stark.ts b/apps/web/src/components/engine/decoders/caption/stark.ts
index 7c8f315f..43a427cc 100644
--- a/apps/web/src/components/engine/decoders/caption/stark.ts
+++ b/apps/web/src/components/engine/decoders/caption/stark.ts
@@ -2,14 +2,14 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { BlendMode, CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
+import { BlendMode, CaptionAlign, CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
import { renderText } from '../../utils/text';
import { loadWebFont } from '../../font/utils';
import { groupBy, findActiveGroup, resolveTranscript } from './utils';
-import { getParentEntity, createEntity } from '../../api';
+import { placeCaption } from './position';
+import { createEntity } from '../../api';
import { appendChild } from '../../api/hierarchy';
import { setComponent } from '../../api/events';
-import { resizeEntity } from '../../api/resize';
import type { EngineWorld } from '../../api/world';
import type { Asset } from '../../db';
@@ -38,23 +38,14 @@ export class StarkCaptionDecoder implements CaptionDecoder {
this.ready = true;
}
+ public reposition(world: EngineWorld, eid: number): boolean {
+ return placeCaption(world, eid, { width: WIDTH, height: HEIGHT, defaultAlign: CaptionAlign.CENTER });
+ }
+
public applyStyles(world: EngineWorld, eid: number): void {
const c = world.components;
- const parentEid = getParentEntity(world, eid);
- if (parentEid === null) return;
- const parentWidth = c.Computed.width[parentEid];
- const parentHeight = c.Computed.height[parentEid];
-
- resizeEntity(world, eid, {
- width: WIDTH,
- height: HEIGHT,
- });
-
- setComponent(world, eid, c.Position, {
- x: (parentWidth - WIDTH) / 2,
- y: (parentHeight - HEIGHT) / 2,
- });
+ if (!this.reposition(world, eid)) return;
setComponent(world, eid, c.TextStyle, {
fontFamily: 'Figtree',
diff --git a/apps/web/src/components/engine/decoders/caption/types.ts b/apps/web/src/components/engine/decoders/caption/types.ts
index 9e9c4e0a..25a3467d 100644
--- a/apps/web/src/components/engine/decoders/caption/types.ts
+++ b/apps/web/src/components/engine/decoders/caption/types.ts
@@ -11,6 +11,7 @@ export interface CaptionDecoder {
groups: WordGroup[];
ready: boolean;
applyStyles(world: EngineWorld, eid: number): void;
+ reposition(world: EngineWorld, eid: number): boolean;
seekTo(world: EngineWorld, eid: number, relativeTime: number): void;
draw(world: EngineWorld, eid: number): void;
dispose(): void;
diff --git a/apps/web/src/components/engine/decoders/caption/whisper.ts b/apps/web/src/components/engine/decoders/caption/whisper.ts
index 1da584c5..6165d0ca 100644
--- a/apps/web/src/components/engine/decoders/caption/whisper.ts
+++ b/apps/web/src/components/engine/decoders/caption/whisper.ts
@@ -2,14 +2,14 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
+import { CaptionAlign, CaptionType, PaintType, FontStyle, TextAlign, TextBaseline, TextCase } from '../../components';
import { renderText } from '../../utils/text';
import { loadWebFont } from '../../font/utils';
import { groupBy, findActiveGroup, resolveTranscript } from './utils';
-import { getParentEntity, createEntity } from '../../api';
+import { placeCaption } from './position';
+import { createEntity } from '../../api';
import { appendChild } from '../../api/hierarchy';
import { setComponent } from '../../api/events';
-import { resizeEntity } from '../../api/resize';
import type { EngineWorld } from '../../api/world';
import type { Asset } from '../../db';
@@ -39,23 +39,14 @@ export class WhisperCaptionDecoder implements CaptionDecoder {
this.ready = true;
}
+ public reposition(world: EngineWorld, eid: number): boolean {
+ return placeCaption(world, eid, { width: WIDTH, height: HEIGHT, defaultAlign: CaptionAlign.BOTTOM });
+ }
+
public applyStyles(world: EngineWorld, eid: number): void {
const c = world.components;
- const parentEid = getParentEntity(world, eid);
- if (parentEid === null) return;
- const parentWidth = c.Computed.width[parentEid];
- const parentHeight = c.Computed.height[parentEid];
-
- resizeEntity(world, eid, {
- width: WIDTH,
- height: HEIGHT,
- });
-
- setComponent(world, eid, c.Position, {
- x: (parentWidth - WIDTH) / 2,
- y: parentHeight - HEIGHT - 100,
- });
+ if (!this.reposition(world, eid)) return;
setComponent(world, eid, c.TextStyle, {
fontFamily: 'Montserrat',
diff --git a/apps/web/src/components/engine/types/db.ts b/apps/web/src/components/engine/types/db.ts
index f87aed6a..21e5d06a 100644
--- a/apps/web/src/components/engine/types/db.ts
+++ b/apps/web/src/components/engine/types/db.ts
@@ -18,6 +18,7 @@ export interface DBEntity {
Caption?: {
type?: number;
colors?: number[];
+ verticalAlign?: number;
};
IsMask?: {};
Shadow?: {};
diff --git a/apps/web/src/context/editor-api/node.ts b/apps/web/src/context/editor-api/node.ts
index d83434bf..e8e13016 100644
--- a/apps/web/src/context/editor-api/node.ts
+++ b/apps/web/src/context/editor-api/node.ts
@@ -18,7 +18,7 @@ import {
serializeEntity,
} from "@/components/engine";
import { ChildOf } from "@/components/engine/components";
-import { ANIMATION_TYPE_MAP, WorldDocument } from "@/utils/jsx";
+import { ANIMATION_TYPE_MAP, CAPTION_ALIGN_MAP, WorldDocument } from "@/utils/jsx";
import { entityType } from "./selection";
import type { EngineWorld, Engine } from "@/components/engine";
@@ -44,6 +44,11 @@ const ANIMATION_TYPE_NAMES: Record<number, string> = Object.fromEntries(
Object.entries(ANIMATION_TYPE_MAP).map(([name, type]) => [type, name]),
);
+// The JSX caption alignment names, keyed by engine enum.
+const CAPTION_ALIGN_NAMES: Record<number, string> = Object.fromEntries(
+ Object.entries(CAPTION_ALIGN_MAP).map(([name, align]) => [align, name]),
+);
+
// Scenes are nodes too, so node ops accept them alongside geometry, groups,
// and adjustment layers.
export function isNode(world: EngineWorld, eid: number): boolean {
@@ -139,6 +144,10 @@ function describeEntity(world: EngineWorld, eid: number): string {
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.Caption)) {
+ const align = c.Caption.verticalAlign[eid];
+ if (align !== undefined) parts.push(`verticalAlign: ${CAPTION_ALIGN_NAMES[align]}`);
+ }
if (hasComponent(world, eid, c.TextStyle)) {
const family = c.TextStyle.fontFamily[eid];
const size = c.TextStyle.fontSize[eid];
diff --git a/apps/web/src/utils/jsx.ts b/apps/web/src/utils/jsx.ts
index c650151f..63389a50 100644
--- a/apps/web/src/utils/jsx.ts
+++ b/apps/web/src/utils/jsx.ts
@@ -11,6 +11,7 @@ import * as diffusionJsx from "@diffusionstudio/jsx";
import {
AnimationPhase,
AnimationType,
+ CaptionAlign,
CaptionType,
FontStyle,
GeometryType,
@@ -272,6 +273,12 @@ const CAPTION_PRESET_MAP = {
stark: CaptionType.STARK,
} as const;
+export const CAPTION_ALIGN_MAP = {
+ top: CaptionAlign.TOP,
+ center: CaptionAlign.CENTER,
+ bottom: CaptionAlign.BOTTOM,
+} as const;
+
type GenaiQueueItem = {
eid: number;
ref?: AssetRef;
@@ -1277,6 +1284,14 @@ export class WorldDocument implements ProjectDocument<HostNode> {
});
setComponent(world, eid, c.Caption, { colors });
break;
+ } case "verticalAlign": {
+ assert(hasComponent(world, eid, c.Caption), "`verticalAlign` only applies to <Captions>");
+ assert(typeof value === "string", "`verticalAlign` must be a string" + `, value: ${value}`);
+ assert(value in CAPTION_ALIGN_MAP, `invalid verticalAlign value: "${value}"`);
+ setComponent(world, eid, c.Caption, { verticalAlign: CAPTION_ALIGN_MAP[value as keyof typeof CAPTION_ALIGN_MAP] });
+ // A live decoder has already placed the box from the old alignment.
+ c.CaptionDecoder[eid]?.reposition(world, eid);
+ break;
}
}
}
diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.ts
index bc087b34..8778d298 100644
--- a/packages/jsx/src/types.ts
+++ b/packages/jsx/src/types.ts
@@ -201,6 +201,12 @@ export type PatchProps = {
preset?: CaptionPreset;
/** Fills the caption preset's color slots in order; any CSS color, alpha is ignored. */
colors?: string[];
+ /**
+ * Vertical placement of the caption block — `<Captions>` only: anchored to
+ * the top or bottom safe margin, or centered. The preset keeps owning the
+ * horizontal placement. Defaults to the preset's own alignment.
+ */
+ verticalAlign?: "top" | "center" | "bottom";
};
/** Every PatchProps key, at runtime — the `dapi node patch` allowlist. */
@@ -238,6 +244,7 @@ export const PATCH_PROP_KEYS = Object.keys({
offset: true,
preset: true,
colors: true,
+ verticalAlign: true,
} satisfies Record<keyof PatchProps, true>) as ReadonlyArray<keyof PatchProps>;
type TimingProps = Pick<PatchProps, "start" | "end" | "sourceIn" | "sourceOut">;
@@ -343,4 +350,7 @@ export type SequenceProps = Pick<PatchProps, "name"> & {
children?: SolidJSX.Element;
};
-export type CaptionsProps = Pick<PatchProps, "preset" | "colors" | "src" | "start" | "animations">;
+export type CaptionsProps = Pick<
+ PatchProps,
+ "preset" | "colors" | "verticalAlign" | "offsetX" | "offsetY" | "src" | "start" | "animations"
+>;