import type { BeatAnalysis } from './music-beats.js';
import type { TitleCue } from './titles.js';
import type { Edl } from './timeline-types.js';
export interface Shot {
    /** Source frame the shot starts on. */
    in: number;
    /** Hold for this many beats (needs a beat grid). */
    beats?: number;
    /** Hold for this many seconds (used when there is no beat grid, or the shot has no `beats`). */
    seconds?: number;
    label: string;
    /** Playback speed; the craft rule is 1.0 — slow-mo reads as a low framerate. */
    speed?: number;
    /** Draw (or suppress) the HUD replay over this shot; menus want `false`. */
    ui?: boolean;
    transition?: 'cut' | 'crossfade';
    transitionDuration?: number;
}
/** A title whose `at` may be the literal `"last-clip"`; `dur` is then the last clip's length. */
export type ShotTitle = Omit<TitleCue, 'at' | 'dur'> & {
    at: number | 'last-clip';
    dur?: number;
};
export interface ShotsFile {
    version: 1;
    /** Name of the recording these frame indices were chosen from. */
    recording?: string;
    /** Free-form notes the author keeps with the cut (never read by the tool). */
    notes?: string;
    shots: Shot[];
    titles?: ShotTitle[];
}
export interface CutOptions {
    /** Frames in the recording; a shot that would run past the end is shifted earlier and reported. */
    frameCount?: number;
}
export interface CutResult {
    edl: Edl;
    /** Beats consumed from the downbeat (0 without a grid). */
    beatsUsed: number;
    totalSec: number;
    /** Largest distance between a cut and its beat target, in ms (0 without a grid). */
    worstCutErrorMs: number;
    /** The first shot that did not fit in the track, when the grid ran out. */
    truncatedAt?: string;
}
/** Parse a shots document: either a bare array of shots or `{ version, shots, titles? }`. */
export declare function parseShots(raw: unknown, source: string): ShotsFile;
export declare function loadShots(filePath: string): ShotsFile;
/**
 * Turn shots into frame-exact clips. With `beats` every cut lands on the grid counted from the
 * downbeat; without, each shot's `seconds` decides its length. Returns the EDL plus the numbers
 * the command prints so the author can judge the fit.
 */
export declare function cutShots(shots: ShotsFile, beats: BeatAnalysis | null, fps: number, options?: CutOptions): CutResult;
/** The one-line summary `bitmagic trailer cut` prints, mirroring the Python script's. */
export declare function describeCut(result: CutResult, beats: BeatAnalysis | null): string;