@nodetool-ai/video-nodes 0.8.1

package/dist/nodes/timeline.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Timeline nodes — operate on persisted timeline sequences (the video
+ * editor's documents) referenced by the `timeline` type.
+ *
+ * RenderTimeline composites the sequence frame by frame through the same GPU
+ * compositor and scene model the editor's preview and its in-browser export
+ * use (`@nodetool-ai/timeline/render`), so a workflow render is the picture
+ * the user previewed: clip placement, transforms, opacity, blend modes,
+ * transitions, animations, effects, captions, text and shapes, across every
+ * visual track. ffmpeg decodes clip media into RGBA and encodes the result.
+ *
+ * Compositing needs a WebGPU device, which means the optional `webgpu` (Dawn)
+ * package and a working driver. Both profiles ship Dawn (D9,
+ * docs/plans/motion-graphics.md), and the Docker image installs lavapipe as its
+ * Vulkan driver, so a server render is composited too. A host that still has no
+ * adapter falls back to the older ffmpeg rough cut — video/image clips
+ * normalized and concatenated in start order — which ignores everything above.
+ * The fallback is a `warning` on the job and `metadata.render_mode` on the
+ * output says which path ran: "composited" or "rough_cut".
+ *
+ * `format` picks the container and `alpha` decides whether the frames keep a
+ * transparency channel: `webm` (VP9, `yuva420p`), `mov` (ProRes 4444,
+ * `yuva444p10le`) and `png_sequence` (a zip of PNGs plus a `manifest.json`)
+ * carry it, `mp4` does not and refuses the pair. The table is
+ * `timeline/outputFormats.ts`.
+ */
+import { BaseNode } from "@nodetool-ai/node-sdk";
+import type { DocumentRef, TimelineRef, VideoRef } from "@nodetool-ai/protocol";
+import type { ProcessingContext } from "@nodetool-ai/runtime";
+import { type TimelineSequence } from "@nodetool-ai/timeline";
+import { type ResolvedTimelineOutput } from "./timeline/outputFormats.js";
+/**
+ * linkIds of audio-track clips that are the detached audio representation of a
+ * video clip. The mere presence of such a clip means the linked video's own
+ * muxed audio must be suppressed (the editor mutes the video element; audio
+ * comes only from audio-track clips). This is intentionally NOT gated on
+ * mute/hidden — those govern whether the audio clip is mixed in, not whether
+ * the video's embedded audio resurfaces. If the user deletes the audio clip,
+ * the store auto-unlinks the lone survivor, clearing the video's linkId, so the
+ * video's audio returns on its own.
+ */
+export declare function extractedAudioLinkIds(seq: TimelineSequence): Set<string>;
+/** Add the sequence's audible tracks and embedded video audio to a composited video. */
+export declare function mixCompositedTimelineAudio(opts: {
+    sequence: TimelineSequence;
+    basePath: string;
+    workDir: string;
+    output: ResolvedTimelineOutput;
+    resolveAssetPath: (assetId: string) => Promise<string | null>;
+}): Promise<string>;
+/**
+ * The PNG-sequence archive on the `frames` handle. `DocumentRef` in the
+ * protocol declares only `uri` and `asset_id`; the document nodes' own refs
+ * carry `data` and `metadata` as well, and that is how a node hands fresh bytes
+ * to the next node.
+ */
+type TimelineFramesRef = DocumentRef & {
+    data?: string | null;
+    metadata?: Record<string, unknown> | null;
+};
+/** Output handles RenderTimelineNode.process() emits. */
+type RenderTimelineNodeOutputs = {
+    output: VideoRef;
+    frames: TimelineFramesRef;
+};
+export declare class RenderTimelineNode extends BaseNode {
+    static readonly nodeType = "nodetool.timeline.RenderTimeline";
+    static readonly title = "Render Timeline";
+    static readonly description = "Render a timeline sequence to a video, composited exactly as the timeline editor previews it (tracks, transforms, transitions, effects, captions and text), with audio mixed in at each clip's offset. Writes MP4, WebM, MOV or a zipped PNG sequence, with an optional transparent background.\n    timeline, render, video, export, cut, alpha\n\n    Use cases:\n    - Turn an edit assembled in the timeline editor into a shareable video\n    - Export a title or lower third over transparency to composite elsewhere\n    - Feed a rough cut into captioning, review, or upload nodes\n    - Automate exports of timelines built by other workflow nodes";
+    static readonly requiredRuntimes: string[];
+    static readonly metadataOutputTypes: {
+        output: string;
+        frames: string;
+    };
+    static readonly inlineFields: string[];
+    static readonly inputFields: string[];
+    timeline: TimelineRef;
+    include_audio: boolean;
+    format: string;
+    alpha: boolean;
+    video_codec: string;
+    motion_blur_samples: number;
+    shutter_angle: number;
+    bitrate: number;
+    preview_scale: number;
+    process(context?: ProcessingContext): Promise<RenderTimelineNodeOutputs>;
+    /**
+     * Refuse a format this ffmpeg cannot encode, by name.
+     *
+     * ProRes and VP9 are both optional at ffmpeg build time. Without this the
+     * render composites every frame first and then dies on ffmpeg's own
+     * "Unknown encoder" line, which says nothing about what to pick instead.
+     */
+    private assertEncoderAvailable;
+    /** Post on the node's log channel, where the run has one. */
+    private log;
+    /**
+     * A `node_progress` reporter for the frame loop, rate-limited to four posts a
+     * second. A minute of 1080p is thousands of frames and every post crosses the
+     * websocket; the final frame always posts, so the bar reaches its end.
+     */
+    private progressReporter;
+}
+/** Output handles TimelineTranscriptNode.process() emits. */
+type TimelineTranscriptNodeOutputs = {
+    text: string;
+    lines: string[];
+};
+export declare class TimelineTranscriptNode extends BaseNode {
+    static readonly nodeType = "nodetool.timeline.Transcript";
+    static readonly title = "Timeline Transcript";
+    static readonly description = "Extract the transcript of a timeline sequence as text.\n    timeline, transcript, text, script, voiceover\n\n    Use cases:\n    - Summarize or rewrite an edit's narration with an LLM\n    - Generate titles, descriptions, or chapters from the spoken script\n    - Translate a voiceover script before re-recording with TTS";
+    static readonly metadataOutputTypes: {
+        text: string;
+        lines: string;
+    };
+    static readonly inlineFields: string[];
+    static readonly inputFields: string[];
+    timeline: TimelineRef;
+    process(context?: ProcessingContext): Promise<TimelineTranscriptNodeOutputs>;
+}
+/**
+ * The content type to store a clip's bytes under.
+ *
+ * The stored asset's file extension and the `Content-Type` the browser is
+ * served both come from this, so guessing by media kind alone mislabels
+ * anything that is not the kind's default container: a WAV voiceover saved as
+ * `audio/mpeg` reaches the player as a `.mp3` it cannot decode. Read the bytes
+ * first, then the source URI's extension, and only then fall back to the kind.
+ */
+export declare function clipContentType(mediaType: string, bytes: Uint8Array, uri: string | undefined): string;
+/** Output handles AddClipsToTimelineNode.process() emits. */
+type AddClipsToTimelineNodeOutputs = {
+    output: {
+        type: string;
+        id: string;
+    };
+};
+export declare class AddClipsToTimelineNode extends BaseNode {
+    static readonly nodeType = "nodetool.timeline.AddClips";
+    static readonly title = "Add Clips To Timeline";
+    static readonly description = "Append media to a timeline sequence as clips (videos and images on the video track, audio on the audio track). Creates a new timeline when none is given.\n    timeline, clips, append, assemble, storyboard\n\n    Use cases:\n    - Assemble generated shots into an editable rough cut\n    - Turn a storyboard's images into an animatic\n    - Add a generated voiceover or soundtrack under an edit";
+    static readonly requiredRuntimes: string[];
+    static readonly metadataOutputTypes: {
+        output: string;
+    };
+    static readonly inlineFields: string[];
+    static readonly inputFields: string[];
+    timeline: TimelineRef;
+    clips: unknown[];
+    name: string;
+    image_duration_ms: number;
+    process(context?: ProcessingContext): Promise<AddClipsToTimelineNodeOutputs>;
+}
+/** Output handles FillTimelineTextNode.process() emits. */
+type FillTimelineTextNodeOutputs = {
+    timeline: {
+        type: string;
+        id: string;
+    };
+    filled: string[];
+    unresolved: string[];
+};
+export declare class FillTimelineTextNode extends BaseNode {
+    static readonly nodeType = "nodetool.timeline.FillTimelineText";
+    static readonly title = "Fill Timeline Text";
+    static readonly description = "Fill a template cut's {{key}} placeholders \u2014 in text clips and in captions \u2014 from a value bag, and save the result as a new timeline. The template is never written. A key with no value stays in the frame and is reported.\n    timeline, template, text, fill, batch\n\n    Use cases:\n    - Stamp a per-SKU name and price onto an approved cut\n    - Localize an overlay without re-editing the timeline\n    - Produce one variant per row of a feed";
+    static readonly metadataOutputTypes: {
+        timeline: string;
+        filled: string;
+        unresolved: string;
+    };
+    static readonly inlineFields: string[];
+    static readonly inputFields: string[];
+    timeline: TimelineRef;
+    values: Record<string, unknown>;
+    name: string;
+    process(context?: ProcessingContext): Promise<FillTimelineTextNodeOutputs>;
+}
+/** Output handles RetargetTimelineNode.process() emits. */
+type RetargetTimelineNodeOutputs = {
+    timeline: {
+        type: string;
+        id: string;
+    };
+    cropped: string[];
+};
+export declare class RetargetTimelineNode extends BaseNode {
+    static readonly nodeType = "nodetool.timeline.RetargetTimeline";
+    static readonly title = "Retarget Timeline";
+    static readonly description = "Derive a new timeline from an approved cut on another aspect ratio, keeping every trim, placement and edit. Cover scales each shot to fill the new frame and reports the clips it crops; contain letterboxes instead. Text sizes follow the short edge. The source cut is never written.\n    timeline, aspect ratio, resize, reframe, variant\n\n    Use cases:\n    - Turn a 16:9 film into 9:16 and 1:1 cuts\n    - Produce every placement's ratio from one approved edit\n    - See which shots lose their sides before rendering";
+    static readonly metadataOutputTypes: {
+        timeline: string;
+        cropped: string;
+    };
+    static readonly inlineFields: string[];
+    static readonly inputFields: string[];
+    timeline: TimelineRef;
+    aspect_ratio: string;
+    fit: "cover" | "contain";
+    name: string;
+    process(context?: ProcessingContext): Promise<RetargetTimelineNodeOutputs>;
+}
+export declare const TIMELINE_NODES: (typeof RenderTimelineNode | typeof TimelineTranscriptNode | typeof AddClipsToTimelineNode | typeof FillTimelineTextNode | typeof RetargetTimelineNode)[];
+export {};
+//# sourceMappingURL=timeline.d.ts.map

package/dist/nodes/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../src/nodes/timeline.ts"],"names":[],"mappings":"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"}