@osmo.inc/cli-linux-arm64 0.1.23 → 0.1.25

package/runtime/packages/scene/src/effect-schemas.d.mts

@@ -0,0 +1,246 @@
+/** @param {{id:string,collection:string,label:string}[]} FILM_STOCKS @param {readonly string[]} FILM_CAMERAS @param {boolean} [grouped] */
+export function filmKnobs(FILM_STOCKS: {
+    id: string;
+    collection: string;
+    label: string;
+}[], FILM_CAMERAS: readonly string[], grouped?: boolean): {
+    stock: {
+        type: "select";
+        label: string;
+        default: string;
+        options: {
+            [k: string]: string;
+        };
+    };
+    cameraProfile: {
+        type: "select";
+        label: string;
+        default: string;
+        options: {
+            [k: string]: string;
+        };
+    };
+    strength: {
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    exposure: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    warmth: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    tint: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    contrast: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    saturation: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    lift: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    gamma: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    print: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    grain: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    grainSaturation: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    grainSoftness: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    grainRoughness: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    halation: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    halationRadius: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    looksGrain: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    looksHalation: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    gauge: {
+        label: string;
+        type: "select";
+        default: string;
+        options: {
+            "35mm": string;
+            "16mm": string;
+            "8mm": string;
+        };
+        group?: string | undefined;
+    };
+    seed: {
+        group?: string | undefined;
+        integer: boolean;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+    textureFps: {
+        group?: string | undefined;
+        type: "number";
+        label: string;
+        default: number;
+        min: number;
+        max: number;
+        step: number;
+    };
+};
+export namespace BLUR_KNOBS {
+    namespace radius {
+        export let type: "number";
+        export let label: string;
+        let _default: number;
+        export { _default as default };
+        export let min: number;
+        export let max: number;
+        export let step: number;
+    }
+}
+export namespace GRAIN_KNOBS {
+    namespace amount {
+        let type_1: "number";
+        export { type_1 as type };
+        let label_1: string;
+        export { label_1 as label };
+        let _default_1: number;
+        export { _default_1 as default };
+        let min_1: number;
+        export { min_1 as min };
+        let max_1: number;
+        export { max_1 as max };
+        let step_1: number;
+        export { step_1 as step };
+    }
+}
+export namespace FILM_GROUPS {
+    namespace color {
+        let label_2: string;
+        export { label_2 as label };
+    }
+    namespace grain {
+        let label_3: string;
+        export { label_3 as label };
+    }
+    namespace halation {
+        let label_4: string;
+        export { label_4 as label };
+    }
+}

package/runtime/packages/scene/src/effect-schemas.mjs

@@ -0,0 +1,136 @@
+// Pure schema data shared by the authoring runtime and the source editor.
+export const BLUR_KNOBS = {
+	radius: {
+		type: /** @type {const} */ ("number"),
+		label: "Radius",
+		default: 8,
+		min: 0,
+		max: 64,
+		step: 0.5,
+	},
+};
+export const GRAIN_KNOBS = {
+	amount: {
+		type: /** @type {const} */ ("number"),
+		label: "Amount",
+		default: 0.04,
+		min: 0,
+		max: 1,
+		step: 0.01,
+	},
+};
+export const FILM_GROUPS = {
+	color: { label: "Color" },
+	grain: { label: "Grain" },
+	halation: { label: "Halation" },
+};
+/** @param {string} label @param {number} value @param {number} min @param {number} max @param {number} [step] */
+const number = (label, value, min, max, step = 0.01) => ({
+	type: /** @type {const} */ ("number"),
+	label,
+	default: value,
+	min,
+	max,
+	step,
+});
+/** @param {{id:string,collection:string,label:string}[]} FILM_STOCKS @param {readonly string[]} FILM_CAMERAS @param {boolean} [grouped] */
+export function filmKnobs(FILM_STOCKS, FILM_CAMERAS, grouped = false) {
+	const stockOptions = Object.fromEntries(
+		FILM_STOCKS.map((s) => [s.id, `${s.collection} / ${s.label}`]),
+	);
+	return {
+		stock: {
+			type: /** @type {const} */ ("select"),
+			label: "Film stock",
+			default: "stock/Vision3/Default/500T.fbfilmneg",
+			options: stockOptions,
+		},
+		cameraProfile: {
+			type: /** @type {const} */ ("select"),
+			label: "Input profile",
+			default: FILM_CAMERAS[0],
+			options: Object.fromEntries(FILM_CAMERAS.map((n) => [n, n])),
+		},
+		strength: number("Strength", 1, 0, 1),
+		exposure: {
+			...number("Exposure", 0, -16, 16, 0.05),
+			...(grouped ? { group: "color" } : {}),
+		},
+		warmth: {
+			...number("Warmth", 0, -100, 100, 1),
+			...(grouped ? { group: "color" } : {}),
+		},
+		tint: {
+			...number("Tint", 0, -100, 100, 1),
+			...(grouped ? { group: "color" } : {}),
+		},
+		contrast: {
+			...number("Contrast", 1, 0, 4),
+			...(grouped ? { group: "color" } : {}),
+		},
+		saturation: {
+			...number("Saturation", 1, 0, 4),
+			...(grouped ? { group: "color" } : {}),
+		},
+		lift: {
+			...number("Lift", 0, -1, 1),
+			...(grouped ? { group: "color" } : {}),
+		},
+		gamma: {
+			...number("Gamma", 1, 0.1, 4),
+			...(grouped ? { group: "color" } : {}),
+		},
+		print: {
+			...number("Print gain", 1, 0, 4),
+			...(grouped ? { group: "color" } : {}),
+		},
+		grain: {
+			...number("Grain", 1, 0, 3),
+			...(grouped ? { group: "grain" } : {}),
+		},
+		grainSaturation: {
+			...number("Grain saturation", 1, 0, 2),
+			...(grouped ? { group: "grain" } : {}),
+		},
+		grainSoftness: {
+			...number("Grain softness", 0, -1, 1),
+			...(grouped ? { group: "grain" } : {}),
+		},
+		grainRoughness: {
+			...number("Grain roughness", 0, -1, 1),
+			...(grouped ? { group: "grain" } : {}),
+		},
+		halation: {
+			...number("Halation", 1, 0, 1),
+			...(grouped ? { group: "halation" } : {}),
+		},
+		halationRadius: {
+			...number("Halation radius", 1, 0, 2),
+			...(grouped ? { group: "halation" } : {}),
+		},
+		looksGrain: {
+			...number("Look grain adjustment", 0, -1, 1),
+			...(grouped ? { group: "grain" } : {}),
+		},
+		looksHalation: {
+			...number("Look halation adjustment", 0, -1, 1),
+			...(grouped ? { group: "halation" } : {}),
+		},
+		gauge: {
+			...(grouped ? { group: "grain" } : {}),
+			label: "Film gauge",
+			type: /** @type {const} */ ("select"),
+			default: "35mm",
+			options: { "35mm": "35 mm", "16mm": "16 mm", "8mm": "8 mm" },
+		},
+		seed: {
+			...number("Grain seed", 0, 0, 16777215, 1),
+			integer: true,
+			...(grouped ? { group: "grain" } : {}),
+		},
+		textureFps: {
+			...number("Grain frame rate", 24, 1, 240, 1),
+			...(grouped ? { group: "grain" } : {}),
+		},
+	};
+}

package/runtime/packages/scene/src/effects.ts

@@ -1,3 +1,4 @@
+import {BLUR_KNOBS, GRAIN_KNOBS} from "./effect-schemas.mjs";
 import { isKnobRef, resolveKnob, type KnobRef } from "./knobs.js";
 import { isMotion, sampleMotion, type Motion, type MotionValue, type TrackDefinition } from "./motion.js";
 import { parseColor } from "./color.js";
@@ -28,13 +29,20 @@ export interface EffectDefinition<K extends Knobs = Knobs> {
 	 * Padding is reserved once for the whole effect. Library API, at most 4 passes. */
 	passes?: readonly Readonly<Record<string, UniformValue>>[];
 }
+/** Shared effect state, independent of its named knobs. */
+export interface EffectOptions {
+	readonly enabled?: boolean;
+}
 export interface EffectInstance {
+	readonly enabled: boolean;
 	readonly [EFFECT]: true;
 	readonly definition: EffectDefinition;
 	readonly sourceFile?: string;
 	readonly bindings: Readonly<Record<string, MotionValue | Motion | KnobRef>>;
+	/** Built-in processors resolve named controls after knob/motion evaluation. */
+	readonly evaluateBuiltin?: (values: Readonly<Record<string, MotionValue>>) => EvaluatedEffect;
 }
-export type EffectFactory<K extends Knobs> = ((values?: EffectBindings<K>) => EffectInstance) & {
+export type EffectFactory<K extends Knobs> = ((values?: EffectBindings<K>, options?: EffectOptions) => EffectInstance) & {
 	readonly definition: EffectDefinition<K>;
 };
 export interface EvaluatedEffect {
@@ -43,6 +51,9 @@ export interface EvaluatedEffect {
 	code?: string;
 	sourceFile?: string;
 	uniforms: Readonly<Record<string, UniformValue>>;
+	/** Pinned catalog asset key for the native multi-pass film processor. */
+	film?: string;
+	uniformData?: number[];
 }
 function fail(message: string): never { throw new Error(`Effect: ${message}`); }
 function record(value: unknown): value is Record<string, any> {
@@ -86,7 +97,10 @@ export function defineEffect<const K extends Knobs>(definition: EffectDefinition
 			fail(`${name}: more than 24 choices needs a uniform mapping`);
 	// Copy metadata: modifying the caller's objects cannot change a loaded effect.
 	const frozen = freeze({ ...JSON.parse(JSON.stringify({ ...definition, uniforms: undefined })), ...(definition.uniforms ? { uniforms: definition.uniforms } : {}), ...(typeof definition.padding === "function" ? { padding: definition.padding } : {}) }) as EffectDefinition<K>;
-	const factory = (values: EffectBindings<K> = {}): EffectInstance => {
+	const factory = (values: EffectBindings<K> = {}, options: EffectOptions = {}): EffectInstance => {
+		if (!record(options)) fail("expected effect options");
+		keys(options, ["enabled"], "options");
+		if (options.enabled !== undefined && typeof options.enabled !== "boolean") fail("enabled must be a boolean");
 		if (!record(values)) fail("expected named knob values");
 		const bindings: Record<string, MotionValue | Motion | KnobRef> = Object.create(null);
 		for (const [name, value] of Object.entries(values)) {
@@ -97,7 +111,7 @@ export function defineEffect<const K extends Knobs>(definition: EffectDefinition
 			} else validateValue(frozen.knobs[name], value, name);
 			bindings[name] = Array.isArray(value) ? Object.freeze([...value]) : value as MotionValue | Motion;
 		}
-		return Object.freeze({ [EFFECT]: true as const, definition: frozen as EffectDefinition, bindings: Object.freeze(bindings), ...(sourceFile ? { sourceFile } : {}) });
+		return Object.freeze({ [EFFECT]: true as const, enabled: options.enabled ?? true, definition: frozen as EffectDefinition, bindings: Object.freeze(bindings), ...(sourceFile ? { sourceFile } : {}) });
 	};
 	return Object.freeze(Object.assign(factory, { definition: frozen }));
 }
@@ -124,13 +138,16 @@ export function describeEffect(instance: EffectInstance, time = 0, resolveBindin
 		visible(knob.visibleWhen) && (!knob.group || visibleGroups[knob.group])
 	]));
 	const padding = normalizePadding(typeof definition.padding === "function" ? definition.padding(values as KnobValues<Knobs>) : definition.padding);
-	return freeze({ padding, src: definition.src, knobs: definition.knobs, groups, values, tracks, visibleGroups, visibleKnobs });
+	return freeze({ enabled: instance.enabled, padding, src: definition.src, knobs: definition.knobs, groups, values, tracks, visibleGroups, visibleKnobs });
 }
 export function evaluateEffects(effects: unknown, time: number, sourceFile?: string, resolveBinding?: (value: unknown) => unknown): EvaluatedEffect[] {
 	if (effects === undefined) return [];
 	if (!Array.isArray(effects) || effects.length > 32) fail("effects must be an array of at most 32 instances");
 	const evaluated = effects.flatMap((instance: EffectInstance) => {
+		if (!isEffect(instance)) fail("effects must contain effect instances");
+		if (!instance.enabled) return [];
 		const { values, padding } = describeEffect(instance, time, resolveBinding);
+		if (instance.evaluateBuiltin) return [instance.evaluateBuiltin(values)];
 		const def = instance.definition;
 		let uniforms: Readonly<Record<string, UniformValue>>;
 		if (def.uniforms) uniforms = def.uniforms(values as KnobValues<Knobs>);
@@ -178,7 +195,7 @@ fn eng_input(uv: vec2f) -> vec4f {
  */
 export const blur = defineEffect({
 	padding: ({ radius }) => Math.max(0, radius) * 2,
-	knobs: { radius: { type: "number", default: 8, min: 0, max: 64, step: 0.5 } },
+	knobs: BLUR_KNOBS,
 	// Separable Gaussian, sigma = radius, reaching two sigmas: a horizontal run,
 	// then a vertical one. 33 closely spaced taps each stay smooth at large radii,
 	// where a single 2D grid of the same cost left visible steps.
@@ -202,7 +219,7 @@ fn effect(uv: vec2f, time: f32) -> vec4f {
  */
 export const grain = defineEffect({
 	padding: 0,
-	knobs: { amount: { type: "number", default: 0.04, min: 0, max: 1, step: 0.01 } },
+	knobs: GRAIN_KNOBS,
 	code: `struct Uniforms { amount: f32 }
 fn effect(uv: vec2f, time: f32) -> vec4f {
   let c = eng_input(uv);

package/runtime/packages/scene/src/elements.ts

@@ -24,6 +24,7 @@ export type InputProps<P> = {
         : K extends
         | "id"
         | "label"
+        | "originalSrc"
         | "hidden"
         | "solo"
         | "track"
@@ -53,7 +54,7 @@ export interface FrameContext {
 export interface ClipProps {
 	/** Stable source identity, unique within its animation file. */
 	id?: string;
-	/** Literal root timeline lane, 0–99. Required at the Scene root; forbidden on nested layers. Does not change paint order. */
+	/** Literal root timeline lane, 0–99. Required at the Scene root; forbidden on nested layers. With Scene stacking="tracks", lower numbers paint in front. */
 	track?: number;
 	/** Start in the parent clock, in seconds. Motion uses time relative to this start. Default: 0. */
 	start?: number;
@@ -81,7 +82,12 @@ export interface TransformProps extends ClipProps {
 	opacity?: number;
 }
 export interface SceneStyleProps {
-	/** Optional lane metadata keyed by track number (0–99). Labels are static, one word maximum. Does not change paint order. */
+	/** Integrate animation subframes over an exposure. Video footage and its own properties hold the center frame; ancestor animation still applies. Models are unsupported. Default: off; true uses 180°, centered, 16 samples. */
+	motionBlur?: boolean | import("./motion-blur.js").MotionBlurSettings;
+	/** Track-first compositing: track 0 is frontmost; groups are local stacking scopes.
+	 * Omitted or "source" preserves legacy source-order compositing. New projects use "tracks". */
+	stacking?: "tracks" | "source";
+	/** Optional lane metadata keyed by track number (0–99). Labels are static, one word maximum. Stacking is controlled by Scene.stacking. */
 	tracks?: Readonly<Record<number, TrackMetadata>>;
 	/** Filter the complete viewport, including 3D surfaces; array order matters. */
 	effects?: readonly EffectInstance[];
@@ -104,6 +110,8 @@ export type SceneProps<K extends Knobs = Knobs> = SceneStyleProps & (
 );
 /** Timeline lane metadata; independent of the clips occupying the lane. */
 export interface TrackMetadata {
+	/** Sample this track's animation across the scene shutter. Default: true; requires Scene.motionBlur. */
+	motionBlur?: boolean;
 	/** Optional static display name, one word maximum, e.g. "Titles". */
 	label?: string;
 	/** Hide this lane's visuals; audio continues unless muted. Default: false. */
@@ -284,7 +292,11 @@ export interface MediaTiming extends ClipProps {
 	/** Gain from 0–1; animatable in JSX. Use 0 to mute video audio. Default: 1. */
 	volume?: number;
 }
-export interface VideoProps extends Omit<ImageProps, "src">, MediaTiming { src: AssetPath<"video"> }
+export interface VideoProps extends Omit<ImageProps, "src">, MediaTiming {
+  src: AssetPath<"video">;
+  /** Local full-quality source used only by CLI rendering with --original. Otherwise uses src. */
+  originalSrc?: string;
+}
 export interface AudioProps extends MediaTiming {
 	/** Local audio file path, relative to this TSX file. */
 	src: AssetPath<"audio">;