@scenerok/sdk 0.8.0 → 0.10.0

package/dist/media.js

@@ -1,38 +1,161 @@
 import { toSeconds } from './duration.js';
 import { getAudioLength, getVideoLength } from './stdlib.js';
+import { isPictureNode, } from './types.js';
+/** Length of a video whose length is not known, when it is appended with `push`. */
+const UNKNOWN_VIDEO_LENGTH = 5;
+/** Length of a still or text appended with `push` and no explicit duration. */
+export const DEFAULT_STILL_LENGTH = 3;
 function normalizeAnims(animate) {
     if (!animate)
         return [];
     return Array.isArray(animate) ? [...animate] : [animate];
 }
-function resolveDeclaredDuration(opts, fallback) {
-    if (opts?.duration !== undefined)
-        return toSeconds(opts.duration);
-    return fallback;
+function requireFinite(value, method, what) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new TypeError(`${method}() expected ${what}, got ${value === undefined ? 'nothing' : JSON.stringify(value)}`);
+    }
+    return value;
 }
-/** Create a video clip from a path/URL. Pass `duration` when the asset is not probed yet. */
-export function video(source, options = {}) {
+/**
+ * A trim on a trimmed value is relative to what the first kept:
+ * `clip.trim(10, 20).trim(2, 4)` plays source 12–14 s. Past the kept range is an error.
+ */
+export function composeTrim(previous, start, end) {
+    const base = previous.trimStart ?? 0;
+    const keptEnd = previous.trimEnd ?? 0;
+    const trimStart = start !== undefined ? base + toSeconds(start) : base;
+    const trimEnd = end !== undefined ? base + toSeconds(end) : keptEnd;
+    if (keptEnd > base && (trimEnd > keptEnd || trimStart > keptEnd)) {
+        throw new RangeError(`trim() is relative to the previous trim, which kept ${keptEnd - base}s; this one runs to ${Math.max(trimStart, trimEnd) - base}s`);
+    }
+    if (trimEnd > 0 && trimEnd <= trimStart) {
+        throw new RangeError(`trim() end (${trimEnd - base}s) must be after its start (${trimStart - base}s)`);
+    }
+    return { trimStart, trimEnd };
+}
+/** A crop on a cropped value is relative to the first, like `trim`. */
+export function composeCrop(previous, x, y, width, height) {
+    for (const [value, what] of [[x, 'an x offset'], [y, 'a y offset'], [width, 'a width'], [height, 'a height']]) {
+        requireFinite(value, 'crop', what);
+    }
+    if (x < 0 || y < 0) {
+        throw new RangeError(`crop() offsets count from the top-left and cannot be negative, got (${x}, ${y})`);
+    }
+    if (width <= 0 || height <= 0) {
+        throw new RangeError(`crop() needs a positive width and height, got ${width}x${height}`);
+    }
+    if (previous && (x + width > previous.width || y + height > previous.height)) {
+        throw new RangeError(`crop() is relative to the previous crop, which kept ${previous.width}x${previous.height}; this one reaches ${x + width}x${y + height}`);
+    }
+    return { x: (previous?.x ?? 0) + x, y: (previous?.y ?? 0) + y, width, height };
+}
+const MASK_MODES = ['alpha', 'luma', 'inverted'];
+export function makeMask(matte, options = {}) {
+    if (!isPictureNode(matte)) {
+        throw new TypeError('mask() needs a picture for its matte (video, image, text, solid, or timeline)');
+    }
+    const mode = options.mode ?? 'alpha';
+    if (!MASK_MODES.includes(mode)) {
+        throw new RangeError(`Unknown mask mode '${String(mode)}'. Use one of: ${MASK_MODES.join(', ')}.`);
+    }
+    return { matte, mode };
+}
+/** A grade scoped to one value. LUTs read a file at compile time, so they stay a VidScript statement. */
+export function makeClipEffect(name, params = {}) {
+    if (!name || !name.trim())
+        throw new TypeError('filter() needs a filter name');
+    if (name.trim().toLowerCase() === 'lut') {
+        throw new TypeError('filter("lut") reads a .cube file at compile time; use VidScript: filter "lut", file: "look.cube"');
+    }
+    return { type: 'builtin', id: `fx_${name}`, name, start: 0, end: 0, params: { ...params } };
+}
+/** How long a clip plays: the source range at `|speed|`, `loop` times; 0 when unknown. */
+export function playedLength(edits, mediaDuration) {
+    const trimStart = edits.trimStart ?? 0;
+    const trimEnd = edits.trimEnd ?? 0;
+    const speed = edits.speed ?? 1;
+    const loop = edits.loop ?? 1;
+    const sourceEnd = trimEnd > trimStart ? trimEnd : ((mediaDuration ?? 0) > trimStart ? mediaDuration : 0);
+    const span = sourceEnd - trimStart;
+    if (span <= 0 || speed === 0)
+        return 0;
+    return (span / Math.abs(speed)) * Math.max(1, Math.floor(loop));
+}
+function editsFromOptions(options) {
+    const edits = {};
+    if (options.trimStart !== undefined)
+        edits.trimStart = toSeconds(options.trimStart);
+    if (options.trimEnd !== undefined)
+        edits.trimEnd = toSeconds(options.trimEnd);
+    if (options.speed !== undefined)
+        edits.speed = options.speed;
+    if (options.loop !== undefined)
+        edits.loop = options.loop;
+    return edits;
+}
+function buildMedia(state) {
+    const { kind, source, options, edits, sequence } = state;
     const animations = normalizeAnims(options.animate);
-    const duration = resolveDeclaredDuration(options, 5);
-    const clip = {
+    const mediaDuration = kind === 'video' && options.duration !== undefined ? toSeconds(options.duration) : undefined;
+    const next = (patch) => buildMedia({ ...state, ...patch });
+    const withEdits = (patch) => next({ edits: { ...edits, ...patch } });
+    const node = {
         __sdk: true,
-        kind: 'video',
+        kind,
         source,
         options: { ...options },
-        duration,
+        edits: { ...edits },
+        ...(sequence ? { sequence } : {}),
+        mediaDuration,
+        get duration() {
+            if (kind === 'image')
+                return DEFAULT_STILL_LENGTH;
+            const played = playedLength(edits, mediaDuration);
+            return played > 0 ? played : UNKNOWN_VIDEO_LENGTH;
+        },
         animations,
-        animate(anim) {
-            const next = normalizeAnims(anim);
-            return video(source, {
-                ...options,
-                animate: [...animations, ...next],
+        trim(start, end) {
+            return withEdits(composeTrim(edits, start, end));
+        },
+        speed(factor) {
+            return withEdits({ speed: requireFinite(factor, 'speed', 'a speed factor') });
+        },
+        loop(count) {
+            return withEdits({ loop: requireFinite(count, 'loop', 'a repeat count') });
+        },
+        resize(width, height) {
+            return withEdits({
+                width: requireFinite(width, 'resize', 'a width'),
+                height: requireFinite(height, 'resize', 'a height'),
             });
         },
+        opacity(value) {
+            return withEdits({ opacity: requireFinite(value, 'opacity', 'an opacity') });
+        },
+        filter(name, params) {
+            return withEdits({ effects: [...(edits.effects ?? []), makeClipEffect(name, params)] });
+        },
+        crop(x, y, width, height) {
+            return withEdits({ crop: composeCrop(edits.crop, x, y, width, height) });
+        },
+        mask(matte, maskOptions) {
+            if (edits.mask)
+                throw new Error('mask() is already applied to this value; one matte per value');
+            return withEdits({ mask: makeMask(matte, maskOptions) });
+        },
+        animate(anim) {
+            return next({ options: { ...options, animate: [...animations, ...normalizeAnims(anim)] } });
+        },
         with(opts) {
-            return video(source, { ...options, ...opts, animate: opts.animate ?? options.animate });
+            const merged = { ...options, ...opts, animate: opts.animate ?? options.animate };
+            return next({ options: merged, edits: { ...edits, ...editsFromOptions(opts) } });
         },
     };
-    return clip;
+    return node;
+}
+/** A video clip from a path/URL. Pass `duration` when the asset is not probed yet. */
+export function video(source, options = {}) {
+    return buildMedia({ kind: 'video', source, options: { ...options }, edits: editsFromOptions(options) });
 }
 /** Probe a video duration when omitted, then create a video clip. */
 export async function loadVideo(source, options = {}) {
@@ -41,42 +164,81 @@ export async function loadVideo(source, options = {}) {
     const duration = await getVideoLength(source);
     return video(source, { ...options, duration });
 }
-/** Create a text layer. */
+/** A still image. It fills its placement window (`image ≤ video`). */
+export function image(source, options = {}) {
+    return buildMedia({ kind: 'image', source, options: { ...options }, edits: {} });
+}
+/**
+ * A numbered-frame source (`input frames = "shot.%04d.png", count: 24, rate: 12`).
+ * Plays `count / rate` seconds; `rate` defaults to the timeline fps.
+ */
+export function imageSequence(pattern, options) {
+    const { first = 1, count, rate, ...rest } = options;
+    if (!/%0?\d*d/.test(pattern)) {
+        throw new TypeError(`imageSequence() needs a numbered pattern like "shot.%04d.png", got "${pattern}"`);
+    }
+    if (!Number.isInteger(count) || count <= 0) {
+        throw new RangeError(`imageSequence() needs a positive frame count, got ${String(count)}`);
+    }
+    const sequence = { first, count, ...(rate !== undefined ? { rate } : {}) };
+    const duration = rate !== undefined ? count / rate : undefined;
+    return buildMedia({
+        kind: 'video',
+        source: pattern,
+        options: { ...rest, ...(duration !== undefined ? { duration } : {}) },
+        edits: editsFromOptions(rest),
+        sequence,
+    });
+}
+/** A text layer. */
 export function text(content, options = {}) {
     const animations = normalizeAnims(options.animate);
-    const layer = {
+    return {
         __sdk: true,
         kind: 'text',
         content,
         options: { ...options },
         animations,
         animate(anim) {
-            const next = normalizeAnims(anim);
-            return text(content, {
-                ...options,
-                animate: [...animations, ...next],
-            });
+            return text(content, { ...options, animate: [...animations, ...normalizeAnims(anim)] });
         },
         with(opts) {
             return text(content, { ...options, ...opts, animate: opts.animate ?? options.animate });
         },
     };
-    return layer;
 }
-/** Create an audio track. */
-export function audio(source, options = {}) {
-    const duration = resolveDeclaredDuration(options, 5);
-    const track = {
+function buildAudio(state) {
+    const { source, options, trimEnd } = state;
+    const trimStart = options.trimStart !== undefined ? toSeconds(options.trimStart) : 0;
+    const declared = options.duration !== undefined ? toSeconds(options.duration) : undefined;
+    const known = trimEnd > trimStart ? trimEnd - trimStart : declared;
+    return {
         __sdk: true,
         kind: 'audio',
         source,
         options: { ...options },
-        duration,
+        mediaDuration: known,
+        duration: known ?? UNKNOWN_VIDEO_LENGTH,
+        trim(start, end) {
+            const composed = composeTrim({ trimStart, trimEnd }, start, end);
+            // Without an out-point the length follows the in-point.
+            const remaining = composed.trimEnd > composed.trimStart
+                ? undefined
+                : (declared !== undefined ? Math.max(0, declared - (composed.trimStart - trimStart)) : undefined);
+            return buildAudio({
+                source,
+                options: { ...options, trimStart: composed.trimStart, ...(remaining !== undefined ? { duration: remaining } : {}) },
+                trimEnd: composed.trimEnd,
+            });
+        },
         with(opts) {
-            return audio(source, { ...options, ...opts });
+            return buildAudio({ ...state, options: { ...options, ...opts } });
         },
     };
-    return track;
+}
+/** An audio track. */
+export function audio(source, options = {}) {
+    return buildAudio({ source, options: { ...options }, trimEnd: 0 });
 }
 /** Probe an audio duration when omitted, then create an audio track. */
 export async function loadAudio(source, options = {}) {
@@ -85,7 +247,35 @@ export async function loadAudio(source, options = {}) {
     const duration = await getAudioLength(source);
     return audio(source, { ...options, duration });
 }
-/** Builtin post-processing filter (e.g. glow, blur). */
+/** A flat-colour rectangle — full frame unless sized. With `radius`/`corners` it is a shape matte. */
+export function solid(color, options = {}) {
+    if (typeof color !== 'string' || !color.trim())
+        throw new TypeError('solid() needs a colour');
+    const animations = normalizeAnims(options.animate);
+    return {
+        __sdk: true,
+        kind: 'solid',
+        color,
+        options: { ...options },
+        animate(anim) {
+            return solid(color, { ...options, animate: [...animations, ...normalizeAnims(anim)] });
+        },
+        with(opts) {
+            return solid(color, { ...options, ...opts, animate: opts.animate ?? options.animate });
+        },
+    };
+}
+/** A transparent gap: `t.push(gap(), 2)` advances the playhead by 2 s. */
+export function gap() {
+    return { __sdk: true, kind: 'gap' };
+}
+/** A named instant (`t[4][4] = marker('act 2')`). Exported as an OTIO marker; never rendered. */
+export function marker(name, metadata) {
+    if (typeof name !== 'string' || !name.trim())
+        throw new TypeError('marker() needs a name');
+    return { __sdk: true, kind: 'marker', name, ...(metadata ? { metadata: { ...metadata } } : {}) };
+}
+/** Builtin post-processing filter over the frame (e.g. glow, blur). */
 export function filter(name, params = {}) {
     return {
         __sdk: true,

package/dist/motion-tracks.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Animation → motion-track lowering — the SDK's copy of `animationToMotionTracks`
+ * in the platform's `src/lib/motion/ir-motion.ts`. Renderers read motion tracks
+ * by target (`opacity`, `transform.position.y`, …), so an SDK animation must
+ * lower to the same tracks a VidScript `animate:` does.
+ */
+import type { IRAnimation, IRMotionTrack } from './ir.js';
+export declare function animationToMotionTracks(animation: IRAnimation): IRMotionTrack[];
+export declare function animationsToMotionTracks(animations: IRAnimation[] | undefined): IRMotionTrack[];
+//# sourceMappingURL=motion-tracks.d.ts.map

package/dist/motion-tracks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motion-tracks.d.ts","sourceRoot":"","sources":["../src/motion-tracks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAiB,MAAM,SAAS,CAAC;AAsEzE,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,WAAW,GAAG,aAAa,EAAE,CA6F/E;AAED,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,WAAW,EAAE,GAAG,SAAS,GAAG,aAAa,EAAE,CAE/F"}

package/dist/motion-tracks.js

@@ -0,0 +1,150 @@
+/**
+ * Animation → motion-track lowering — the SDK's copy of `animationToMotionTracks`
+ * in the platform's `src/lib/motion/ir-motion.ts`. Renderers read motion tracks
+ * by target (`opacity`, `transform.position.y`, …), so an SDK animation must
+ * lower to the same tracks a VidScript `animate:` does.
+ */
+const EPSILON = 0.0001;
+function finiteNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function normalizeEasingName(easing) {
+    return (easing ?? '').toLowerCase().replace(/[-_\s]/g, '');
+}
+function motionTrack(animation, suffix, target, from, to, behavior) {
+    const springEasing = normalizeEasingName(animation.easing) === 'spring';
+    const keyframeEasing = springEasing ? 'linear' : animation.easing;
+    const resolvedBehavior = behavior
+        || (springEasing ? { type: 'spring' } : undefined)
+        || (animation.loop ? { type: 'loop' } : undefined);
+    return {
+        id: `${animation.id}_${suffix}`,
+        target,
+        keyframes: [
+            { time: animation.start, value: from },
+            { time: animation.end, value: to, easing: keyframeEasing },
+        ],
+        behavior: resolvedBehavior,
+        plugin: animation.plugin,
+        sourceAnimationId: animation.id,
+    };
+}
+function customTargetForKey(key) {
+    switch (key) {
+        case 'opacity':
+            return 'opacity';
+        case 'x':
+        case 'offsetX':
+        case 'translateX':
+            return 'transform.position.x';
+        case 'y':
+        case 'offsetY':
+        case 'translateY':
+            return 'transform.position.y';
+        case 'scale':
+            return 'transform.scale';
+        case 'scaleX':
+            return 'transform.scale.x';
+        case 'scaleY':
+            return 'transform.scale.y';
+        case 'rotation':
+        case 'degrees':
+            return 'transform.rotation.z';
+        default:
+            return key.startsWith('effect.') ? key : `custom.${key}`;
+    }
+}
+export function animationToMotionTracks(animation) {
+    const from = recordValue(animation.from);
+    const to = recordValue(animation.to);
+    const tracks = [];
+    switch (animation.type) {
+        case 'fade':
+        case 'opacity':
+            tracks.push(motionTrack(animation, 'opacity', 'opacity', finiteNumber(from.opacity, 0), finiteNumber(to.opacity, 1)));
+            break;
+        case 'slideX':
+        case 'translateX':
+            tracks.push(motionTrack(animation, 'x', 'transform.position.x', finiteNumber(from.x, 0), finiteNumber(to.x, 0)));
+            break;
+        case 'slideY':
+        case 'translateY':
+            tracks.push(motionTrack(animation, 'y', 'transform.position.y', finiteNumber(from.y, 0), finiteNumber(to.y, 0)));
+            break;
+        case 'scale': {
+            const fromScale = finiteNumber(from.scale ?? from.x, 1);
+            const toScale = finiteNumber(to.scale ?? to.x, 1);
+            tracks.push(motionTrack(animation, 'scale_x', 'transform.scale.x', fromScale, toScale));
+            tracks.push(motionTrack(animation, 'scale_y', 'transform.scale.y', finiteNumber(from.y, fromScale), finiteNumber(to.y, toScale)));
+            break;
+        }
+        case 'rotate':
+        case 'rotation':
+            tracks.push(motionTrack(animation, 'rotation', 'transform.rotation.z', finiteNumber(from.rotation ?? from.degrees, 0), finiteNumber(to.rotation ?? to.degrees, 0)));
+            break;
+        case 'pop': {
+            const fromScale = finiteNumber(from.scale, 0.55);
+            const overshootScale = finiteNumber(to.scale, 1.06);
+            const settleScale = finiteNumber(to.settleScale ?? to.finalScale, 1);
+            const overshootTime = animation.start + Math.max(EPSILON, animation.end - animation.start) * 0.72;
+            const behavior = animation.loop ? { type: 'loop' } : undefined;
+            for (const axis of ['x', 'y']) {
+                tracks.push({
+                    id: `${animation.id}_scale_${axis}`,
+                    target: `transform.scale.${axis}`,
+                    keyframes: [
+                        { time: animation.start, value: fromScale },
+                        { time: overshootTime, value: overshootScale, easing: animation.easing },
+                        { time: animation.end, value: settleScale, easing: 'easeOutCubic' },
+                    ],
+                    behavior,
+                    plugin: animation.plugin,
+                    sourceAnimationId: animation.id,
+                });
+            }
+            tracks.push(motionTrack(animation, 'opacity', 'opacity', finiteNumber(from.opacity, 0), finiteNumber(to.opacity, 1)));
+            break;
+        }
+        case 'rise':
+            tracks.push(motionTrack(animation, 'y', 'transform.position.y', finiteNumber(from.y, 80), finiteNumber(to.y, 0)));
+            tracks.push(motionTrack(animation, 'opacity', 'opacity', finiteNumber(from.opacity, 0), finiteNumber(to.opacity, 1)));
+            break;
+        case 'swing':
+            tracks.push(motionTrack(animation, 'rotation', 'transform.rotation.z', finiteNumber(from.rotation, -14), finiteNumber(to.rotation, 0)));
+            tracks.push(motionTrack(animation, 'y', 'transform.position.y', finiteNumber(from.y, 35), finiteNumber(to.y, 0)));
+            tracks.push(motionTrack(animation, 'opacity', 'opacity', finiteNumber(from.opacity, 0), finiteNumber(to.opacity, 1)));
+            break;
+        case 'glitch':
+            tracks.push(motionTrack(animation, 'opacity', 'opacity', finiteNumber(from.opacity, 0.2), finiteNumber(to.opacity, 1)));
+            tracks.push(motionTrack(animation, 'jitter_x', 'transform.position.x', 0, 0, { type: 'wiggle', params: { amplitude: 3.5, frequency: 30 } }));
+            tracks.push(motionTrack(animation, 'jitter_y', 'transform.position.y', 0, 0, { type: 'wiggle', params: { amplitude: 2.8, frequency: 34, phase: 0.25 } }));
+            break;
+        case 'float': {
+            const amplitude = Math.abs(finiteNumber(to.y, 12) - finiteNumber(from.y, -12)) / 2;
+            const duration = Math.max(EPSILON, animation.end - animation.start);
+            tracks.push(motionTrack(animation, 'float_y', 'transform.position.y', 0, 0, {
+                type: 'wiggle',
+                params: { amplitude, frequency: 1 / duration },
+            }));
+            break;
+        }
+        case 'typewriter':
+            tracks.push(motionTrack(animation, 'reveal', 'text.reveal', 0, 1, { type: 'typewriter' }));
+            break;
+        default: {
+            const keys = new Set([...Object.keys(from), ...Object.keys(to)]);
+            for (const key of keys) {
+                tracks.push(motionTrack(animation, key, customTargetForKey(key), (from[key] ?? 0), (to[key] ?? 1)));
+            }
+        }
+    }
+    return tracks;
+}
+export function animationsToMotionTracks(animations) {
+    return (animations || []).flatMap(animationToMotionTracks);
+}

package/dist/motion.d.ts

@@ -1,9 +1,43 @@
+/**
+ * Animation descriptors — the same set as VidScript's `@scenerok/basic-animations`
+ * (`import fx from "@scenerok/basic-animations"`, `animate: fx.fadeIn(0.5s)`),
+ * with the same types and defaults, so an SDK `animate` lowers to the same IR.
+ */
 import { type TimeInput } from './duration.js';
 import type { AnimationDescriptor } from './types.js';
+export interface AnimationOptions {
+    /** Easing name (`easeOutCubic`, `spring`, `linear`, …). */
+    easing?: string;
+    /** `end` aligns the animation to the end of the placement window (exits). */
+    align?: 'start' | 'end';
+    loop?: boolean;
+}
+/**
+ * Any animation by type — the SDK spelling of a VidScript object literal
+ * (`animate: { type: "kenBurns", from: { scale: 1 }, to: { scale: 1.1 } }`).
+ * A `duration` of 0 spans the whole placement window.
+ */
+export declare function animation(type: string, from: Record<string, unknown>, to: Record<string, unknown>, duration?: TimeInput, options?: AnimationOptions): AnimationDescriptor;
 export declare function fadeIn(duration?: TimeInput): AnimationDescriptor;
 export declare function fadeOut(duration?: TimeInput): AnimationDescriptor;
 export declare function slideY(fromY?: number, toY?: number, duration?: TimeInput): AnimationDescriptor;
 export declare function slideX(fromX?: number, toX?: number, duration?: TimeInput): AnimationDescriptor;
+/** Uniform scale from → to. */
 export declare function scale(from?: number, to?: number, duration?: TimeInput): AnimationDescriptor;
+/** Scale + fade entrance with a slight overshoot. */
 export declare function popIn(duration?: TimeInput): AnimationDescriptor;
+/** Upward entrance with a fade. */
+export declare function riseIn(duration?: TimeInput, distance?: number): AnimationDescriptor;
+/** Rotates in while sliding and fading. */
+export declare function swingIn(duration?: TimeInput): AnimationDescriptor;
+/** Jittery entrance with a flash. */
+export declare function glitchIn(duration?: TimeInput): AnimationDescriptor;
+/** Gentle looping vertical bob. */
+export declare function float(duration?: TimeInput, amplitude?: number): AnimationDescriptor;
+/** Reveals text character by character (`stagger` on the text picks words or chars). */
+export declare function typewriter(duration?: TimeInput): AnimationDescriptor;
+/** Constant rotation in degrees over the whole window (`rotation:` in VidScript). */
+export declare function rotate(from: number, to?: number, duration?: TimeInput): AnimationDescriptor;
+/** Gain automation for an audio track (`animate: { type: "volume", … }`). */
+export declare function volumeRamp(from: number, to: number, duration?: TimeInput, options?: AnimationOptions): AnimationDescriptor;
 //# sourceMappingURL=motion.d.ts.map

package/dist/motion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../src/motion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAqBtD,wBAAgB,MAAM,CAAC,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAErE;AAED,wBAAgB,OAAO,CAAC,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAEtE;AAED,wBAAgB,MAAM,CAAC,KAAK,SAAK,EAAE,GAAG,SAAI,EAAE,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAE1F;AAED,wBAAgB,MAAM,CAAC,KAAK,SAAM,EAAE,GAAG,SAAI,EAAE,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAE3F;AAED,wBAAgB,KAAK,CAAC,IAAI,SAAM,EAAE,EAAE,SAAI,EAAE,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAExF;AAED,wBAAgB,KAAK,CAAC,QAAQ,GAAE,SAAgB,GAAG,mBAAmB,CAErE"}
+{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../src/motion.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IACxB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3B,QAAQ,GAAE,SAAa,EACvB,OAAO,GAAE,gBAAqB,GAC7B,mBAAmB,CAWrB;AAED,wBAAgB,MAAM,CAAC,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAErE;AAED,wBAAgB,OAAO,CAAC,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAEtE;AAED,wBAAgB,MAAM,CAAC,KAAK,SAAK,EAAE,GAAG,SAAI,EAAE,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAE1F;AAED,wBAAgB,MAAM,CAAC,KAAK,SAAM,EAAE,GAAG,SAAI,EAAE,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAE3F;AAED,+BAA+B;AAC/B,wBAAgB,KAAK,CAAC,IAAI,SAAM,EAAE,EAAE,SAAI,EAAE,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAExF;AAED,qDAAqD;AACrD,wBAAgB,KAAK,CAAC,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAEpE;AAED,mCAAmC;AACnC,wBAAgB,MAAM,CAAC,QAAQ,GAAE,SAAgB,EAAE,QAAQ,SAAK,GAAG,mBAAmB,CAErF;AAED,2CAA2C;AAC3C,wBAAgB,OAAO,CAAC,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAEtE;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,CAAC,QAAQ,GAAE,SAAgB,GAAG,mBAAmB,CAExE;AAED,mCAAmC;AACnC,wBAAgB,KAAK,CAAC,QAAQ,GAAE,SAAe,EAAE,SAAS,SAAK,GAAG,mBAAmB,CAEpF;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,QAAQ,GAAE,SAAe,GAAG,mBAAmB,CAEzE;AAED,qFAAqF;AACrF,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAO,EAAE,QAAQ,GAAE,SAAa,GAAG,mBAAmB,CAE5F;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,GAAE,SAAa,EAAE,OAAO,GAAE,gBAAqB,GAAG,mBAAmB,CAEjI"}

package/dist/motion.js

@@ -1,31 +1,71 @@
+/**
+ * Animation descriptors — the same set as VidScript's `@scenerok/basic-animations`
+ * (`import fx from "@scenerok/basic-animations"`, `animate: fx.fadeIn(0.5s)`),
+ * with the same types and defaults, so an SDK `animate` lowers to the same IR.
+ */
 import { toSeconds } from './duration.js';
-function anim(type, from, to, duration, extra) {
+/**
+ * Any animation by type — the SDK spelling of a VidScript object literal
+ * (`animate: { type: "kenBurns", from: { scale: 1 }, to: { scale: 1.1 } }`).
+ * A `duration` of 0 spans the whole placement window.
+ */
+export function animation(type, from, to, duration = 0, options = {}) {
     return {
         __sdk: true,
         kind: 'animation',
         type,
-        from,
-        to,
+        from: { ...from },
+        to: { ...to },
         duration: toSeconds(duration),
         plugin: '@scenerok/basic-animations',
-        ...extra,
+        ...options,
     };
 }
 export function fadeIn(duration = 0.5) {
-    return anim('fade', { opacity: 0 }, { opacity: 1 }, duration);
+    return animation('fade', { opacity: 0 }, { opacity: 1 }, duration);
 }
 export function fadeOut(duration = 0.5) {
-    return anim('fade', { opacity: 1 }, { opacity: 0 }, duration, { align: 'end' });
+    return animation('fade', { opacity: 1 }, { opacity: 0 }, duration, { align: 'end' });
 }
 export function slideY(fromY = 30, toY = 0, duration = 0.6) {
-    return anim('translateY', { y: fromY }, { y: toY }, duration);
+    return animation('translateY', { y: fromY }, { y: toY }, duration);
 }
 export function slideX(fromX = -30, toX = 0, duration = 0.6) {
-    return anim('translateX', { x: fromX }, { x: toX }, duration);
+    return animation('translateX', { x: fromX }, { x: toX }, duration);
 }
+/** Uniform scale from → to. */
 export function scale(from = 0.8, to = 1, duration = 0.5) {
-    return anim('scale', { scale: from }, { scale: to }, duration);
+    return animation('scale', { scale: from }, { scale: to }, duration);
 }
-export function popIn(duration = 0.45) {
-    return anim('scale', { scale: 0.6, opacity: 0 }, { scale: 1, opacity: 1 }, duration);
+/** Scale + fade entrance with a slight overshoot. */
+export function popIn(duration = 0.7) {
+    return animation('pop', { scale: 0.55, opacity: 0 }, { scale: 1.06, opacity: 1 }, duration);
+}
+/** Upward entrance with a fade. */
+export function riseIn(duration = 0.85, distance = 80) {
+    return animation('rise', { y: distance, opacity: 0 }, { y: 0, opacity: 1 }, duration);
+}
+/** Rotates in while sliding and fading. */
+export function swingIn(duration = 0.9) {
+    return animation('swing', { rotation: -14, y: 35, opacity: 0 }, { rotation: 0, y: 0, opacity: 1 }, duration);
+}
+/** Jittery entrance with a flash. */
+export function glitchIn(duration = 0.65) {
+    return animation('glitch', { opacity: 0 }, { opacity: 1 }, duration);
+}
+/** Gentle looping vertical bob. */
+export function float(duration = 2.2, amplitude = 12) {
+    return animation('float', { y: -amplitude }, { y: amplitude }, duration, { loop: true });
+}
+/** Reveals text character by character (`stagger` on the text picks words or chars). */
+export function typewriter(duration = 1.8) {
+    return animation('typewriter', {}, {}, duration);
+}
+/** Constant rotation in degrees over the whole window (`rotation:` in VidScript). */
+export function rotate(from, to = from, duration = 0) {
+    return animation('rotation', { rotation: from }, { rotation: to }, duration);
+}
+/** Gain automation for an audio track (`animate: { type: "volume", … }`). */
+export function volumeRamp(from, to, duration = 0, options = {}) {
+    return animation('volume', { volume: from }, { volume: to }, duration, options);
 }

package/dist/plugins/invoke.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/plugins/invoke.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC;AACvC,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CACJ,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACvC,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAsBD,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG;IACzD,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAiBA;AA8BD,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,CAwBlE;AAgBD,gEAAgE;AAChE,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,SAAS,CAAC,CAMpB;AAED,kEAAkE;AAClE,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,UAAU,CAAC,CAMrB;AAED,mEAAmE;AACnE,wBAAsB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAChD,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED,mFAAmF;AACnF,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,iBAAiB,CAAC,CAE5B"}
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/plugins/invoke.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC;AACvC,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CACJ,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACvC,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAsBD,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG;IACzD,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAiBA;AA+BD,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,CA2BlE;AAgBD,gEAAgE;AAChE,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,SAAS,CAAC,CAMpB;AAED,kEAAkE;AAClE,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,UAAU,CAAC,CAMrB;AAED,mEAAmE;AACnE,wBAAsB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAChD,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED,mFAAmF;AACnF,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,iBAAiB,CAAC,CAE5B"}

package/dist/plugins/invoke.js

@@ -55,10 +55,13 @@ export function mapPluginResult(result) {
         return result;
     const r = result;
     if (r.type === 'video' && typeof r.url === 'string') {
+        // Like VidScript: the media's pixel size is not a placement size, and a
+        // generated clip with sound brings it along.
+        const metadata = (r.metadata && typeof r.metadata === 'object' ? r.metadata : {});
+        const nativeAudio = metadata.native_audio === true || metadata.has_audio === true;
         return video(r.url, {
             duration: typeof r.duration === 'number' ? r.duration : 5,
-            width: typeof r.width === 'number' ? r.width : undefined,
-            height: typeof r.height === 'number' ? r.height : undefined,
+            ...(nativeAudio ? { nativeAudio: true } : {}),
         });
     }
     if (r.type === 'audio' && typeof r.url === 'string') {

package/dist/timeline.d.ts

@@ -21,6 +21,9 @@ export interface Timeline extends TimelineLike {
  * t.push(text('Tail'))
  * return t.toIR()
  * ```
+ *
+ * Without `width`/`height`/`fps` it takes the host canvas (the importing
+ * VidScript's output, or its parent's when nested), else 1080×1920 at 30 fps.
  */
 export declare function timeline(options?: TimelineOptions): Timeline;
 export declare function isTimeline(value: unknown): value is Timeline;

package/dist/timeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAU7E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,eAAe,EAEhB,MAAM,YAAY,CAAC;AAkCpB,MAAM,WAAW,QAAS,SAAQ,YAAY;IAC5C,mDAAmD;IACnD,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,OAAO,CAAC;IACvE,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAClE,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACrD,IAAI,IAAI,UAAU,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CA2EhE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAO5D"}
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0C,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAYvF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAGV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,eAAe,EAIhB,MAAM,YAAY,CAAC;AAmEpB,MAAM,WAAW,QAAS,SAAQ,YAAY;IAC5C,mDAAmD;IACnD,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,OAAO,CAAC;IACvE,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAClE,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACrD,IAAI,IAAI,UAAU,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CAoGhE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAQ5D"}