ff-preview 0.18.0

//! Model-agnostic description of a timeline for the real-time preview runner.
//!
//! A [`Scene`] is the primitive seam between an editing engine and
//! [`SceneRunner`](super::runner::SceneRunner): it carries only the
//! model's primitivised fields (paths, durations, opacity, blend, animation
//! tracks), never the editing model itself. Resolving a `Scene` against the
//! media — probing for duration, audio presence, and frame size — happens in
//! [`ScenePlayer::open`](super::ScenePlayer::open), so a `Scene` re-derived on
//! every edit needs no re-probe and behaviour is preserved. An engine derives a
//! `Scene` from its own editing model; `Scene` is the only input the runner accepts.

use std::path::{Path, PathBuf};
use std::time::Duration;

use ff_filter::{AnimatedValue, RealtimeLayerDescriptor, XfadeTransition};
use ff_format::{Color, TextSpec};

// SceneSource

/// The video source backing a [`ScenePlacement`]: a decoded media file, or a
/// generated (solid-colour / text) source rendered without a file — the preview
/// counterpart of the engine's `ClipSource`. Generated sources are produced by
/// `ff-filter`'s `SolidSource` / `TextSource` (the same `color` / `drawtext`
/// filters the export path uses), so preview matches export.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SceneSource {
    /// A decoded media file at this path.
    File(PathBuf),
    /// A solid-colour fill for the whole canvas.
    Solid(Color),
    /// A text/title overlay rendered by `drawtext`.
    Text(TextSpec),
}

impl SceneSource {
    /// The file path when this is a [`File`](Self::File) source, else `None`
    /// (a generated source has no path). Used by the file-only open path.
    #[must_use]
    pub fn as_file(&self) -> Option<&Path> {
        match self {
            Self::File(path) => Some(path.as_path()),
            Self::Solid(_) | Self::Text(_) => None,
        }
    }
}

// Scene

/// A whole timeline's worth of playback work, described without the editing model.
#[derive(Debug, Clone)]
pub struct Scene {
    /// Presentation frame rate. Clamped to at least `1.0` by the runner.
    pub fps: f64,
    /// Explicit output canvas `(width, height)`, or `None` to size from the base track.
    pub canvas: Option<(u32, u32)>,
    /// Optional timeline-global `lavfi` filtergraph string (e.g.
    /// `color=s=1920x1080:c=black@0.0,drawtext=text='Title'`) generated and composited
    /// as the **topmost** video layer, matching the export path. `None` = no overlay.
    pub lavfi_overlay: Option<String>,
    /// Video tracks, composited bottom-up: index `0` is the V1 base, `1..` are overlays.
    pub video_tracks: Vec<SceneVideoTrack>,
    /// Dedicated audio-only tracks (A1, A2, …).
    pub audio_tracks: Vec<SceneAudioTrack>,
}

// SceneVideoTrack

/// One video track: an ordered list of clip placements along the timeline. The
/// track's index in [`Scene::video_tracks`] is its compositing order (`0` = base).
#[derive(Debug, Clone)]
pub struct SceneVideoTrack {
    /// Placements in timeline order.
    pub placements: Vec<ScenePlacement>,
}

// ScenePlacement

