@a-company/atelier 0.29.0 → 0.37.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { AtelierDocument } from '@a-company/atelier-types';
+import { AtelierDocument, StudioRecipe, VideoProjectManifest, CutEntry, VideoCutList, VideoTranscript, Layer, Delta, TranscriptWord } from '@a-company/atelier-types';
 import { ResolvedFrame } from '@a-company/atelier-core';
 
 /**
@@ -85,6 +85,182 @@ declare function exportSvgCommand(program: Command): void;
 /** Register the `export-lottie` subcommand on the Commander program. */
 declare function exportLottieCommand(program: Command): void;
 
+/**
+ * Shared single-frame render-to-PNG path.
+ *
+ * Extracted from `atelier export-image` so the carousel batch driver and the
+ * single-frame export command render through one code path. Rasterizes via
+ * `@napi-rs/canvas` — a Canvas2D implementation shipped as prebuilt platform
+ * binaries, so PNG export works on a plain install with no node-gyp build and
+ * no system libraries (cairo/pango/etc.). Pre-loads any ImageVisual layers via
+ * its `loadImage` (file path / data-URL / buffer all work server-side, the same
+ * mechanism the MP4 render-pipeline uses) and renders one resolved frame scaled
+ * to the requested output dimensions.
+ */
+
+/** @napi-rs/canvas surface — the subset this module touches. */
+interface NodeCanvas {
+    getContext(id: "2d"): unknown;
+    toBuffer(format: "image/png"): Buffer;
+}
+/** A loaded image — width/height are the natural pixel dims. */
+interface LoadedImage {
+    width: number;
+    height: number;
+}
+/** Canvas module surface (createCanvas + loadImage). */
+interface CanvasModule {
+    createCanvas: (w: number, h: number) => NodeCanvas;
+    loadImage: (src: string) => Promise<LoadedImage>;
+}
+/** Bounds + centered frame for fitting an image into a canvas. */
+interface ImageFitResult {
+    bounds: {
+        width: number;
+        height: number;
+    };
+    frame: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Fit a natural-sized image into a canvas while preserving aspect ratio,
+ * centered. Adapted from studio's image-drop helper (kept local so the CLI's
+ * server-side render path doesn't import the browser studio package).
+ *
+ * Landscape (wider than canvas) → fit to width; portrait (taller or equal) →
+ * fit to height; both dims capped at the canvas extents. Degenerate natural
+ * sizes fall back to canvas extents so callers always get valid bounds.
+ */
+declare function fitImageToCanvas(canvas: {
+    width: number;
+    height: number;
+}, natural: {
+    width: number;
+    height: number;
+}): ImageFitResult;
+/**
+ * Raised when the `@napi-rs/canvas` rasterizer cannot be loaded. In practice
+ * this never fires: `@napi-rs/canvas` is a hard dependency that ships prebuilt
+ * platform binaries (no node-gyp, no system libraries). It can only happen if
+ * the install is corrupt or running on an unsupported platform with no prebuilt
+ * binary — in which case a reinstall is the fix. Kept as a typed seam so call
+ * sites can still distinguish a missing-rasterizer failure from a bad document.
+ */
+declare class CanvasUnavailableError extends Error {
+    constructor();
+}
+/**
+ * Resolve the canvas module. `@napi-rs/canvas` is a hard, statically-imported
+ * dependency, so this is a thin accessor that surfaces a typed
+ * {@link CanvasUnavailableError} on the (essentially impossible) chance the
+ * platform binary failed to load.
+ */
+declare function loadCanvasModule(): Promise<CanvasModule>;
+/**
+ * Compute final output dimensions from the document canvas and optional
+ * width/height overrides. When only one of width/height is provided, the
+ * other is derived to preserve the document's aspect ratio. When both are
+ * provided, both are used verbatim (allows non-uniform scaling).
+ */
+declare function resolveExportDimensions(docWidth: number, docHeight: number, width?: number, height?: number): {
+    width: number;
+    height: number;
+};
+interface RenderToPngOptions {
+    /** State to resolve (defaults to the first state). */
+    state?: string;
+    /** Frame within the state (defaults to 0). */
+    frame?: number;
+    /** Output width override (px). */
+    width?: number;
+    /** Output height override (px). */
+    height?: number;
+    /**
+     * Optional hook to adjust each image layer's bounds once natural dimensions
+     * are known from the loaded image. Receives the layer src + natural dims and
+     * the doc canvas; returns new bounds (and frame). Used by the carousel driver
+     * to aspect-fit fit-to-canvas images that were composed with placeholder
+     * bounds (natural dims are unknown until the rasterizer decodes the file).
+     */
+    refitImageBounds?: (args: {
+        canvas: {
+            width: number;
+            height: number;
+        };
+        natural: {
+            width: number;
+            height: number;
+        };
+    }) => {
+        bounds: {
+            width: number;
+            height: number;
+        };
+        frame: {
+            x: number;
+            y: number;
+        };
+    };
+}
+/**
+ * Render a single resolved frame of a document to a PNG buffer.
+ *
+ * Validates state/frame, pre-loads image layers, scales rendering to fit the
+ * requested output dimensions, and returns the encoded PNG bytes. Throws
+ * {@link CanvasUnavailableError} when the rasterizer is missing and a plain
+ * Error for bad state/frame selection.
+ */
+declare function renderDocumentToPng(doc: AtelierDocument, opts?: RenderToPngOptions): Promise<Buffer>;
+
+/** Register the `export-image` subcommand on the Commander program. */
+declare function exportImageCommand(program: Command): void;
+
+/**
+ * Expand an --inputs pattern into a sorted list of absolute image file paths.
+ *
+ * Deliberately minimal (no new glob dependency): supports a directory path
+ * (lists all image files within), a single file path, or a single-segment
+ * `*`-glob in the final path component (e.g. `shots/*.png`, `shots/img-*`).
+ * Multi-segment / recursive globs are out of scope — point --inputs at a
+ * directory instead. The returned list is filtered to image extensions and
+ * sorted lexicographically so output ordering is stable.
+ */
+declare function expandInputs(pattern: string): string[];
+/**
+ * Build a single-frame carousel document for one image: a canvas-sized doc with
+ * a background and one fit-to-canvas ImageVisual layer, then the recipe's
+ * overlay_rules applied with currentIndex/totalCount threaded so the page-number
+ * overlay renders "i/N".
+ *
+ * Pure + synchronous (no node-canvas): image bounds use the canvas-extent
+ * fallback because natural dimensions aren't known until node-canvas decodes
+ * the file at render time. {@link renderDocumentToPng} re-fits the bounds via
+ * `refitImageBounds` once the image is loaded.
+ */
+declare function composeCarouselFrameDoc(args: {
+    imagePath: string;
+    index: number;
+    total: number;
+    width: number;
+    height: number;
+    recipe: StudioRecipe;
+    background?: string;
+}): AtelierDocument;
+/** Zero-padded sortable filename prefix: width = max(2, digits in N). */
+declare function carouselFileName(index: number, total: number, imagePath: string): string;
+/**
+ * Register `atelier carousel <recipe> --inputs <glob> --out-dir <dir>` — batch
+ * compose a folder of images into recipe-overlaid PNGs.
+ *
+ * For each image i of N: build a fit-to-canvas doc, apply the recipe's
+ * overlay_rules with currentIndex=i / totalCount=N (handle + "i/N" page-number),
+ * render via the shared export-image path, and write a zero-padded sortable
+ * PNG into --out-dir.
+ */
+declare function carouselCommand(program: Command): void;
+
 /** Asset summary entry */
 interface AssetInfo {
     assetId: string;
@@ -159,4 +335,410 @@ declare function buildFfmpegArgs(width: number, height: number, fps: number, for
  */
 declare function renderDocument(doc: AtelierDocument, opts: RenderOptions): Promise<RenderResult>;
 
-export { type AssetInfo, type DocumentInfo, type ProgressInfo, type RenderFormat, type RenderOptions, type RenderResult, type VariableInfo, assetsCommand, buildFfmpegArgs, checkFfmpeg, exportLottieCommand, exportSvgCommand, getAssets, getInfo, getVariables, infoCommand, renderCommand, renderDocument, resolveStill, stillCommand, validateCommand, validateFile, variablesCommand };
+declare const VIDEO_PROJECT_VERSION = "1.0";
+declare const VIDEO_CUTLIST_VERSION = "1.1";
+declare const VIDEO_TRANSCRIPT_VERSION = "1.1";
+/**
+ * Compute the effective in/out span for a cut, clamped to source bounds.
+ * `start = max(0, rawStart - paddingPre)`, `end = min(duration, rawEnd + paddingPost)`.
+ */
+declare function effectiveSpan(cut: CutEntry, duration: number): {
+    start: number;
+    end: number;
+};
+/** Resolved absolute paths for all files in a VideoProject folder */
+interface VideoProject {
+    /** Absolute path to the project folder */
+    dir: string;
+    /** Absolute path to source video file */
+    sourcePath: string;
+    /** Absolute path to project.atelier composition */
+    compositionPath: string;
+    /** Absolute path to transcript.json */
+    transcriptPath: string;
+    /** Absolute path to cuts.json */
+    cutsPath: string;
+    /** Absolute path to export/ directory */
+    exportDir: string;
+    /** Manifest metadata */
+    manifest: VideoProjectManifest;
+}
+/**
+ * Scaffold a new VideoProject folder from a source video file.
+ *
+ * Creates the folder at `destDir` (defaults to same directory as source,
+ * named after the video file without extension). Copies the source video
+ * into the folder as "source<ext>". Writes an empty draft project.atelier,
+ * an empty cuts.json, and creates the export/ directory.
+ *
+ * Does NOT run metadata extraction — the caller (`atelier edit`, T-005)
+ * probes duration/fps via ffprobe and fills in videoMeta before saving.
+ */
+declare function createVideoProject(srcPath: string, destDir?: string): Promise<VideoProject>;
+/**
+ * Load an existing VideoProject from a folder path.
+ * Does not validate that the composition or cut list are well-formed —
+ * callers that need that should use lintFile() after loading.
+ */
+declare function loadVideoProject(dir: string): VideoProject;
+/**
+ * Read and parse cuts.json from a VideoProject.
+ *
+ * Migrates legacy 1.0 cuts (flat { start, end }) to 1.1 parametric form
+ * (rawStart/rawEnd + zero padding) on the fly. Writers always emit 1.1.
+ */
+declare function readCutList(project: VideoProject): VideoCutList;
+/** Write cuts.json to a VideoProject (always at the current cut list version) */
+declare function writeCutList(project: VideoProject, cuts: VideoCutList): void;
+/**
+ * Read and parse transcript.json from a VideoProject.
+ *
+ * Migrates legacy 1.0 transcripts (TranscriptWord had flat `word: string`)
+ * to 1.1 (`detected` + `text` + flags) on the fly. Writers always emit 1.1.
+ */
+declare function readTranscript(project: VideoProject): VideoTranscript | null;
+/** Write transcript.json to a VideoProject (always at the current transcript version) */
+declare function writeTranscript(project: VideoProject, transcript: VideoTranscript): void;
+/** Read and parse project.atelier from a VideoProject */
+declare function readComposition(project: VideoProject): AtelierDocument;
+/** Write project.atelier to a VideoProject */
+declare function writeComposition(project: VideoProject, doc: AtelierDocument): void;
+/**
+ * Rewrite the silence-trim layers in a composition from a current cut list.
+ *
+ * Drops every layer tagged "silence-trim" then appends one VideoVisual layer
+ * per cut, in temporal order, with cumulative startFrame computed from prior
+ * clip durations. All other layers (user-authored, captions, overlays) are
+ * preserved untouched — this is the tag-namespace isolation invariant.
+ */
+declare function rewriteCutLayers(doc: AtelierDocument, cuts: CutEntry[], sourceFilename: string, sourceDuration: number, assetId?: string): AtelierDocument;
+
+interface TrimOptions {
+    /** silencedetect noise threshold, e.g. "-30dB" */
+    noise?: string;
+    /** Minimum silence duration to register, in seconds */
+    minSilence?: number;
+    /** Default leading padding for new cuts, in seconds */
+    padPre?: number;
+    /** Default trailing padding for new cuts, in seconds */
+    padPost?: number;
+    /** Re-detect match tolerance for preserving user padding, in seconds */
+    matchTolerance?: number;
+    /** Global tighten across all cuts, in milliseconds (positive number) */
+    tightenMs?: number;
+    /** Global loosen across all cuts, in milliseconds (positive number) */
+    loosenMs?: number;
+    /** Apply --pad-pre / --pad-post to one specific cut index only */
+    cutIndex?: number;
+    /** Discard existing padding; full fresh detect with default padding */
+    reset?: boolean;
+    /** Don't write files; return result */
+    dryRun?: boolean;
+}
+interface TrimResult {
+    projectDir: string;
+    duration: number;
+    cuts: CutEntry[];
+    layerCount: number;
+}
+/**
+ * Run the silence-trim pipeline on a VideoProject folder.
+ *
+ * Pipeline:
+ *   1. Probe ffmpeg has silencedetect filter
+ *   2. ffprobe source duration
+ *   3. Run silencedetect → silence intervals
+ *   4. Invert to speech intervals
+ *   5. Build fresh CutEntry[] with default (or recipe) padding
+ *   6. Merge with existing cuts (preserves user padding) unless --reset
+ *   7. Apply --tighten / --loosen / --cut overrides
+ *   8. Resolve overlaps at silence midpoints
+ *   9. Clamp boundaries to [0, duration]
+ *   10. Write cuts.json + rewrite silence-trim layers in project.atelier
+ */
+declare function trimProject(projectDir: string, options?: TrimOptions): Promise<TrimResult>;
+/** Register `atelier trim` on the Commander program */
+declare function trimCommand(program: Command): void;
+
+/** Whisper model selection (size/quality tradeoff) */
+type WhisperModel = "tiny" | "tiny.en" | "base" | "base.en" | "small" | "small.en" | "medium" | "medium.en" | "large-v3";
+interface WhisperOptions {
+    /** Model size (default: "base.en") */
+    model?: WhisperModel;
+    /** BCP-47 language hint (omit for autodetect) */
+    language?: string;
+    /** Explicit path to the model file — overrides model lookup by name */
+    modelPath?: string;
+}
+/** Backend that produced a transcript run */
+type WhisperBackend = "whisper-cpp" | "openai-api" | "none";
+/**
+ * Probe which Whisper backend is available on this machine.
+ * - "whisper-cpp" if `whisper-cli` is on PATH
+ * - "openai-api" if OPENAI_API_KEY is set and --use-api requested
+ * - "none" otherwise — caller throws with install guidance
+ */
+declare function probeWhisper(): Promise<WhisperBackend>;
+/**
+ * Run whisper.cpp on a source file and return the raw JSON stdout.
+ * Caller passes to parseWhisperCppJson() to get a VideoTranscript.
+ *
+ * Note: whisper-cli writes JSON to stdout when given --output-json and "-"
+ * as the output destination. Some builds always write to a file with the
+ * `.json` suffix appended to the input path; we handle both.
+ */
+declare function runWhisperCpp(sourcePath: string, options?: WhisperOptions): Promise<string>;
+/**
+ * Parse whisper.cpp --output-json output into a VideoTranscript.
+ *
+ * whisper.cpp emits a structure like:
+ *   {
+ *     "result": { "language": "en" },
+ *     "transcription": [
+ *       {
+ *         "timestamps": { "from": "00:00:00,000", "to": "00:00:02,300" },
+ *         "offsets":    { "from": 0,                "to": 2300 },
+ *         "text": " Hello world",
+ *         "tokens": [ ... ]   // optional per-token detail
+ *       }
+ *     ]
+ *   }
+ *
+ * Token-level word timestamps come via the "tokens" array on each segment
+ * when --output-json-full is used. With --output-json (lighter), only
+ * segment-level boundaries are present and we synthesize word timing by
+ * even split across the segment.
+ *
+ * Exported for unit testing.
+ */
+declare function parseWhisperCppJson(jsonStr: string): VideoTranscript;
+
+/** Default style for generated caption layers — overridable by Studio Recipe */
+interface CaptionStyle {
+    fontFamily?: string;
+    fontSize?: number;
+    fontWeight?: number | "normal" | "bold";
+    textAlign?: "left" | "center" | "right";
+    color?: string;
+    /** Relative vertical position 0–1 (0 = top, 1 = bottom). Default 0.85 — lower-third. */
+    yRatio?: number;
+    /** Horizontal width as ratio of canvas width. Default 0.9. */
+    widthRatio?: number;
+    /** Fade duration in seconds for opacity in/out. Default 0.05 (3 frames at 60fps). */
+    fadeSeconds?: number;
+}
+interface BuildCaptionsOptions {
+    style?: CaptionStyle;
+    /** Phrase grouping — max words per caption phrase */
+    maxWords?: number;
+    /** Phrase grouping — pause gap in seconds that forces a phrase break */
+    pauseGap?: number;
+}
+/**
+ * Build caption-tagged TextVisual layers from a transcript + canvas dimensions.
+ *
+ * Each phrase becomes one Layer with:
+ *  - tags: ["caption"]
+ *  - TextVisual with merged style
+ *  - opacity: 0 (default; deltas animate to 1 during the phrase)
+ *  - positioned at canvas.width * 0.5, canvas.height * yRatio
+ *
+ * Caller is responsible for appending these to a state's deltas array
+ * (returned alongside the layers as Delta[] keyed to layer id).
+ */
+declare function buildCaptionLayers(transcript: VideoTranscript, canvas: AtelierDocument["canvas"], options?: BuildCaptionsOptions): {
+    layers: Layer[];
+    deltas: Delta[];
+};
+/**
+ * Drop caption-tagged layers + their deltas from a composition,
+ * append fresh ones from the current transcript.
+ *
+ * Mirrors rewriteCutLayers' invariant: only caption-tagged layers touched;
+ * all other layers (silence-trim, overlay, user-authored) preserved.
+ *
+ * Deltas are written into the default state (or first state if no "default").
+ */
+declare function rewriteCaptionLayers(doc: AtelierDocument, transcript: VideoTranscript, options?: BuildCaptionsOptions): AtelierDocument;
+
+interface TranscribeOptions {
+    /** Whisper model selection */
+    model?: WhisperModel;
+    /** BCP-47 language hint (omit for autodetect) */
+    language?: string;
+    /** Discard existing user edits; full fresh transcript */
+    reset?: boolean;
+    /** Skip caption layer generation; transcript.json only */
+    noCaptions?: boolean;
+    /** Don't write files; return result */
+    dryRun?: boolean;
+    /** Caption style + grouping overrides, typically supplied by a Studio Recipe */
+    captionOptions?: BuildCaptionsOptions;
+}
+interface TranscribeResult {
+    projectDir: string;
+    backend: string;
+    transcript: VideoTranscript;
+    wordCount: number;
+    captionsGenerated: boolean;
+}
+/**
+ * Run the transcription pipeline on a VideoProject folder.
+ *
+ * Pipeline:
+ *   1. Probe Whisper backend (whisper-cpp / openai-api / none)
+ *   2. Run Whisper → raw transcript JSON
+ *   3. Parse into VideoTranscript shape
+ *   4. Merge with existing transcript (preserves user edits) unless --reset
+ *   5. Write transcript.json
+ *   6. Unless --no-captions: rewriteCaptionLayers in project.atelier
+ */
+declare function transcribeProject(projectDir: string, options?: TranscribeOptions): Promise<TranscribeResult>;
+/** Register `atelier transcribe` on the Commander program */
+declare function transcribeCommand(program: Command): void;
+
+/** Register the `atelier transcript` family of edit subcommands */
+declare function transcriptCommand(program: Command): void;
+
+/** Register `atelier captions regenerate <project>` */
+declare function captionsCommand(program: Command): void;
+
+/**
+ * Flatten a VideoTranscript's segments into a single ordered word array.
+ * Used by edit commands that take a global word index.
+ */
+declare function flattenWords(transcript: VideoTranscript): TranscriptWord[];
+/**
+ * Phrase block — one rendered caption layer's worth of words.
+ */
+interface CaptionPhrase {
+    start: number;
+    end: number;
+    text: string;
+    words: TranscriptWord[];
+}
+/**
+ * Group transcript words into caption-sized phrases.
+ *
+ * Emits a new phrase when ANY of:
+ *  - currentPhrase.length >= maxWords
+ *  - currentWord.text ends in . ! ? , ; :
+ *  - gap between currentWord and nextWord > pauseGap seconds
+ *
+ * Hidden words are skipped (do not appear in captions but still in transcript).
+ */
+declare function groupIntoPhrases(transcript: VideoTranscript, options?: {
+    maxWords?: number;
+    pauseGap?: number;
+}): CaptionPhrase[];
+/**
+ * Merge a freshly-detected transcript with an existing one, preserving user
+ * edits (userEdited / userAdded / hidden + text override) on any word whose
+ * raw boundary still matches within `tolerance` seconds AND whose `detected`
+ * string is unchanged.
+ *
+ * userAdded words in the existing transcript have no matching fresh entry by
+ * definition — they're preserved as orphans, inserted into the appropriate
+ * segment by timing.
+ */
+declare function mergeTranscriptWithExisting(fresh: VideoTranscript, existing: VideoTranscript, tolerance?: number): VideoTranscript;
+/**
+ * Replace the text of word at the given global index. Sets userEdited=true.
+ * Returns a new VideoTranscript; does not mutate input.
+ */
+declare function applyTextEdit(transcript: VideoTranscript, wordIndex: number, newText: string): VideoTranscript;
+/**
+ * Apply a batch find/replace across all detected words.
+ * Sets userEdited=true on every word whose detected text matches `find`.
+ */
+declare function applyBatchReplace(transcript: VideoTranscript, find: string, replace: string): VideoTranscript;
+/** Hide a word (excluded from caption render, kept in transcript). Sets hidden=true. */
+declare function applyHide(transcript: VideoTranscript, wordIndex: number): VideoTranscript;
+/**
+ * Insert a user-added word after the given global index.
+ * Sets userAdded=true. Duration defaults to 0.15s if not specified.
+ * Word is placed in the segment containing the anchor word.
+ */
+declare function applyAdd(transcript: VideoTranscript, afterIndex: number, text: string, duration?: number): VideoTranscript;
+/**
+ * Merge adjacent words at indices i and i+1 into a single word.
+ * The merged word's detected/text becomes the concatenation; timing spans both.
+ * Sets userEdited=true.
+ */
+declare function applyMerge(transcript: VideoTranscript, firstIndex: number): VideoTranscript;
+/**
+ * Split one word at the given fractional point (0–1). Timing prorates.
+ * Sets userEdited=true on both halves. `firstText` and `secondText` default
+ * to slicing the original text at its character midpoint.
+ */
+declare function applySplit(transcript: VideoTranscript, wordIndex: number, fraction: number, firstText?: string, secondText?: string): VideoTranscript;
+
+/** Register `atelier recipe new/validate/show` family */
+declare function recipeCommand(program: Command): void;
+
+/**
+ * Register `atelier apply-recipe <project> <recipe>` — convenience verb that
+ * runs `atelier trim` and `atelier transcribe` against the same recipe in
+ * one shot. Useful for fresh-project bootstrap.
+ */
+declare function applyRecipeCommand(program: Command): void;
+
+declare const RECIPE_VERSION = "1.0";
+interface LoadedRecipe {
+    recipe: StudioRecipe;
+    /** Absolute path the recipe was read from */
+    path: string;
+    /** Warnings from validateRecipe (e.g. reserved-field usage) */
+    warnings: string[];
+}
+/**
+ * Resolve a recipe reference to an absolute path.
+ *
+ * Resolution order (per studio-recipe.md §6.2):
+ *   1. <projectDir>/.atelier/recipes/<name>.recipe.{yaml,json}
+ *   2. ~/.atelier/recipes/<name>.recipe.{yaml,json}
+ *   3. The literal path passed (absolute or relative to cwd)
+ *
+ * Absolute paths and paths containing slashes skip resolution and load directly.
+ */
+declare function resolveRecipePath(pathOrName: string, projectDir?: string): string;
+/**
+ * Load and validate a recipe from a path or name.
+ *
+ * Sniffs YAML vs JSON by file extension; falls back to YAML parser when
+ * unclear (YAML is a superset of JSON for objects).
+ */
+declare function loadRecipe(pathOrName: string, projectDir?: string): LoadedRecipe;
+/**
+ * Generate a starter recipe YAML with every Phase 1 field present and
+ * inline comments documenting it. Authors learn the shape by editing.
+ */
+declare function scaffoldRecipeYaml(name: string): string;
+/**
+ * Merge a recipe's silence_policy into TrimOptions.
+ * CLI options take precedence (per studio-recipe.md §4.1).
+ */
+declare function applyRecipeToTrimOptions(recipe: StudioRecipe | undefined, cliOptions: TrimOptions): TrimOptions;
+/**
+ * Translate a recipe's caption_style + caption_grouping into runtime
+ * BuildCaptionsOptions for the caption builder.
+ *
+ * CLI doesn't currently expose per-invocation caption styling flags;
+ * the recipe is the canonical source for now.
+ */
+declare function applyRecipeToCaptionOptions(recipe: StudioRecipe | undefined): BuildCaptionsOptions;
+/**
+ * Merge a recipe into TranscribeOptions. Caption-related recipe fields
+ * are stashed on the transcribe options so the orchestrator can pass them
+ * through to rewriteCaptionLayers.
+ */
+declare function applyRecipeToTranscribeOptions(recipe: StudioRecipe | undefined, cliOptions: TranscribeOptions): TranscribeOptions;
+/**
+ * Render a recipe's effective values (recipe overlaid on code defaults).
+ * Used by `atelier recipe show --with-defaults`.
+ */
+declare function renderRecipeWithDefaults(recipe: StudioRecipe): StudioRecipe;
+/** Serialize a recipe back to YAML for `recipe show` output */
+declare function recipeToYaml(recipe: StudioRecipe): string;
+
+export { type AssetInfo, type BuildCaptionsOptions, CanvasUnavailableError, type CaptionStyle, type DocumentInfo, type LoadedRecipe, type ProgressInfo, RECIPE_VERSION, type RenderFormat, type RenderOptions, type RenderResult, type TranscribeOptions, type TranscribeResult, type TrimOptions, type TrimResult, VIDEO_CUTLIST_VERSION, VIDEO_PROJECT_VERSION, VIDEO_TRANSCRIPT_VERSION, type VariableInfo, type VideoProject, type WhisperBackend, type WhisperModel, type WhisperOptions, applyAdd, applyBatchReplace, applyHide, applyMerge, applyRecipeCommand, applyRecipeToCaptionOptions, applyRecipeToTranscribeOptions, applyRecipeToTrimOptions, applySplit, applyTextEdit, assetsCommand, buildCaptionLayers, buildFfmpegArgs, captionsCommand, carouselCommand, carouselFileName, checkFfmpeg, composeCarouselFrameDoc, createVideoProject, effectiveSpan, expandInputs, exportImageCommand, exportLottieCommand, exportSvgCommand, fitImageToCanvas, flattenWords, getAssets, getInfo, getVariables, groupIntoPhrases, infoCommand, loadCanvasModule, loadRecipe, loadVideoProject, mergeTranscriptWithExisting, parseWhisperCppJson, probeWhisper, readComposition, readCutList, readTranscript, recipeCommand, recipeToYaml, renderCommand, renderDocument, renderDocumentToPng, renderRecipeWithDefaults, resolveExportDimensions, resolveRecipePath, resolveStill, rewriteCaptionLayers, rewriteCutLayers, runWhisperCpp, scaffoldRecipeYaml, stillCommand, transcribeCommand, transcribeProject, transcriptCommand, trimCommand, trimProject, validateCommand, validateFile, variablesCommand, writeComposition, writeCutList, writeTranscript };