Skip to content

The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.

docs(project): document the whole public surface; adopt workspace lints

Jareera3c51acd7d40
diff --git a/engine/crates/wolfcut-project/Cargo.toml b/engine/crates/wolfcut-project/Cargo.toml
index c1c3cb07..1a7696a4 100644
--- a/engine/crates/wolfcut-project/Cargo.toml
+++ b/engine/crates/wolfcut-project/Cargo.toml
@@ -9,3 +9,6 @@ description = "The edit itself: the project document, its operations, and undo.
[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json.workspace = true
+
+[lints]
+workspace = true
diff --git a/engine/crates/wolfcut-project/src/commands.rs b/engine/crates/wolfcut-project/src/commands.rs
index 323dc64d..9b9ef519 100644
--- a/engine/crates/wolfcut-project/src/commands.rs
+++ b/engine/crates/wolfcut-project/src/commands.rs
@@ -29,17 +29,25 @@ const MAX_OFFSET: f64 = 3.0;
/// How far apart two clips may sit and still count as touching, in seconds.
const JOIN_EPSILON: f64 = 1e-6;
+/// Which end of a clip a trim drags. The two are not symmetric: see
+/// [`Command::TrimClip`].
#[derive(Clone, Copy, PartialEq, Eq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum TrimEdge {
+ /// The head. Trimming here moves the in-point with the edge, so the
+ /// remaining frames stay where they were on the timeline.
Start,
+ /// The tail. Trimming here only lengthens or shortens the clip.
End,
}
+/// Which per-track toggle a [`Command::SetTrackFlag`] flips.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum TrackFlag {
+ /// [`Track::visible`]: whether the track's video reaches the composite.
Visible,
+ /// [`Track::muted`]: whether the track's audio is silenced.
Muted,
}
@@ -47,8 +55,13 @@ pub enum TrackFlag {
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ClipMove {
+ /// The clip to move. An unknown id is skipped, not an error - the rest
+ /// of the batch of moves still lands.
pub clip_id: String,
+ /// New timeline position in seconds, floored at 0.
pub start: f64,
+ /// Destination track. An unknown id moves the clip in time but leaves it
+ /// on its current track.
pub track_id: String,
}
@@ -58,16 +71,31 @@ pub struct ClipMove {
#[derive(Clone, Default, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ClipPatch {
+ /// New display name, taken verbatim. A later `text` patch overwrites it
+ /// with the title's first line.
pub name: Option<String>,
+ /// New gain; floored at 0, deliberately not capped at 1 - boosting quiet
+ /// footage is legitimate.
pub volume: Option<f64>,
+ /// New fade-in length in seconds, floored at 0.
pub fade_in: Option<f64>,
+ /// New fade-out length in seconds, floored at 0.
pub fade_out: Option<f64>,
+ /// New opacity, clamped into 0..=1.
pub opacity: Option<f64>,
+ /// New pitch-preservation setting, taken as sent.
pub preserve_pitch: Option<bool>,
+ /// Wholesale replacement of the audio filter chain - the UI sends the
+ /// full list, not a diff.
pub filters: Option<Vec<AppliedFilter>>,
+ /// Wholesale replacement of the video effect chain, like `filters`.
pub video_effects: Option<Vec<AppliedFilter>>,
+ /// The transition on the cut into the clip: absent leaves it alone,
+ /// null clears it, a value replaces it.
#[serde(default, with = "double_option", skip_serializing_if = "Option::is_none")]
pub transition_in: Option<Option<Transition>>,
+ /// The title styling, same three-way wire semantics as `transition_in`.
+ /// Setting a style also renames the clip after its first line.
#[serde(default, with = "double_option", skip_serializing_if = "Option::is_none")]
pub text: Option<Option<TextStyle>>,
}
@@ -97,32 +125,106 @@ mod double_option {
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct NewMedia {
+ /// Absolute path on disk. Adding a path already in the bin is a no-op,
+ /// so re-imports cannot duplicate media.
pub path: String,
+ /// Display name for the bin, normally the file's basename.
pub name: String,
+ /// Seconds, or None when the container did not report one - clips of
+ /// such media get a five-second fallback length.
pub duration: Option<f64>,
+ /// What the host's probe decided the file is.
pub kind: MediaKind,
+ /// Pixel width, when the probe found one.
pub width: Option<u32>,
+ /// Pixel height, same terms as `width`.
pub height: Option<u32>,
+ /// Frames per second as a decimal, for display.
pub frame_rate: Option<f64>,
+ /// The exact rate fraction the engine works in, e.g. "30000/1001".
pub frame_rate_fraction: Option<String>,
+ /// Codec name as probed, e.g. "h264". Informational.
pub video_codec: Option<String>,
+ /// Codec of the embedded audio, when there is any.
pub audio_codec: Option<String>,
+ /// Whether the file carries an audio stream.
pub has_audio: bool,
}
+/// Every edit, as the UI sends it over IPC: a tagged `op` plus camelCase
+/// fields. [`apply`] is the single place each variant's meaning lives; the
+/// notes here state the contract - clamps, tolerances, what gets minted -
+/// so a caller need not read `apply` to know what a command will do.
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
#[serde(tag = "op", rename_all = "camelCase", rename_all_fields = "camelCase")]
pub enum Command {
- AddMedia { item: NewMedia },
- RemoveMedia { media_id: String },
- SetMediaPlaceholder { media_id: String, placeholder: bool },
- FillSlot { media_id: String, item: NewMedia },
- Batch { commands: Vec<Command> },
- AddClip { media_id: String, track_id: String, start: f64 },
- AddClipAtFirstFree { media_id: String, start: f64 },
+ /// Imports a file into the bin, minting an "m" id. A path already
+ /// present is a tolerated no-op that mints nothing.
+ AddMedia {
+ /// The probed file, as described by the host.
+ item: NewMedia,
+ },
+ /// Removes a bin item and every clip referencing it, on *all* timelines
+ /// - a clip whose media is gone would linger as a dead reference.
+ RemoveMedia {
+ /// The bin item to remove. An unknown id is a no-op.
+ media_id: String,
+ },
+ /// Marks a bin item as a template slot (or back to ordinary media),
+ /// which is what [`Command::FillSlot`] requires of its target.
+ SetMediaPlaceholder {
+ /// The bin item to mark. An unknown id is a no-op.
+ media_id: String,
+ /// True to make it a slot, false to make it ordinary media again.
+ placeholder: bool,
+ },
+ /// Swaps the user's file into a template slot in place. The slot keeps
+ /// its id so clips keep working; start, duration and speed stay the
+ /// template's, while the in-point resets and each clip's kind and name
+ /// follow the new file, across all timelines. Errs if the id is unknown
+ /// or the item is not a placeholder.
+ FillSlot {
+ /// The slot being filled - must have `placeholder` set.
+ media_id: String,
+ /// The user's file that takes the slot's place.
+ item: NewMedia,
+ },
+ /// Several commands as one atomic edit: applied to a staged copy and
+ /// committed only if every one succeeds, then recorded as a single undo
+ /// step. The outcome carries the last id minted inside.
+ Batch {
+ /// The commands, applied in order. Nesting is legal.
+ commands: Vec<Command>,
+ },
+ /// Places a clip of `media_id` on a named track, minting a "c" id.
+ /// Duration comes from the media (five seconds for a still or unknown
+ /// length); errs if the media or track no longer exists.
+ AddClip {
+ /// The bin item to cut from.
+ media_id: String,
+ /// The lane to place it on.
+ track_id: String,
+ /// Timeline position in seconds, floored at 0.
+ start: f64,
+ },
+ /// [`Command::AddClip`] without naming a lane: lands on the lowest
+ /// track with nothing in the clip's span, falling back to the bottom
+ /// track (overlap and all) rather than refusing.
+ AddClipAtFirstFree {
+ /// The bin item to cut from.
+ media_id: String,
+ /// Timeline position in seconds, floored at 0.
+ start: f64,
+ },
+ /// Places a title: a clip with no media behind it, named after the
+ /// text's first line, minting a "c" id.
AddTextClip {
+ /// The lane to place it on. None picks the first free track like
+ /// [`Command::AddClipAtFirstFree`]; naming a vanished track errs.
track_id: Option<String>,
+ /// Timeline position in seconds, floored at 0.
start: f64,
+ /// The words and their look. None means [`TextStyle::default`].
style: Option<TextStyle>,
/// Seconds on the timeline; the editorial default when absent. Here
/// so a caption run can land as one batch instead of add-then-trim
@@ -134,32 +236,158 @@ pub enum Command {
#[serde(default)]
offset_y: Option<f64>,
},
- MoveClips { moves: Vec<ClipMove> },
- TrimClip { clip_id: String, edge: TrimEdge, delta: f64 },
- SplitClips { clip_ids: Vec<String>, time: f64 },
- MergeClips { clip_ids: Vec<String> },
- RemoveClips { clip_ids: Vec<String> },
- UpdateClip { clip_id: String, patch: ClipPatch },
- SetClipSpeed { clip_id: String, speed: f64 },
+ /// Repositions any number of clips in one edit - one undo step for a
+ /// whole multi-selection drag. Unknown clips and tracks are tolerated
+ /// per [`ClipMove`].
+ MoveClips {
+ /// Where each clip is going.
+ moves: Vec<ClipMove>,
+ },
+ /// Drags one edge of a clip. A head trim moves the in-point with the
+ /// edge (scaled by speed) so the remaining pixels do not slide; either
+ /// edge stops at the sixtieth-of-a-second minimum duration. An unknown
+ /// clip is a no-op.
+ TrimClip {
+ /// The clip to trim.
+ clip_id: String,
+ /// Which edge is being dragged.
+ edge: TrimEdge,
+ /// Signed seconds of timeline the edge moves: positive drags the
+ /// head right (shortening) or the tail right (lengthening).
+ delta: f64,
+ },
+ /// Cuts each named clip in two at one playhead time. The head keeps the
+ /// id and the transition; the tail is minted fresh and stays
+ /// source-continuous. A clip the time misses (or grazes within the
+ /// minimum duration) is skipped.
+ SplitClips {
+ /// The clips under the playhead - normally the selection.
+ clip_ids: Vec<String>,
+ /// The cut point, in timeline seconds.
+ time: f64,
+ },
+ /// Rejoins split pieces into the earliest piece, which keeps its id.
+ /// Errs with a user-facing sentence ([`why_not_merge`]) unless the
+ /// pieces sit on one track, come from one file at one speed, touch
+ /// within a microsecond, and are still in source order.
+ MergeClips {
+ /// The pieces to rejoin, any order.
+ clip_ids: Vec<String>,
+ },
+ /// Deletes clips from the active timeline. Unknown ids are ignored.
+ RemoveClips {
+ /// The clips to delete.
+ clip_ids: Vec<String>,
+ },
+ /// Applies a [`ClipPatch`]: only the fields present change, with the
+ /// clamps documented on the patch. An unknown clip is a no-op.
+ UpdateClip {
+ /// The clip to patch.
+ clip_id: String,
+ /// Which properties change, and to what.
+ patch: ClipPatch,
+ },
+ /// Changes playback rate while holding the amount of source covered
+ /// constant - the clip's timeline duration is what stretches, which is
+ /// what makes this a speed change rather than a trim.
+ SetClipSpeed {
+ /// The clip to retime. An unknown id is a no-op.
+ clip_id: String,
+ /// The new rate, clamped into 0.0625..=16 (the engine's range).
+ speed: f64,
+ },
+ /// Adjusts the picture's placement. Each field is optional so a drag
+ /// can send just the axis it moved; absent fields stay put.
SetClipTransform {
+ /// The clip to place. An unknown id is a no-op.
clip_id: String,
+ /// New scale, clamped into 0.05..=8.
scale: Option<f64>,
+ /// New horizontal offset as a frame-width fraction, clamped to ±3.
offset_x: Option<f64>,
+ /// New vertical offset as a frame-height fraction, clamped to ±3.
offset_y: Option<f64>,
+ /// New rotation in degrees, wrapped into (-180, 180] so a full drag
+ /// never accumulates turns.
rotation: Option<f64>,
},
- DetachAudio { clip_id: String },
- ReattachAudio { clip_id: String },
+ /// Pulls a video clip's sound out into its own audio clip on a free
+ /// lane (minting one if none is free), muting the video and moving its
+ /// audio filters to the sound. A no-op unless the clip is an unmuted
+ /// video whose media has audio and is not already detached.
+ DetachAudio {
+ /// The video clip to detach from.
+ clip_id: String,
+ },
+ /// Undoes a detach: deletes the detached sound clip(s), unmutes the
+ /// video and hands the sound's filters back. Accepts either the video's
+ /// id or the sound's; a no-op when either side is gone.
+ ReattachAudio {
+ /// The video clip - or its detached sound.
+ clip_id: String,
+ },
+ /// Appends a lane named after the highest "Track N" in use, minting a
+ /// "t" id.
AddTrack,
- RemoveTrack { track_id: String },
- RenameTrack { track_id: String, name: String },
- SetTrackFlag { track_id: String, flag: TrackFlag, value: bool },
+ /// Deletes a lane and every clip on it. Errs at the floor of one track.
+ RemoveTrack {
+ /// The lane to delete.
+ track_id: String,
+ },
+ /// Renames a lane. Whitespace-only names are ignored so a track can
+ /// never end up blank; unknown ids are tolerated.
+ RenameTrack {
+ /// The lane to rename.
+ track_id: String,
+ /// The new label; trimmed before it lands.
+ name: String,
+ },
+ /// Flips one of a track's two toggles. An unknown id is a no-op.
+ SetTrackFlag {
+ /// The lane to change.
+ track_id: String,
+ /// Which toggle: visibility or mute.
+ flag: TrackFlag,
+ /// The new setting.
+ value: bool,
+ },
+ /// Adds a fresh timeline - four new lanes, "Timeline N" after the
+ /// highest in use - and makes it active. Mints a "tl" id.
AddTimeline,
- RemoveTimeline { timeline_id: String },
- RenameTimeline { timeline_id: String, name: String },
- SelectTimeline { timeline_id: String },
- AddFont { family: String, path: String },
- RemoveFont { family: String },
+ /// Deletes a timeline, moving the active tab to a neighbour if it was
+ /// this one. Errs at the floor of one timeline.
+ RemoveTimeline {
+ /// The timeline to delete. An unknown id is a no-op.
+ timeline_id: String,
+ },
+ /// Renames a timeline tab, with the same trim-and-ignore-blank rule as
+ /// [`Command::RenameTrack`].
+ RenameTimeline {
+ /// The timeline to rename.
+ timeline_id: String,
+ /// The new tab label; trimmed before it lands.
+ name: String,
+ },
+ /// Switches which timeline subsequent commands act on. An unknown id
+ /// leaves the selection where it was.
+ SelectTimeline {
+ /// The timeline to switch to.
+ timeline_id: String,
+ },
+ /// Registers a font file for titles. A path already registered is a
+ /// no-op, so re-adding cannot duplicate.
+ AddFont {
+ /// The family name titles will refer to.
+ family: String,
+ /// Where the font file lives on disk.
+ path: String,
+ },
+ /// Unregisters a font family. Clips keep the family name: the face may
+ /// come back when the file does.
+ RemoveFont {
+ /// The family to unregister.
+ family: String,
+ },
}
/// What a command produced, beyond the new state: the ids it minted, so the
@@ -167,6 +395,9 @@ pub enum Command {
#[derive(Clone, Default, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Outcome {
+ /// The id of what the command created - a clip, track, timeline, or
+ /// media item - or, for a batch, the last id minted inside it. Absent
+ /// when nothing was created, including tolerated no-ops.
#[serde(skip_serializing_if = "Option::is_none")]
pub created_id: Option<String>,
}
@@ -180,6 +411,8 @@ pub struct IdMint {
}
impl IdMint {
+ /// The next fresh id: the prefix ("c", "t", "tl", "m") plus a counter
+ /// shared across all prefixes, so no two ids ever share a number.
pub fn next(&mut self, prefix: &str) -> String {
self.counter += 1;
format!("{prefix}{}", self.counter)
@@ -200,6 +433,8 @@ impl IdMint {
}
}
+ /// Adopts every id a restored project uses - media, timelines, tracks,
+ /// clips - so nothing minted afterwards can collide with the file.
pub fn adopt_project(&mut self, project: &Project) {
for item in &project.media {
self.adopt(&item.id);
diff --git a/engine/crates/wolfcut-project/src/doc.rs b/engine/crates/wolfcut-project/src/doc.rs
index 0b87c8aa..2ae8b02d 100644
--- a/engine/crates/wolfcut-project/src/doc.rs
+++ b/engine/crates/wolfcut-project/src/doc.rs
@@ -280,10 +280,15 @@ pub fn from_document(document: &Value) -> Option<Project> {
/// Settings the host manages around the edit: the manifest's identity fields.
#[derive(Clone, Debug)]
pub struct DocumentSettings {
+ /// The project's display name, written as the document's `name` field.
pub name: String,
+ /// Output frame width in pixels.
pub width: u32,
+ /// Output frame height in pixels.
pub height: u32,
+ /// Numerator of the output frame rate, e.g. 30000 for 29.97fps.
pub rate_num: i64,
+ /// Denominator of the output frame rate, e.g. 1001 for 29.97fps.
pub rate_den: i64,
}
diff --git a/engine/crates/wolfcut-project/src/editor.rs b/engine/crates/wolfcut-project/src/editor.rs
index 991ad65d..82034cba 100644
--- a/engine/crates/wolfcut-project/src/editor.rs
+++ b/engine/crates/wolfcut-project/src/editor.rs
@@ -14,6 +14,9 @@ use crate::model::Project;
const UNDO_DEPTH: usize = 200;
+/// One editing session: the project, the id mint that keeps its ids unique,
+/// and the undo/redo stacks. This is the object a host holds per open
+/// project; everything else in the crate is reachable through it.
pub struct Editor {
project: Project,
mint: IdMint,
@@ -37,6 +40,8 @@ impl Editor {
Some(Self { project, mint, undo: Vec::new(), redo: Vec::new() })
}
+ /// The current state, read-only: all mutation goes through
+ /// [`Editor::apply`] so nothing can change without being undoable.
pub fn project(&self) -> &Project {
&self.project
}
@@ -81,10 +86,14 @@ impl Editor {
}
}
+ /// Whether [`Editor::undo`] would do anything - what the UI's undo
+ /// button greys out on.
pub fn can_undo(&self) -> bool {
!self.undo.is_empty()
}
+ /// Whether [`Editor::redo`] would do anything; the redo button's twin
+ /// of [`Editor::can_undo`].
pub fn can_redo(&self) -> bool {
!self.redo.is_empty()
}
diff --git a/engine/crates/wolfcut-project/src/model.rs b/engine/crates/wolfcut-project/src/model.rs
index d9ee9b0a..2568f0d6 100644
--- a/engine/crates/wolfcut-project/src/model.rs
+++ b/engine/crates/wolfcut-project/src/model.rs
@@ -20,8 +20,11 @@ use serde::{Deserialize, Serialize};
#[derive(Clone, Copy, PartialEq, Eq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum MediaKind {
+ /// Moving pictures, with or without embedded sound.
Video,
+ /// Sound only; nothing to composite.
Audio,
+ /// A still, whose timeline length is editorial rather than intrinsic.
Image,
}
@@ -30,9 +33,13 @@ pub enum MediaKind {
#[derive(Clone, Copy, PartialEq, Eq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ClipKind {
+ /// A cut of a video media item.
Video,
+ /// A cut of audio - either audio media or sound detached from a video.
Audio,
+ /// A placed still.
Image,
+ /// A title. No media behind it; the content lives in [`Clip::text`].
Text,
}
@@ -43,22 +50,38 @@ impl ClipKind {
}
}
+/// One entry in the media bin: a file the user imported, plus what the host's
+/// probe learned about it. The probe metadata is stored, not re-derived, so a
+/// document opens meaningfully even when the file itself is missing.
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MediaItem {
+ /// Minted by the editor ("m1", "m2", ...) and never re-issued, even
+ /// across a save/load - clips reference media by this id.
pub id: String,
+ /// Absolute path on the user's disk. Doubles as the duplicate check:
+ /// adding the same path twice is a no-op.
pub path: String,
+ /// Display name in the bin, normally the file's basename.
pub name: String,
/// Seconds. None when the container did not say.
pub duration: Option<f64>,
+ /// What the probe decided the file is; fixes which [`ClipKind`] its
+ /// clips get.
pub kind: MediaKind,
+ /// Pixel width, when the file has pictures and the probe found one.
pub width: Option<u32>,
+ /// Pixel height, same terms as `width`.
pub height: Option<u32>,
+ /// Frames per second as a decimal - convenient for display, not exact.
pub frame_rate: Option<f64>,
/// The exact fraction the engine works in, e.g. "30000/1001".
pub frame_rate_fraction: Option<String>,
+ /// Codec name as the probe reported it, e.g. "h264". Informational.
pub video_codec: Option<String>,
+ /// Codec of the embedded audio, when there is any.
pub audio_codec: Option<String>,
+ /// Whether the file carries an audio stream; gates `DetachAudio`.
pub has_audio: bool,
/// True when this item is a template slot: a stand-in whose metadata says
/// what kind of media belongs here, waiting to be replaced by the user's
@@ -77,7 +100,11 @@ fn is_false(value: &bool) -> bool {
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Track {
+ /// Minted per timeline ("t5", or "T1".."T4" for the first timeline's
+ /// starter lanes); never shared between timelines.
pub id: String,
+ /// User-editable label. Renames to whitespace are ignored, so it is
+ /// never blank.
pub name: String,
/// Video clips on this track are left out of the composite when false.
pub visible: bool,
@@ -91,7 +118,11 @@ pub struct Track {
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct AppliedFilter {
+ /// Which catalogue entry this is, e.g. "sepia". Not minted; an id the
+ /// catalogue no longer knows is simply skipped at render time.
pub id: String,
+ /// The user's knob settings, keyed by parameter name. Missing keys mean
+ /// the catalogue's defaults; ordered so serialisation is stable.
#[serde(default)]
pub params: BTreeMap<String, f64>,
/// False bypasses without losing settings. Absent means enabled.
@@ -107,16 +138,23 @@ fn yes() -> bool {
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Transition {
+ /// Which transition from the catalogue, e.g. "cross-fade".
pub id: String,
/// Seconds the transition covers.
pub duration: f64,
}
+/// How a title's lines sit within their block. The block itself is placed by
+/// the clip's transform, so this only matters for multi-line text.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum TextAlign {
+ /// Lines share a left edge.
Left,
+ /// Lines are centred on each other - the default, and what the reader
+ /// falls back to for an unrecognised value.
Center,
+ /// Lines share a right edge.
Right,
}
@@ -125,21 +163,40 @@ pub enum TextAlign {
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TextStyle {
+ /// The words themselves, newlines included. The clip's display name is
+ /// snapshotted from the first non-empty line.
pub content: String,
+ /// CSS-style family name, quotes included where the name needs them,
+ /// e.g. `"Cabinet Grotesk"`. May name a [`CustomFont`] the user added.
pub font_family: String,
/// Cap height as a fraction of frame height.
pub font_size: f64,
+ /// CSS-scale weight, 100..=900; the reader clamps hand-edited values
+ /// into that range.
pub font_weight: f64,
+ /// Italic when true. A style flag, not a separate face.
pub italic: bool,
+ /// Fill colour as a CSS hex string, e.g. "#ffffff".
pub color: String,
+ /// Line alignment within the block; see [`TextAlign`].
pub align: TextAlign,
+ /// Opacity of the whole title in 0..=1, multiplied with the clip's own
+ /// opacity.
pub opacity: f64,
+ /// Outline thickness as a fraction of frame height. Zero - the default -
+ /// means no stroke.
pub stroke_width: f64,
+ /// Outline colour, only visible when `stroke_width` is non-zero.
pub stroke_color: String,
+ /// A drop shadow for legibility over footage. On by default.
pub shadow: bool,
/// A solid plate behind the text. Empty string for none.
pub background: String,
+ /// Baseline spacing as a multiple of the font size; the reader floors it
+ /// at 0.5 so lines cannot collapse onto each other.
pub line_height: f64,
+ /// Extra letter spacing, in the same frame-height fractions as
+ /// `font_size`. Zero is the font's natural fit.
pub tracking: f64,
}
@@ -164,28 +221,44 @@ impl Default for TextStyle {
}
}
+/// One placed piece of a timeline: a stretch of media (or a title) with its
+/// timing, mix, transform, and effects. Everything an edit decision touches
+/// lives here, which is why most commands are clip commands.
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Clip {
+ /// Minted by the editor ("c1", "c2", ...); how every command names its
+ /// target. Survives splits - the head keeps the id - and merges.
pub id: String,
+ /// The lane this clip sits on. Always a track of the same timeline; the
+ /// reader drops clips whose track vanished.
pub track_id: String,
/// Empty for a text clip, which has no file behind it.
pub media_id: String,
+ /// Display label. Snapshotted from the media's name (or a title's first
+ /// line) at creation, then the user's to change.
pub name: String,
+ /// What this clip renders as. Follows the media's kind, and is rewritten
+ /// when a template slot is filled with a different kind of file.
pub kind: ClipKind,
/// Seconds from the start of the timeline.
pub start: f64,
+ /// Seconds of timeline the clip occupies. Source seconds divided by
+ /// `speed`; never below a sixtieth of a second.
pub duration: f64,
/// In-point: how far into the media the clip starts.
pub source_start: f64,
/// Linear gain, 1 being unity.
pub volume: f64,
+ /// Seconds of audio ramp-in from silence at the head. Zero for none.
pub fade_in: f64,
+ /// Seconds of audio ramp-out to silence at the tail. Zero for none.
pub fade_out: f64,
/// Multiplier over the fitted size. 1 fills the frame, preserving aspect.
pub scale: f64,
/// Offset from centred, as a fraction of frame width / height.
pub offset_x: f64,
+ /// The vertical half of `offset_x`'s pair; positive moves down.
pub offset_y: f64,
/// Clockwise rotation in degrees, about the picture's centre.
pub rotation: f64,
@@ -193,6 +266,8 @@ pub struct Clip {
pub opacity: f64,
/// Playback rate. 1 is normal.
pub speed: f64,
+ /// Keep voices at their natural pitch when `speed` is not 1. On by
+ /// default; off gives the tape-machine chipmunk/slow-motion sound.
pub preserve_pitch: bool,
/// Audio filters, in order - order is audible.
#[serde(default)]
@@ -221,9 +296,15 @@ pub struct Clip {
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Timeline {
+ /// Minted by the editor ("tl2", ...), except the founding "TL1".
pub id: String,
+ /// The tab label; "Timeline N" by default, renameable but never blank.
pub name: String,
+ /// The lanes, top to bottom. Never empty - `RemoveTrack` keeps a floor
+ /// of one.
pub tracks: Vec<Track>,
+ /// Every clip on this timeline, in insertion order, not time order -
+ /// readers must sort by `start` where order matters.
pub clips: Vec<Clip>,
}
@@ -231,7 +312,11 @@ pub struct Timeline {
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CustomFont {
+ /// The family name titles refer to; removal leaves referring clips
+ /// untouched so the face can come back when the file does.
pub family: String,
+ /// Where the font file lives on disk. Doubles as the duplicate check
+ /// when adding.
pub path: String,
}
@@ -240,10 +325,15 @@ pub struct CustomFont {
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Project {
+ /// The bin: every imported file, shared by all timelines.
pub media: Vec<MediaItem>,
+ /// Fonts the user added from disk, available to every title.
pub fonts: Vec<CustomFont>,
/// Every timeline, in tab order. Always at least one.
pub timelines: Vec<Timeline>,
+ /// Which timeline commands act on. Maintained by the command layer, so
+ /// it always names a member of `timelines`; [`Project::active`] degrades
+ /// to the first timeline if it somehow does not.
pub active_timeline_id: String,
}
@@ -280,6 +370,8 @@ impl Project {
.unwrap_or(&self.timelines[0])
}
+ /// Mutable twin of [`Project::active`], with the same degrade-to-first
+ /// behaviour.
pub fn active_mut(&mut self) -> &mut Timeline {
let index = self
.timelines
@@ -289,6 +381,7 @@ impl Project {
&mut self.timelines[index]
}
+ /// The bin entry with this id, or None if it was removed.
pub fn media_by_id(&self, media_id: &str) -> Option<&MediaItem> {
self.media.iter().find(|item| item.id == media_id)
}
@@ -301,14 +394,18 @@ impl Default for Project {
}
impl Timeline {
+ /// The clip with this id, or None if it is not on this timeline - which
+ /// most commands treat as a tolerated no-op, not an error.
pub fn clip(&self, clip_id: &str) -> Option<&Clip> {
self.clips.iter().find(|clip| clip.id == clip_id)
}
+ /// Mutable twin of [`Timeline::clip`].
pub fn clip_mut(&mut self, clip_id: &str) -> Option<&mut Clip> {
self.clips.iter_mut().find(|clip| clip.id == clip_id)
}
+ /// The track with this id, or None if it was removed.
pub fn track(&self, track_id: &str) -> Option<&Track> {
self.tracks.iter().find(|track| track.id == track_id)
}