/// One video clip placed on the timeline.
///
/// Fields are pre-resolved model projections (e.g. `in_point` defaulted, `speed`
/// clamped, `xfade_dur` computed); media-dependent resolution (the effective
/// clip duration when `out_point` is `None`) is done by the runner at open time.
#[derive(Debug, Clone)]
pub struct ScenePlacement {
    /// Video source: a media file, or a generated (solid/text) source.
    pub source: SceneSource,
    /// Global timeline position where this placement starts.
    pub offset: Duration,
    /// Source-file PTS at which playback starts (`Clip::in_point`, defaulted to zero).
    pub in_point: Duration,
    /// Source-file PTS at which playback ends (`None` = play to EOF).
    pub out_point: Option<Duration>,
    /// Playback speed multiplier (`1.0` = normal), clamped to at least `0.01`.
    pub speed: f64,
    /// Crossfade duration from the previous placement into this one. Meaningful on
    /// the V1 base track only; `Duration::ZERO` = hard cut.
    pub xfade_dur: Duration,
    /// The `xfade` transition kind for this crossfade (V1 base track only). `None`
    /// when there is no transition; the runner defaults to `Fade` if a duration is
    /// set without a kind.
    pub xfade_kind: Option<XfadeTransition>,
    /// How far past `out_point` this placement may keep producing **video**, to feed
    /// the crossfade into the *next* placement. `Duration::ZERO` = not at all.
    ///
    /// A transition occupies the incoming placement head and blends it against these
    /// frames, so the outgoing placement has to survive that window without being
    /// lengthened: `out_point` stays where it is (it bounds this placement audio and
    /// its timeline extent), and only the video decode runs on.
    ///
    /// **Timeline time**, like `xfade_dur` — the runner converts to source time with
    /// `speed` where it compares against a source PTS.
    pub video_handle: Duration,
    /// Per-clip opacity in `[0.0, 1.0]`.
    pub opacity: f32,
    /// The dimension-free compositing description (effects, blend, position, and the
    /// opacity/position animation tracks). The runner realises it per frame via
    /// [`RealtimeLayer::with_dimensions`](ff_filter::RealtimeLayer::with_dimensions).
    pub layer: RealtimeLayerDescriptor,
    /// Audio fade-in duration (`Duration::ZERO` = none).
    pub fade_in: Duration,
    /// Audio fade-out duration (`Duration::ZERO` = none).
    pub fade_out: Duration,
    /// Resolved audio gain (dB), static or animated. A static value is applied once at
    /// open; an animated one is evaluated per tick.
    pub volume: AnimatedValue<f64>,
    /// Per-clip audio pitch shift in semitones (`0.0` = none). A set `pitch_track`
    /// is evaluated at its `t=0` value (static, per ADR-0002); the preview applies
    /// it duration-preserving, matching the export shift at the model level.
    pub pitch: f64,
    /// Resolved stereo pan (`-1.0` left .. `+1.0` right, `0.0` center), static or
    /// animated. Applied once at open at its `t=0` value; per-sample pan automation
    /// is a deferred capability, so an animated pan uses its initial value (matching
    /// the export mixer).
    pub pan: AnimatedValue<f64>,
}

// SceneAudioTrack

/// One dedicated audio-only track (A1, A2, …).
#[derive(Debug, Clone)]
pub struct SceneAudioTrack {
    /// Placements in timeline order.
    pub placements: Vec<SceneAudioPlacement>,
}

// SceneAudioPlacement

/// One audio-only clip placed on the timeline.
#[derive(Debug, Clone)]
pub struct SceneAudioPlacement {
    /// Source media path.
    pub source: PathBuf,
    /// Global timeline position where this placement starts.
    pub offset: Duration,
    /// Source-file PTS at which playback starts (defaulted to zero).
    pub in_point: Duration,
    /// Source-file PTS at which playback ends (`None` = play to EOF).
    pub out_point: Option<Duration>,
    /// Playback speed multiplier (`1.0` = normal), clamped to at least `0.01`,
    /// applied by resampling.
    pub speed: f64,
    /// Audio fade-in duration (`Duration::ZERO` = none).
    pub fade_in: Duration,
    /// Audio fade-out duration (`Duration::ZERO` = none).
    pub fade_out: Duration,
    /// Resolved audio gain (dB), static or animated. A static value is applied once at
    /// open; an animated one is evaluated per tick.
    pub volume: AnimatedValue<f64>,
    /// Per-clip audio pitch shift in semitones (`0.0` = none). A set `pitch_track`
    /// is evaluated at its `t=0` value (static, per ADR-0002); the preview applies
    /// it duration-preserving, matching the export shift at the model level.
    pub pitch: f64,
    /// Resolved stereo pan (`-1.0` left .. `+1.0` right, `0.0` center), static or
    /// animated. Applied once at open at its `t=0` value; per-sample pan automation
    /// is a deferred capability, so an animated pan uses its initial value (matching
    /// the export mixer).
    pub pan: AnimatedValue<f64>,
}