Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Save a rendered scene as an .mp4 in the project folder

Bittid5d4670a71ac
diff --git a/src-tauri/src/export.rs b/src-tauri/src/export.rs
index ba4087d..120e97d 100644
--- a/src-tauri/src/export.rs
+++ b/src-tauri/src/export.rs
@@ -46,7 +46,9 @@ fn safe_file_name(value: &str) -> String {
/// Decodes `encodeURIComponent` output back to the path the user chose. Only
/// `%XX` is special; everything else is already the character it looks like.
-fn percent_decode(value: &str) -> Result<String, String> {
+/// Shared with the generated-video write, which carries its own paths in
+/// headers for the same reason: a raw body leaves nowhere else to put them.
+pub(crate) fn percent_decode(value: &str) -> Result<String, String> {
let source = value.as_bytes();
let mut bytes = Vec::with_capacity(source.len());
let mut index = 0;
@@ -154,7 +156,7 @@ fn authorized_destination(value: &str) -> Result<PathBuf, String> {
/// Writes beside the destination and renames on top of it, so an export that
/// fails half way through cannot leave a truncated file where a playable one
/// used to be. `fs::rename` replaces the destination on both platforms here.
-fn write_atomically(destination: &Path, bytes: &[u8]) -> Result<(), String> {
+pub(crate) fn write_atomically(destination: &Path, bytes: &[u8]) -> Result<(), String> {
let mut temporary = destination.as_os_str().to_os_string();
temporary.push(".part");
let temporary = PathBuf::from(temporary);
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index 9d33363..c611bc4 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -5,11 +5,12 @@ use std::{
path::{Path, PathBuf},
sync::atomic::{AtomicU64, Ordering},
};
-use tauri::AppHandle;
+use tauri::{ipc::InvokeBody, ipc::Request, AppHandle};
use tauri_plugin_dialog::DialogExt;
mod agent;
mod export;
+mod rendered;
mod vidfab;
const PROJECT_FILE_NAME: &str = "polstudio.json";
@@ -1882,6 +1883,146 @@ fn cancel_vidfab_generation(
state.cancel(&job_id)
}
+/* ── A finished render, on its way to a file ─────────────────────────────────
+ vidfab produces pictures, not files. The webview turns them into an MP4 —
+ WebCodecs owns the hardware encoder and there is no FFmpeg here (CLAUDE.md) —
+ which means the pictures have to cross into the webview and the bytes have to
+ come back. These four commands are that round trip: three that read what a
+ finished generation left in memory (see `rendered`), and one that writes the
+ encoded file into the project.
+ -------------------------------------------------------------------------- */
+
+const GENERATED_FOLDER_HEADER: &str = "x-generated-folder";
+const GENERATED_JOB_HEADER: &str = "x-generated-job";
+/// Where a rendered scene lands, relative to the project root. Created by
+/// `create_project` along with the rest of the folder layout.
+const GENERATED_DIRECTORY: &str = "media/generated";
+
+/// A scene id, as a file name.
+///
+/// The webview names the job, so this is caller-controlled text about to become
+/// a path — the exact shape of a traversal. Rather than sanitising it, the id
+/// is REFUSED unless it is already only letters, digits, dash and underscore,
+/// which is what every id PolStudio generates looks like. There is nothing to
+/// strip and nothing to get wrong: no dots (so no `..` and no second
+/// extension), no separators, no length worth arguing about.
+fn generated_file_stem(job_id: &str) -> Result<String, String> {
+ let trimmed = job_id.trim();
+ if trimmed.is_empty() || trimmed.len() > 64 {
+ return Err("A scene id must be between 1 and 64 characters.".into());
+ }
+ if !trimmed
+ .chars()
+ .all(|character| character.is_ascii_alphanumeric() || matches!(character, '-' | '_'))
+ {
+ return Err(format!(
+ "'{job_id}' is not a scene id: only letters, digits, dashes and underscores name a rendered file."
+ ));
+ }
+ Ok(trimmed.to_string())
+}
+
+/// The single path a generated video may be written to, and what the project
+/// will record. Nothing about it comes from the caller except the scene id,
+/// which [`generated_file_stem`] has already refused unless it is inert — so
+/// unlike an export, there is no destination to authorise, because the webview
+/// never names one.
+fn generated_video_destination(folder_path: &str, job_id: &str) -> Result<(PathBuf, String), String> {
+ let root = project_root(folder_path)?;
+ let stem = generated_file_stem(job_id)?;
+ let directory = root.join(GENERATED_DIRECTORY);
+ fs::create_dir_all(&directory).map_err(|error| {
+ format!("Could not make {}: {error}", display_path(&directory))
+ })?;
+ Ok((
+ directory.join(format!("{stem}.mp4")),
+ format!("{GENERATED_DIRECTORY}/{stem}.mp4"),
+ ))
+}
+
+/// What was written, in the project's own terms: the path that goes into
+/// `polstudio.json` and the size of the file that demonstrably exists.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct GeneratedVideoFile {
+ relative_path: String,
+ bytes: u64,
+}
+
+/// Writes the webview's encoded MP4 into the project folder.
+///
+/// The bytes arrive as a raw IPC body for the same reason an export's do: a
+/// 30 MB file serialised as a JSON array of numbers is hundreds of megabytes of
+/// text. That leaves nowhere for the arguments, so the project folder and the
+/// scene id ride in headers, percent-encoded because a header is ASCII and a
+/// Windows path is not.
+#[tauri::command]
+fn write_generated_video(request: Request<'_>) -> Result<GeneratedVideoFile, String> {
+ let InvokeBody::Raw(bytes) = request.body() else {
+ return Err("The rendered scene was sent as JSON instead of raw bytes.".to_string());
+ };
+ if bytes.is_empty() {
+ return Err("The encoder produced no bytes, so nothing was written.".to_string());
+ }
+ let header = |name: &str| -> Result<String, String> {
+ let value = request
+ .headers()
+ .get(name)
+ .ok_or_else(|| format!("The request carried no {name} header."))?;
+ export::percent_decode(
+ value
+ .to_str()
+ .map_err(|_| format!("The {name} header is not readable text."))?,
+ )
+ };
+ let (destination, relative_path) = generated_video_destination(
+ &header(GENERATED_FOLDER_HEADER)?,
+ &header(GENERATED_JOB_HEADER)?,
+ )?;
+ export::write_atomically(&destination, bytes)?;
+ Ok(GeneratedVideoFile {
+ relative_path,
+ bytes: bytes.len() as u64,
+ })
+}
+
+/// What is waiting to be encoded for this scene, or None when nothing is. The
+/// webview asks this first: it decides what to encode from what Rust actually
+/// holds rather than from the event that told it to look.
+#[tauri::command]
+fn generated_summary(job_id: String) -> Option<rendered::RenderedSummary> {
+ rendered::summary(&job_id)
+}
+
+/// One frame of a finished render, as RGBA the webview can build a `VideoFrame`
+/// from. A frame at a time because a whole render is hundreds of megabytes and
+/// the encoder only ever wants the next one.
+#[tauri::command]
+fn generated_frame(job_id: String, index: u32) -> Result<tauri::ipc::Response, String> {
+ rendered::frame(&job_id, index)
+ .map(tauri::ipc::Response::new)
+ .ok_or_else(|| {
+ format!("Frame {index} of {job_id} is not in memory. The render was released, dropped to make room, or never finished.")
+ })
+}
+
+/// The render's soundtrack, interleaved little-endian f32 — one read, because
+/// even fifteen seconds of stereo is a couple of megabytes.
+#[tauri::command]
+fn generated_audio(job_id: String) -> Result<tauri::ipc::Response, String> {
+ rendered::audio(&job_id)
+ .map(tauri::ipc::Response::new)
+ .ok_or_else(|| format!("The audio of {job_id} is not in memory."))
+}
+
+/// Hands the memory back. Called when the file has been written AND when the
+/// webview has given up: a render nobody can encode is still hundreds of
+/// megabytes nobody should be holding.
+#[tauri::command]
+fn release_generated_frames(job_id: String) -> bool {
+ rendered::release(&job_id)
+}
+
/* ── Exit guard ──────────────────────────────────────────────────────────────
The video engine runs inside this process, so closing the window ends a
generation outright — and vidfab writes no file of its own, so an unfinished
@@ -2030,6 +2171,11 @@ pub fn run() {
cancel_vidfab_generation,
set_generation_active,
answer_app_close,
+ write_generated_video,
+ generated_summary,
+ generated_frame,
+ generated_audio,
+ release_generated_frames,
export::choose_export_destination,
export::write_export_file
])
@@ -3724,6 +3870,70 @@ mod tests {
assert_eq!(track.clips[0].source_start_ms, 0);
assert!(validate_and_normalize_config(config.clone()).is_ok());
}
+
+ /* ── Where a rendered scene is allowed to land ──────────────────────────
+ The webview names the scene, and the scene names the file. That is the
+ whole of the caller's influence over this path, and these pin it.
+ ------------------------------------------------------------------- */
+
+ fn project_folder() -> tempfile::TempDir {
+ let folder = tempfile::tempdir().unwrap();
+ fs::write(
+ folder.path().join(PROJECT_FILE_NAME),
+ serde_json::to_vec(&created_fixture()).unwrap(),
+ )
+ .unwrap();
+ folder
+ }
+
+ #[test]
+ fn a_rendered_scene_lands_in_the_project_under_its_own_id() {
+ let folder = project_folder();
+ let (destination, relative) =
+ generated_video_destination(&folder.path().to_string_lossy(), "job-initial-brief").unwrap();
+ assert_eq!(relative, "media/generated/job-initial-brief.mp4");
+ assert!(destination.ends_with("media/generated/job-initial-brief.mp4"));
+ // The folder is made, so the write that follows has somewhere to go.
+ assert!(destination.parent().unwrap().is_dir());
+ // And it really is inside the project, not merely named as though it were.
+ assert!(destination.starts_with(folder.path().canonicalize().unwrap()));
+ }
+
+ #[test]
+ fn a_scene_id_that_is_not_a_scene_id_is_refused_rather_than_scrubbed() {
+ let folder = project_folder();
+ let root = folder.path().to_string_lossy().into_owned();
+ for hostile in [
+ "../../etc/passwd",
+ "..",
+ ".",
+ "job/../../escape",
+ r"job\..\escape",
+ "job:stream",
+ "job.mp4",
+ "",
+ " ",
+ &"j".repeat(65),
+ ] {
+ assert!(
+ generated_video_destination(&root, hostile).is_err(),
+ "'{hostile}' must not name a file"
+ );
+ }
+ // A dot is refused too — nothing PolStudio generates has one, and
+ // allowing it is how a second extension gets in.
+ assert!(generated_file_stem("job-01_A").is_ok());
+ assert!(generated_file_stem("job.01").is_err());
+ }
+
+ #[test]
+ fn a_folder_that_holds_no_project_gets_no_writer() {
+ // The same rule every other command that takes a folderPath follows:
+ // confining a name against an unchecked folder confines nothing.
+ let empty = tempfile::tempdir().unwrap();
+ assert!(generated_video_destination(&empty.path().to_string_lossy(), "job-01").is_err());
+ assert!(generated_video_destination("", "job-01").is_err());
+ }
}
/* ── Exit guard tests ─────────────────────────────────────────────────────── */
@@ -3781,4 +3991,5 @@ mod exit_guard_tests {
guard.generation_active.store(false, Ordering::Release);
assert_eq!(guard.on_close_requested(), CloseDecision::Close);
}
+
}
diff --git a/src-tauri/src/rendered.rs b/src-tauri/src/rendered.rs
new file mode 100644
index 0000000..c08578b
--- /dev/null
+++ b/src-tauri/src/rendered.rs
@@ -0,0 +1,399 @@
+//! What a finished generation leaves behind, between vidfab and the encoder.
+//!
+//! vidfab hands back raw pictures — planar RGB floats, one plane after another,
+//! frame after frame — and then frees them when the generation handle is
+//! destroyed. Nothing in this process can turn those into an MP4: encoding is
+//! the webview's job, because WebCodecs is what owns the OS hardware encoder
+//! and PolStudio ships no FFmpeg by design (see docs/architecture.md, and
+//! CLAUDE.md on the licensing reason).
+//!
+//! So this module is the hand-off. It takes one copy of the pictures on the way
+//! out of the C API — converting them to the 8-bit RGBA the webview can make a
+//! `VideoFrame` from — holds them until the webview has read them, and hands
+//! them over a frame at a time. The webview encodes, muxes, and asks Rust to
+//! write the file.
+//!
+//! ## What this costs
+//!
+//! A frame of RGBA at 1344×768 is 4.1 MB, so a five-second scene at 24 fps is
+//! about 500 MB and the longest a scene can be (15 s) is 1.5 GB. That is real
+//! memory, held from the moment a render finishes until the webview says it is
+//! done with it. It is also the smallest the hand-off can be: the source floats
+//! are three times larger, the copy is forced (the C API frees its buffers with
+//! the generation), and a temporary file on disk would trade the memory for a
+//! gigabyte of writing and reading that ends up in the same place.
+//!
+//! [`CAPACITY`] is what stops that growing without limit.
+
+use std::{
+ collections::VecDeque,
+ sync::{LazyLock, Mutex},
+};
+
+/// How many finished renders may wait for the webview at once.
+///
+/// The queue is serial and the webview claims a render as soon as the event
+/// announcing it lands, so one is the normal number and two is slack for a
+/// window that was busy. Beyond that the OLDEST is dropped — its frames are
+/// gone and the scene has to be rendered again. That is the honest trade: the
+/// alternative is a process that grows by a gigabyte per abandoned render until
+/// the machine gives out.
+const CAPACITY: usize = 2;
+
+/// A finished render, converted once and kept whole.
+pub struct RenderedVideo {
+ pub job_id: String,
+ pub width: u32,
+ pub height: u32,
+ pub frame_count: u32,
+ pub fps: f64,
+ /// RGBA8, frame after frame, rows top to bottom. `frame_count * width *
+ /// height * 4` bytes exactly.
+ rgba: Vec<u8>,
+ /// Interleaved samples, as vidfab returned them.
+ audio: Vec<f32>,
+ pub audio_channels: u32,
+ pub audio_sample_rate: u32,
+}
+
+impl RenderedVideo {
+ pub fn frame_bytes(&self) -> usize {
+ self.width as usize * self.height as usize * 4
+ }
+
+ /// One frame's pixels, or None when there is no such frame.
+ pub fn frame(&self, index: u32) -> Option<&[u8]> {
+ let size = self.frame_bytes();
+ let start = (index as usize).checked_mul(size)?;
+ self.rgba.get(start..start.checked_add(size)?)
+ }
+
+ /// The soundtrack as little-endian f32 bytes, which is what the webview's
+ /// `Float32Array` reads without a conversion of its own.
+ pub fn audio_bytes(&self) -> Vec<u8> {
+ let mut bytes = Vec::with_capacity(self.audio.len() * 4);
+ for sample in &self.audio {
+ bytes.extend_from_slice(&sample.to_le_bytes());
+ }
+ bytes
+ }
+}
+
+/// How the floats vidfab returns map onto 0–255.
+///
+/// The C API documents the layout (planar RGB) but not the range, and the two
+/// conventions a decoder can use — 0…1 and −1…1 — differ by a factor of two and
+/// an offset. Getting it wrong is not subtle: a signed picture read as unsigned
+/// is blown-out and half black. So it is READ off the pictures rather than
+/// assumed, from the first frame, which is the smallest sample that can settle
+/// it: a picture with any meaningfully negative value cannot be 0…1.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Range {
+ /// 0.0 is black, 1.0 is white.
+ Unit,
+ /// −1.0 is black, 1.0 is white.
+ Signed,
+}
+
+impl Range {
+ /// Anything below this is a negative the 0…1 convention has no room for.
+ /// Not zero, because a decoder that clamps at zero still lands a whisker
+ /// under it now and then.
+ const NEGATIVE: f32 = -0.02;
+
+ pub fn of(sample: &[f32]) -> Self {
+ if sample.iter().any(|value| *value < Self::NEGATIVE) {
+ Self::Signed
+ } else {
+ Self::Unit
+ }
+ }
+
+ fn to_byte(self, value: f32) -> u8 {
+ // NaN maps to black rather than to whatever `as u8` does with it, which
+ // is 0 on every target Rust supports but is not something to lean on.
+ if value.is_nan() {
+ return 0;
+ }
+ let unit = match self {
+ Self::Unit => value,
+ Self::Signed => (value + 1.0) / 2.0,
+ };
+ (unit.clamp(0.0, 1.0) * 255.0).round() as u8
+ }
+}
+
+/// Turns vidfab's planar float pictures into the RGBA the webview can encode.
+///
+/// The layout, from docs/architecture.md and the C API's own fields: `frames`
+/// pictures, each `channels` planes of `height × width` floats, rows top to
+/// bottom. Every plane of a frame is therefore `width * height` apart, which is
+/// what the striding below says.
+///
+/// One channel is greyscale and is written to all three; more than three means
+/// the first three are the colour and the rest is not ours to interpret.
+pub fn rgba_from_planar(
+ video: &[f32],
+ frame_count: u32,
+ width: u32,
+ height: u32,
+ channels: u32,
+) -> Result<Vec<u8>, String> {
+ let (frames, width_px, height_px, planes) = (
+ frame_count as usize,
+ width as usize,
+ height as usize,
+ channels as usize,
+ );
+ if frames == 0 || width_px == 0 || height_px == 0 || planes == 0 {
+ return Err("The render returned no pictures.".to_string());
+ }
+ let pixels = width_px * height_px;
+ let expected = frames
+ .checked_mul(planes)
+ .and_then(|value| value.checked_mul(pixels))
+ .ok_or_else(|| "The render's dimensions do not fit in memory.".to_string())?;
+ if video.len() < expected {
+ return Err(format!(
+ "The render says it has {frames} frames of {width_px}×{height_px}×{planes}, which is {expected} values, but only {} came back.",
+ video.len()
+ ));
+ }
+ let range = Range::of(&video[..planes * pixels]);
+ let mut rgba = vec![255u8; frames * pixels * 4];
+ for frame in 0..frames {
+ let base = frame * planes * pixels;
+ let red = &video[base..base + pixels];
+ let green = if planes >= 2 { &video[base + pixels..base + 2 * pixels] } else { red };
+ let blue = if planes >= 3 { &video[base + 2 * pixels..base + 3 * pixels] } else { red };
+ let out = &mut rgba[frame * pixels * 4..(frame + 1) * pixels * 4];
+ for pixel in 0..pixels {
+ out[pixel * 4] = range.to_byte(red[pixel]);
+ out[pixel * 4 + 1] = range.to_byte(green[pixel]);
+ out[pixel * 4 + 2] = range.to_byte(blue[pixel]);
+ // Alpha was filled with 255 up front; a generated frame is opaque.
+ }
+ }
+ Ok(rgba)
+}
+
+/// Builds the hand-off from one vidfab output. Everything is copied here,
+/// because the C API frees its own buffers as soon as the generation is
+/// destroyed — which happens the moment this returns.
+#[allow(clippy::too_many_arguments)]
+pub fn from_output(
+ job_id: &str,
+ video: &[f32],
+ audio: &[f32],
+ frame_count: u32,
+ width: u32,
+ height: u32,
+ channels: u32,
+ fps: f64,
+ audio_channels: u32,
+ audio_sample_rate: u32,
+) -> Result<RenderedVideo, String> {
+ Ok(RenderedVideo {
+ job_id: job_id.to_string(),
+ width,
+ height,
+ frame_count,
+ fps,
+ rgba: rgba_from_planar(video, frame_count, width, height, channels)?,
+ audio: audio.to_vec(),
+ audio_channels,
+ audio_sample_rate,
+ })
+}
+
+static WAITING: LazyLock<Mutex<VecDeque<RenderedVideo>>> = LazyLock::new(Default::default);
+
+/// Puts a finished render where the webview can fetch it. Returns what had to
+/// be dropped to make room, so the caller can say so rather than let a render
+/// disappear quietly.
+pub fn keep(video: RenderedVideo) -> Option<String> {
+ let Ok(mut waiting) = WAITING.lock() else {
+ return None;
+ };
+ // A second run of the same scene replaces the first: the frames the user
+ // wants are the ones they just watched being made.
+ waiting.retain(|held| held.job_id != video.job_id);
+ waiting.push_back(video);
+ if waiting.len() > CAPACITY {
+ return waiting.pop_front().map(|dropped| dropped.job_id);
+ }
+ None
+}
+
+/// Reads something out of one waiting render. Nothing is copied for a job that
+/// is not there — the answer is None and the caller says so.
+fn with<T>(job_id: &str, read: impl FnOnce(&RenderedVideo) -> T) -> Option<T> {
+ let waiting = WAITING.lock().ok()?;
+ waiting.iter().find(|held| held.job_id == job_id).map(read)
+}
+
+pub fn frame(job_id: &str, index: u32) -> Option<Vec<u8>> {
+ with(job_id, |video| video.frame(index).map(<[u8]>::to_vec))?
+}
+
+pub fn audio(job_id: &str) -> Option<Vec<u8>> {
+ with(job_id, RenderedVideo::audio_bytes)
+}
+
+/// What the webview needs before it can encode: the shape of the pictures it is
+/// about to ask for, one at a time, and how much sound came with them.
+///
+/// Read from the STORE rather than from the event that announced the render.
+/// The event is a notification — it can be missed, it can arrive at a window
+/// that is reloading — and the only authority on what can still be encoded is
+/// what is still held.
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RenderedSummary {
+ pub job_id: String,
+ pub width: u32,
+ pub height: u32,
+ pub frame_count: u32,
+ pub fps: f64,
+ pub audio_channels: u32,
+ pub audio_sample_rate: u32,
+ /// Interleaved samples across every channel, so an empty soundtrack is
+ /// distinguishable from one that has not been read yet.
+ pub audio_samples: u32,
+}
+
+pub fn summary(job_id: &str) -> Option<RenderedSummary> {
+ with(job_id, |video| RenderedSummary {
+ job_id: video.job_id.clone(),
+ width: video.width,
+ height: video.height,
+ frame_count: video.frame_count,
+ fps: video.fps,
+ audio_channels: video.audio_channels,
+ audio_sample_rate: video.audio_sample_rate,
+ audio_samples: video.audio.len() as u32,
+ })
+}
+
+/// Hands the memory back. Called when the webview has written the file, and
+/// when it has given up on writing it — a render nobody can encode is still a
+/// gigabyte nobody should be holding.
+pub fn release(job_id: &str) -> bool {
+ let Ok(mut waiting) = WAITING.lock() else {
+ return false;
+ };
+ let before = waiting.len();
+ waiting.retain(|held| held.job_id != job_id);
+ waiting.len() != before
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn planar(frames: usize, width: usize, height: usize, channels: usize, value: impl Fn(usize) -> f32) -> Vec<f32> {
+ (0..frames * channels * width * height).map(value).collect()
+ }
+
+ #[test]
+ fn planes_become_pixels_in_the_right_order() {
+ // One 2×1 frame: red plane, then green, then blue.
+ let video = vec![1.0, 0.0, /* R */ 0.0, 1.0, /* G */ 0.0, 0.0 /* B */];
+ let rgba = rgba_from_planar(&video, 1, 2, 1, 3).unwrap();
+ assert_eq!(rgba, vec![255, 0, 0, 255, 0, 255, 0, 255]);
+ }
+
+ #[test]
+ fn every_frame_is_read_from_its_own_planes() {
+ // Two 1×1 frames, the second twice as bright as the first.
+ let video = vec![0.2, 0.2, 0.2, 0.4, 0.4, 0.4];
+ let rgba = rgba_from_planar(&video, 2, 1, 1, 3).unwrap();
+ assert_eq!(rgba, vec![51, 51, 51, 255, 102, 102, 102, 255]);
+ }
+
+ #[test]
+ fn a_signed_picture_is_recognised_and_shifted_rather_than_clipped() {
+ // −1…1: mid grey is 0.0 here and would read as black on the 0…1 rule.
+ assert_eq!(Range::of(&[-1.0, 0.0, 1.0]), Range::Signed);
+ let video = vec![-1.0, 0.0, 1.0, -1.0, 0.0, 1.0, -1.0, 0.0, 1.0];
+ let rgba = rgba_from_planar(&video, 1, 3, 1, 3).unwrap();
+ assert_eq!(&rgba[..12], &[0, 0, 0, 255, 128, 128, 128, 255, 255, 255, 255, 255]);
+ }
+
+ #[test]
+ fn a_unit_picture_keeps_its_own_scale() {
+ assert_eq!(Range::of(&[0.0, 0.5, 1.0]), Range::Unit);
+ let video = vec![0.0, 0.5, 1.0, 0.0, 0.5, 1.0, 0.0, 0.5, 1.0];
+ let rgba = rgba_from_planar(&video, 1, 3, 1, 3).unwrap();
+ assert_eq!(&rgba[..12], &[0, 0, 0, 255, 128, 128, 128, 255, 255, 255, 255, 255]);
+ }
+
+ #[test]
+ fn out_of_range_and_not_a_number_land_inside_the_byte() {
+ let video = vec![2.0, f32::NAN, -0.001, 2.0, f32::NAN, -0.001, 2.0, f32::NAN, -0.001];
+ let rgba = rgba_from_planar(&video, 1, 3, 1, 3).unwrap();
+ assert_eq!(&rgba[..12], &[255, 255, 255, 255, 0, 0, 0, 255, 0, 0, 0, 255]);
+ }
+
+ #[test]
+ fn one_plane_is_greyscale_rather_than_a_red_picture() {
+ let rgba = rgba_from_planar(&[0.5], 1, 1, 1, 1).unwrap();
+ assert_eq!(rgba, vec![128, 128, 128, 255]);
+ }
+
+ #[test]
+ fn a_short_buffer_is_refused_rather_than_read_past_its_end() {
+ let video = planar(2, 4, 4, 3, |_| 0.5);
+ assert!(rgba_from_planar(&video, 3, 4, 4, 3).is_err());
+ assert!(rgba_from_planar(&video, 2, 4, 4, 3).is_ok());
+ assert!(rgba_from_planar(&[], 0, 4, 4, 3).is_err());
+ }
+
+ fn sample(job_id: &str) -> RenderedVideo {
+ from_output(job_id, &[0.5, 0.5, 0.5], &[0.25, -0.25], 1, 1, 1, 3, 24.0, 2, 48_000).unwrap()
+ }
+
+ #[test]
+ fn a_render_is_held_until_it_is_released() {
+ release("held");
+ assert!(frame("held", 0).is_none());
+ keep(sample("held"));
+ assert_eq!(frame("held", 0).unwrap(), vec![128, 128, 128, 255]);
+ assert_eq!(
+ summary("held").unwrap(),
+ RenderedSummary { job_id: "held".into(), width: 1, height: 1, frame_count: 1, fps: 24.0, audio_channels: 2, audio_sample_rate: 48_000, audio_samples: 2 },
+ );
+ // Past the last frame is an absence, not a panic and not a short read.
+ assert!(frame("held", 1).is_none());
+ // f32 little-endian, which is what the webview reads it back as.
+ assert_eq!(audio("held").unwrap(), 0.25f32.to_le_bytes().iter().chain(&(-0.25f32).to_le_bytes()).copied().collect::<Vec<u8>>());
+ assert!(release("held"));
+ assert!(!release("held"));
+ assert!(frame("held", 0).is_none());
+ }
+
+ #[test]
+ fn a_second_run_of_one_scene_replaces_the_first() {
+ release("same");
+ keep(sample("same"));
+ keep(sample("same"));
+ assert!(release("same"));
+ assert!(!release("same"), "one job may only ever hold one render");
+ }
+
+ #[test]
+ fn the_oldest_render_is_dropped_rather_than_the_process_growing_without_limit() {
+ for id in ["cap-1", "cap-2", "cap-3"] {
+ release(id);
+ }
+ assert_eq!(keep(sample("cap-1")), None);
+ assert_eq!(keep(sample("cap-2")), None);
+ // Whatever else is waiting from another test, pushing past the cap
+ // reports what it evicted rather than losing it silently.
+ let evicted = keep(sample("cap-3"));
+ assert!(evicted.is_some());
+ for id in ["cap-1", "cap-2", "cap-3"] {
+ release(id);
+ }
+ }
+}
diff --git a/src-tauri/src/vidfab.rs b/src-tauri/src/vidfab.rs
index d9e1995..4668ba9 100644
--- a/src-tauri/src/vidfab.rs
+++ b/src-tauri/src/vidfab.rs
@@ -2,7 +2,7 @@
//!
//! All ABI declarations and `unsafe` calls live in `ffi`; the rest of the
//! application only handles owned Rust status, plan, progress, and metadata.
-use crate::{ProviderOption, ProviderSetting};
+use crate::{rendered, ProviderOption, ProviderSetting};
use serde::{Deserialize, Serialize};
use std::{
collections::{BTreeMap, HashMap},
@@ -106,6 +106,9 @@ struct JobEvent {
output: Option<OutputMetadata>,
}
+/// What came back, and what the webview needs in order to encode it: the
+/// shape of the pictures now waiting in [`crate::rendered`], and how much sound
+/// came with them.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct OutputMetadata {
@@ -115,6 +118,9 @@ struct OutputMetadata {
fps: f64,
audio_channels: i32,
audio_sample_rate: i32,
+ /// Interleaved samples across every channel, so the webview can tell an
+ /// empty soundtrack from one it has not read yet.
+ audio_samples: usize,
duration_seconds: f64,
boundary: &'static str,
}
@@ -134,7 +140,21 @@ impl Default for VidfabRuntime {
while let Ok(item) = receiver.recv() {
let result = run_generation(&item);
let (state, detail, output) = match result {
- Ok(output) => ("framesReady", "Raw frames and audio are ready for host encoding; no MP4 was created by vidfab.".into(), Some(output)),
+ Ok((metadata, pictures)) => {
+ /* The pictures wait in memory for the webview, which
+ encodes them and asks Rust to write the file. What
+ had to be dropped to make room is said out loud —
+ an abandoned render is a scene that has to be run
+ again, and the user is owed that sentence. */
+ let evicted = rendered::keep(pictures);
+ let detail = match evicted {
+ Some(job) if job != item.request.job_id => format!(
+ "Frames and audio are ready to be encoded. The frames of {job} were dropped to make room and that scene would have to be rendered again."
+ ),
+ _ => "Frames and audio are ready to be encoded.".to_string(),
+ };
+ ("framesReady", detail, Some(metadata))
+ }
Err(error) if item.cancel.load(Ordering::Acquire) => ("cancelled", error, None),
Err(error) => ("failed", error, None),
};
@@ -365,7 +385,13 @@ fn configure_request(
Ok(())
}
-fn run_generation(item: &QueueItem) -> Result<OutputMetadata, String> {
+/// Runs one generation and takes a copy of everything it produced.
+///
+/// The copy is not optional: `api.output` hands back pointers into memory the
+/// generation owns, and `destroy_generation` — which this function always
+/// reaches — frees it. Everything the app will ever have of a render is taken
+/// here or lost here.
+fn run_generation(item: &QueueItem) -> Result<(OutputMetadata, rendered::RenderedVideo), String> {
if item.cancel.load(Ordering::Acquire) {
return Err("Generation was cancelled before it started.".into());
}
@@ -425,21 +451,50 @@ fn run_generation(item: &QueueItem) -> Result<OutputMetadata, String> {
return Err(error);
}
};
+ /* SAFETY: `output` describes buffers the generation owns and keeps alive
+ until `destroy_generation`, which is below and after the copy. The counts
+ are the C API's own, and a null pointer is read as an empty slice rather
+ than dereferenced. */
+ let video = if output.video.is_null() {
+ &[][..]
+ } else {
+ unsafe { std::slice::from_raw_parts(output.video, output.video_float_count) }
+ };
+ let audio = if output.audio.is_null() {
+ &[][..]
+ } else {
+ unsafe { std::slice::from_raw_parts(output.audio, output.audio_float_count) }
+ };
+ let pictures = rendered::from_output(
+ &item.request.job_id,
+ video,
+ audio,
+ output.frames.max(0) as u32,
+ output.width.max(0) as u32,
+ output.height.max(0) as u32,
+ output.channels.max(0) as u32,
+ output.fps,
+ output.audio_channels.max(0) as u32,
+ output.audio_sample_rate.max(0) as u32,
+ );
let metadata = OutputMetadata {
frames: output.frames, width: output.width, height: output.height, fps: output.fps,
audio_channels: output.audio_channels, audio_sample_rate: output.audio_sample_rate,
+ audio_samples: output.audio_float_count,
duration_seconds: if output.fps > 0.0 {
output.frames as f64 / output.fps
} else {
0.0
},
- boundary: "Raw decoded buffers were returned and released. Host encoding is not implemented; no MP4 exists.",
+ boundary: "Raw decoded buffers were copied out and released. The webview encodes them; vidfab wrote no file.",
};
api.destroy_generation(generation);
unsafe {
drop(Box::from_raw(context_ptr));
}
- Ok(metadata)
+ // Only now, with the C API's memory handed back: a conversion that failed
+ // must not leave the generation handle alive behind it.
+ Ok((metadata, pictures?))
}
struct RequestHandle<'a>(*mut ffi::Request, &'a ffi::Api);
diff --git a/src/components/ExitGuardDialog.test.tsx b/src/components/ExitGuardDialog.test.tsx
index 0eb3cfd..7537e90 100644
--- a/src/components/ExitGuardDialog.test.tsx
+++ b/src/components/ExitGuardDialog.test.tsx
@@ -30,10 +30,14 @@ const workspace = (config: ProjectConfig, onBack: () => void) =>
render(createElement(ProjectWorkspace, { project: { folderPath: "C:\\Ceramic Lamp", config }, initialView: "timeline", onBack, onSave: async () => undefined }));
describe("the one definition of an ongoing generation", () => {
- it("is the pair of statuses the Generator queues shots through, and nothing else", () => {
+ it("is every status with something still to lose, and nothing else", () => {
const statuses: GenerationJob["status"][] = ["draft", "queued", "generating", "ready", "completed", "failed", "cancelled"];
const ongoing = statuses.filter((status) => isGenerationOngoing({ status } as GenerationJob));
- expect(ongoing).toEqual(["queued", "generating"]);
+ /* "ready" is in the list because it does not mean finished: the pictures
+ exist and the file does not yet — the app is encoding them into the
+ project folder. Leaving then costs the whole render, exactly as leaving
+ mid-render does. "completed" is the one that means there is a file. */
+ expect(ongoing).toEqual(["queued", "generating", "ready"]);
});
it("counts what is happening without rounding a queued shot up into a rendering one", () => {
@@ -46,7 +50,7 @@ describe("the one definition of an ongoing generation", () => {
describe("leaving a project", () => {
it("goes straight back when nothing is generating", () => {
const onBack = vi.fn();
- workspace(withJobs(["draft", "completed", "failed", "cancelled", "ready"]), onBack);
+ workspace(withJobs(["draft", "completed", "failed", "cancelled"]), onBack);
fireEvent.click(screen.getByRole("button", { name: "Back to project library" }));
expect(onBack).toHaveBeenCalledTimes(1);
expect(screen.queryByRole("alertdialog")).toBeNull();
diff --git a/src/components/ExitGuardDialog.tsx b/src/components/ExitGuardDialog.tsx
index 52533cb..863387f 100644
--- a/src/components/ExitGuardDialog.tsx
+++ b/src/components/ExitGuardDialog.tsx
@@ -18,10 +18,12 @@ const FOCUSABLE = "button:not([disabled]), [href], input, select, textarea, [tab
/** Asks before an exit that would throw away work the engine is still doing.
*
* Every claim it makes is a claim about this codebase, not a hedge:
- * • vidfab writes no file of its own (see `run_generation` in vidfab.rs) and
- * the finished frames only reach the app through the `vidfab-job` event,
- * which is listened for inside the Generator. Leave the project or close
- * the window and there is nothing on disk to come back to.
+ * • vidfab writes no file of its own (see `run_generation` in vidfab.rs). Its
+ * frames reach the app through the `vidfab-job` event, and only once the
+ * app has encoded them (useGenerationEvents → lib/generatedVideo.ts) is
+ * there an .mp4 in the project folder. Leave before that and there is
+ * nothing on disk to come back to — which is why a scene that is still
+ * being encoded counts as ongoing too (see isGenerationOngoing).
* • Nothing resumes. The only route back to a stopped shot is the Generator's
* "Run it again", which starts the whole render from the first step.
*/
diff --git a/src/components/ProjectWorkspace.tsx b/src/components/ProjectWorkspace.tsx
index 5293dcc..359dc8d 100644
--- a/src/components/ProjectWorkspace.tsx
+++ b/src/components/ProjectWorkspace.tsx
@@ -8,15 +8,21 @@ import { ExportView } from "./workspace/ExportView";
import { GeneratorView } from "./workspace/GeneratorView";
import { ReferencesView } from "./workspace/ReferencesView";
import { TimelineView, type ConfigUpdate } from "./workspace/TimelineView";
+import { useGenerationEvents } from "./workspace/useGenerationEvents";
export type ProjectView = "timeline" | "generator" | "references" | "export";
-/** A generation the app is still working on. These are exactly the two statuses
- * the Generator splits into its "Rendering now" and "Waiting to render" groups
- * and locks a shot's references on; the topbar count and the exit guard both
- * read this one predicate, so a badge saying "2" and a warning about what
- * leaving costs can never disagree. */
-export const isGenerationOngoing = (job: GenerationJob) => job.status === "generating" || job.status === "queued";
+/** A generation the app is still working on: waiting for the engine, being
+ * rendered by it, or — `ready` — rendered and being encoded into the file that
+ * will land in the project folder.
+ *
+ * That last one belongs here for the same reason as the other two: until the
+ * .mp4 is written there is nothing on disk, and closing the window in the
+ * seconds it takes to encode throws away the whole render. The topbar count
+ * and the exit guard both read this one predicate, so a badge saying "2" and a
+ * warning about what leaving costs can never disagree. */
+export const isGenerationOngoing = (job: GenerationJob) =>
+ job.status === "generating" || job.status === "queued" || job.status === "ready";
export function formatDurationTimecode(totalSeconds: number): string {
const seconds = Math.max(0, Math.floor(totalSeconds));
@@ -41,6 +47,11 @@ export function ProjectWorkspace({ project, initialView = "timeline", runtime =
onOngoingGenerationsChange?: (jobs: OngoingGeneration[]) => void;
}) {
const [config, setConfig] = useState(project.config);
+ /* What the engine says about a render, and the saving of the file it
+ produces. Mounted HERE, not in the Generator: a render takes minutes, and
+ a user who spends them on the timeline used to unmount the only listeners
+ there were — the finished frames then arrived at nobody and were dropped. */
+ useGenerationEvents({ folderPath: project.folderPath, onChange: (update) => { setConfig(update); setDirty(true); } });
const [view, setView] = useState<ProjectView>(initialView);
const [selectedGenerationJobId, setSelectedGenerationJobId] = useState<string | undefined>(project.config.generationJobs[0]?.id);
const [saving, setSaving] = useState(false);
@@ -71,10 +82,11 @@ export function ProjectWorkspace({ project, initialView = "timeline", runtime =
useEffect(() => { if (ongoing.length === 0) setLeaveGuard(false); }, [ongoing.length]);
const leave = () => {
- /* Nothing resumes, and nothing is written until a shot finishes, so a run
- the user has walked away from can only burn the GPU for a result no one
- is listening for — the events that record it land in the Generator, which
- is about to unmount. Stopped the same way its own stop button stops it. */
+ /* Nothing resumes, and a render that finishes after this screen is gone has
+ nowhere to be recorded: the listeners that save it (useGenerationEvents)
+ belong to this component and go with it. Rather than burn the GPU for a
+ result no one will keep, the runs are stopped the same way their own stop
+ button stops them. */
ongoing.forEach((job) => { void cancelVidfabGeneration(job.id).catch(() => undefined); });
onBack();
};
diff --git a/src/components/workspace/GeneratorView.tsx b/src/components/workspace/GeneratorView.tsx
index 7d16dab..b0d4558 100644
--- a/src/components/workspace/GeneratorView.tsx
+++ b/src/components/workspace/GeneratorView.tsx
@@ -1,5 +1,5 @@
import { listen } from "@tauri-apps/api/event";
-import { AlertCircle, Ban, Check, ChevronRight, Clock3, FileText, Image as ImageIcon, Info, LoaderCircle, Music2, Play, Plus, RefreshCw, Sparkles, Square, Video, WandSparkles, X } from "lucide-react";
+import { AlertCircle, Ban, Check, ChevronRight, Clock3, FileText, Image as ImageIcon, LoaderCircle, Music2, Play, Plus, RefreshCw, Sparkles, Square, Video, WandSparkles, X } from "lucide-react";
import { useEffect, useMemo, useRef, useState } from "react";
import { resolutionLabel } from "../../lib/export";
import { isTauri } from "../../lib/persistence";
@@ -26,10 +26,14 @@ export function GeneratorView({ config, folderPath, runtime = null, onChange, on
configRef.current = config;
const jobs = config.generationJobs;
const selected = jobs.find((job) => job.id === selectedId);
- const active = jobs.filter((job) => job.status === "generating");
+ /* "ready" means the pictures exist and the file does not yet — the app is
+ encoding them. That is work in progress, so it belongs beside the render it
+ came out of rather than under "Already run", where it would sit looking
+ finished with nothing to open. */
+ const active = jobs.filter((job) => job.status === "generating" || job.status === "ready");
const queued = jobs.filter((job) => job.status === "queued");
const drafts = jobs.filter((job) => job.status === "draft");
- const completed = jobs.filter((job) => ["ready", "completed", "failed", "cancelled"].includes(job.status));
+ const completed = jobs.filter((job) => ["completed", "failed", "cancelled"].includes(job.status));
// Queued and generating scenes have already been handed to the engine with
// their references attached; re-binding now would change nothing about that
// run while claiming otherwise.
@@ -96,29 +100,11 @@ export function GeneratorView({ config, folderPath, runtime = null, onChange, on
};
};
- useEffect(() => {
- if (!isTauri()) return;
- let disposed = false;
- const subscriptions = Promise.all([
- listen<{ jobId: string; stage: string; step: number; totalSteps: number }>("vidfab-progress", ({ payload }) => {
- if (disposed) return;
- const progress = payload.totalSteps > 0 ? Math.min(.92, .12 + Math.max(0, payload.step) / payload.totalSteps * .72) : payload.stage === "delivering" ? .95 : .08;
- updateJob(payload.jobId, { status: "generating", stage: payload.stage === "starting" || payload.stage === "transformerLoad" ? "preparing" : "generating", progress, updatedAt: new Date().toISOString() });
- }),
- listen<{ jobId: string; state: string; detail: string }>("vidfab-job", ({ payload }) => {
- if (disposed) return;
- const updates: Partial<GenerationJob> = payload.state === "framesReady"
- ? { status: "ready", stage: "completed", progress: 1, error: payload.detail }
- : payload.state === "failed" ? { status: "failed", stage: "failed", error: payload.detail }
- : payload.state === "cancelled" ? { status: "cancelled", stage: "failed", error: payload.detail }
- : { status: "queued", stage: "queued" };
- updateJob(payload.jobId, { ...updates, updatedAt: new Date().toISOString() });
- }),
- ]);
- return () => { disposed = true; void subscriptions.then((unlisten) => unlisten.forEach((stop) => stop())); };
- // configRef keeps handlers current without resubscribing per progress tick.
- // eslint-disable-next-line react-hooks/exhaustive-deps
- }, [onChange]);
+ /* The engine's own events are listened for by the project screen
+ (useGenerationEvents), not here: a render outlives this view, and the
+ encode that turns its frames into a file has to happen wherever the user
+ happens to be. What this view does with a scene is start it, stop it, and
+ show what became of it. */
const prepareOrRetry = async (job: GenerationJob) => {
const now = new Date().toISOString();
@@ -382,12 +368,7 @@ export function GeneratorView({ config, folderPath, runtime = null, onChange, on
<button className="primary-button" disabled={!runtimeReady || Boolean(blocked)} onClick={() => void startDraft(selected)}>
<WandSparkles size={15} /> {runtimeReady ? (jobs.length === 1 ? "Generate your first scene" : "Generate this scene") : "Can’t generate yet"}
</button>
- {/* Disclosed at the point of commitment, not after an expensive
- run. This used to sit under the composer's submit button; the
- button that actually starts a render is this one. */}
- {runtimeReady
- ? <p className="job-actions__limit"><Info size={16} /><span>A finished scene renders frames into memory. PolStudio can’t save them as a video file yet, so nothing lands in your project folder and there is nothing to add to the timeline.</span></p>
- : <p className="job-actions__note">This draft is saved with your project. PolStudio needs a working video engine before it can render it.</p>}
+ {!runtimeReady && <p className="job-actions__note">This draft is saved with your project. PolStudio needs a working video engine before it can render it.</p>}
</>}
{(selected.status === "failed" || selected.status === "cancelled") && <>
@@ -397,22 +378,23 @@ export function GeneratorView({ config, folderPath, runtime = null, onChange, on
{!runtimeReady && <p className="job-actions__note">PolStudio needs a working video engine before it can run this scene again.</p>}
</>}
- {selected.status === "ready" && <>
- <div className="job-actions__blocked">
- <b>There is nothing to open yet</b>
- <p>The frames and sound were rendered and are held in memory, but PolStudio can’t package them into a video file yet — that step isn’t built. Nothing was written to your project folder.</p>
- </div>
- <div className="job-actions__choices">
- <button className="primary-button" disabled={!runtimeReady || Boolean(blocked)} onClick={() => void prepareOrRetry(selected)}>
- <RefreshCw size={15} /> {runtimeReady ? "Run this scene again" : "Can’t run it again yet"}
- </button>
- <button className="secondary-button" onClick={newScene}>
- <Plus size={15} /> Start another scene
- </button>
- </div>
+ {/* Between the last frame and the file: the pictures are rendered
+ and are being encoded into an .mp4 in the project folder. It is
+ a real step with a real duration — a few hundred megabytes
+ through the machine's encoder — so it is a state, not a
+ flicker. */}
+ {selected.status === "ready" && <p className="job-actions__note">
+ <LoaderCircle size={15} className="spin" /> Saving this scene into your project folder…
+ </p>}
+
+ {selected.status === "completed" && selected.outputRelativePath && !selected.clipId && <>
+ <button className="primary-button" onClick={() => insertIntoStory(selected)}><Play size={15} /> Insert into Track 1</button>
+ <p className="job-actions__note">Saved to <code>{selected.outputRelativePath}</code>.</p>
</>}
- {selected.status === "completed" && selected.outputRelativePath && !selected.clipId && <button className="primary-button" onClick={() => insertIntoStory(selected)}><Play size={15} /> Insert into Track 1</button>}
+ {/* Something was left out of the file — the scene is finished and
+ the file exists, so this is a note rather than a failure. */}
+ {selected.status === "completed" && selected.outputRelativePath && selected.error && <p className="job-actions__note">{selected.error}</p>}
{selected.status === "completed" && selected.clipId && <button className="primary-button" onClick={onOpenTimeline}><Play size={15} /> Open in timeline</button>}
@@ -420,7 +402,7 @@ export function GeneratorView({ config, folderPath, runtime = null, onChange, on
<button className="primary-button" disabled={!runtimeReady || Boolean(blocked)} onClick={() => void prepareOrRetry(selected)}>
<RefreshCw size={15} /> {runtimeReady ? "Run this scene again" : "Can’t run it again yet"}
</button>
- <p className="job-actions__note">This run finished without saving a video file, so there is nothing to add to your edit.</p>
+ <p className="job-actions__note">This run finished without a video file in your project folder, so there is nothing to add to your edit.</p>
</>}
</div>
</aside>
@@ -527,17 +509,20 @@ const referenceKindIcon = (kind: ProjectReference["kind"]) =>
: kind === "image" ? <ImageIcon size={16} />
: <FileText size={16} />;
+/* The three things that happen to a scene, in the order they happen. "Save" is
+ the encode: the engine's pictures being written into an .mp4 in the project
+ folder, which is the last tenth of the bar. */
const STAGES: Array<{ label: string; at: number }> = [
{ label: "Prepare", at: 0.01 },
{ label: "Render", at: 0.5 },
- { label: "Frames ready", at: 1 },
+ { label: "Save", at: 0.9 },
];
const STATUS_BADGE: Record<JobStatus, string> = {
draft: "DRAFT",
queued: "IN QUEUE",
generating: "RENDERING",
- ready: "FRAMES RENDERED",
+ ready: "SAVING",
completed: "FINISHED",
failed: "FAILED",
cancelled: "CANCELLED",
@@ -547,7 +532,7 @@ const STATUS_WORD: Record<JobStatus, string> = {
draft: "Saved as a draft",
queued: "Waiting to render",
generating: "Rendering now",
- ready: "Frames rendered, held in memory",
+ ready: "Saving the video file",
completed: "Finished",
failed: "Stopped by an error",
cancelled: "Stopped by you",
@@ -567,21 +552,23 @@ const queueLine = (job: GenerationJob) => {
case "generating": return `Rendering · ${Math.round(job.progress * 100)}%`;
case "queued": return "Waiting its turn";
case "draft": return `Draft — ${shape}`;
- case "ready": return "Frames rendered · no video file";
+ case "ready": return `Saving the video file · ${Math.round(job.progress * 100)}%`;
case "completed": return job.outputRelativePath ? `Ready to use · ${shape}` : "Finished with no file";
case "failed": return "Didn’t finish";
case "cancelled": return "Cancelled";
}
};
-const statusIcon = (status: JobStatus) => status === "generating" ? <LoaderCircle size={16} /> : status === "completed" || status === "ready" ? <Check size={16} /> : status === "failed" ? <AlertCircle size={16} /> : status === "cancelled" ? <Ban size={16} /> : <Clock3 size={16} />;
+/* Encoding turns the same spinner as rendering: it is the app working, not the
+ app waiting, and a tick beside "saving" would say it was already done. */
+const statusIcon = (status: JobStatus) => status === "generating" || status === "ready" ? <LoaderCircle size={16} /> : status === "completed" ? <Check size={16} /> : status === "failed" ? <AlertCircle size={16} /> : status === "cancelled" ? <Ban size={16} /> : <Clock3 size={16} />;
const progressTitle = (job: GenerationJob) => {
switch (job.status) {
case "generating": return `${Math.round(job.progress * 100)}% rendered`;
case "queued": return "Waiting to start";
case "draft": return "Draft saved";
- case "ready": return "Frames rendered";
+ case "ready": return "Saving the video file";
case "completed": return job.outputRelativePath ? "Ready for your edit" : "Finished with no file";
case "failed": return "Didn’t finish";
case "cancelled": return "Generation stopped";
@@ -593,7 +580,7 @@ const stageCopy = (job: GenerationJob) => {
case "generating": return "The video engine is building the motion and the sound.";
case "queued": return "Waiting for the scene ahead of it to finish.";
case "draft": return "Saved with your project. Nothing has been rendered yet.";
- case "ready": return "The frames and sound exist in memory. PolStudio can’t package them into a video file yet.";
+ case "ready": return "The pictures are rendered. They are being encoded into a video file in your project folder.";
case "completed": return job.outputRelativePath ? "Saved in your project and ready to drop into the timeline." : "This run ended without saving a video file.";
case "failed": return "The run stopped before it finished. You can try it again.";
case "cancelled": return "You stopped this one. You can run it again.";
@@ -605,7 +592,7 @@ const previewStatus = (job: GenerationJob) => {
case "generating": return <><LoaderCircle size={15} /> Rendering {Math.round(job.progress * 100)}%</>;
case "queued": return <><Clock3 size={15} /> Waiting in queue</>;
case "draft": return <><Clock3 size={15} /> Draft — nothing rendered</>;
- case "ready": return <><Check size={15} /> Frames rendered</>;
+ case "ready": return <><LoaderCircle size={15} /> Saving {Math.round(job.progress * 100)}%</>;
case "completed": return job.outputRelativePath ? <><Check size={15} /> Ready for your edit</> : <><AlertCircle size={15} /> No video file was saved</>;
case "failed": return <><AlertCircle size={15} /> Generation failed</>;
case "cancelled": return <><Ban size={15} /> Generation cancelled</>;
@@ -619,7 +606,7 @@ const previewCaption = (job: GenerationJob): string => {
case "generating": return "Frames are being built now. PolStudio can’t show them while they are still in memory.";
case "queued": return "This scene hasn’t started, so there is no picture to show.";
case "draft": return "Nothing has been rendered, so there is no picture to show.";
- case "ready": return "The frames exist in memory only. PolStudio can’t display or save them yet.";
+ case "ready": return "The pictures are being encoded into a video file. It can be watched in the timeline once it lands.";
case "completed": return job.outputRelativePath ? "A video file was saved. Open it in the timeline to watch it." : "This run ended without a video file, so there is no picture to show.";
case "failed": return "The run stopped before any frames were kept.";
case "cancelled": return "You stopped this run, so no frames were kept.";
diff --git a/src/components/workspace/useGenerationEvents.test.tsx b/src/components/workspace/useGenerationEvents.test.tsx
new file mode 100644
index 0000000..0d6b8e7
--- /dev/null
+++ b/src/components/workspace/useGenerationEvents.test.tsx
@@ -0,0 +1,166 @@
+// @vitest-environment jsdom
+
+import { listen } from "@tauri-apps/api/event";
+import { act, cleanup, render } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { saveGeneratedScene } from "../../lib/generatedVideo";
+import { createProjectConfig, parseProjectConfig, type ProjectConfig } from "../../lib/project";
+import { useGenerationEvents } from "./useGenerationEvents";
+
+vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn() }));
+vi.mock("@tauri-apps/api/event", () => ({ listen: vi.fn() }));
+vi.mock("../../lib/generatedVideo", () => ({ saveGeneratedScene: vi.fn() }));
+
+const scope = globalThis as unknown as Record<string, unknown>;
+/** Handlers the hook registered, by event name. */
+const handlers = new Map<string, (event: { payload: unknown }) => void>();
+
+beforeEach(() => {
+ handlers.clear();
+ scope.__TAURI_INTERNALS__ = {};
+ // Cleared, not just re-implemented: one test asserts it was never called.
+ vi.mocked(listen).mockReset();
+ vi.mocked(listen).mockImplementation((async (name: string, handler: (event: { payload: unknown }) => void) => {
+ handlers.set(name, handler);
+ return () => handlers.delete(name);
+ }) as unknown as typeof listen);
+ vi.mocked(saveGeneratedScene).mockReset();
+});
+afterEach(() => {
+ cleanup();
+ delete scope.__TAURI_INTERNALS__;
+});
+
+/** A project with one draft scene, and a harness that keeps whatever the hook
+ * writes — the same shape the workspace holds it in. */
+function harness() {
+ const fresh = createProjectConfig({ name: "Ceramic lamp", prompt: "A quiet product film", aspectRatio: "16:9", resolution: "1080p", targetDurationSeconds: 30 });
+ const state = { config: fresh };
+ function Harness() {
+ useGenerationEvents({ folderPath: "C:\\Ceramic Lamp", onChange: (update) => { state.config = update(state.config); } });
+ return null;
+ }
+ render(<Harness />);
+ return { state, jobId: fresh.generationJobs[0].id, job: () => state.config.generationJobs[0] };
+}
+
+const emit = async (name: string, payload: unknown) => {
+ await act(async () => {
+ handlers.get(name)?.({ payload });
+ await Promise.resolve();
+ });
+};
+
+describe("what the app does with the engine's events", () => {
+ it("saves the frames the moment the engine says they are ready, and records the file", async () => {
+ vi.mocked(saveGeneratedScene).mockResolvedValue({ relativePath: "media/generated/job-01.mp4", bytes: 4_200_000, note: null });
+ const { jobId, job, state } = harness();
+ await emit("vidfab-job", { jobId, state: "framesReady", detail: "Frames and audio are ready to be encoded." });
+
+ expect(saveGeneratedScene).toHaveBeenCalledWith(expect.objectContaining({ folderPath: "C:\\Ceramic Lamp", jobId }));
+ expect(job()).toMatchObject({
+ status: "completed",
+ stage: "completed",
+ progress: 1,
+ outputRelativePath: "media/generated/job-01.mp4",
+ error: null,
+ });
+ // What was written has to survive a save and a reload, so it has to parse.
+ expect(parseProjectConfig(state.config)).toBeTruthy();
+ });
+
+ it("keeps the note when something was left out of the file", async () => {
+ vi.mocked(saveGeneratedScene).mockResolvedValue({ relativePath: "media/generated/job-01.mp4", bytes: 10, note: "Saved without sound: this computer's encoder would not take the render's audio." });
+ const { jobId, job } = harness();
+ await emit("vidfab-job", { jobId, state: "framesReady", detail: "" });
+ // Finished, with the file — and still saying what is missing from it.
+ expect(job().status).toBe("completed");
+ expect(job().error).toMatch(/without sound/);
+ });
+
+ it("calls a render that could not be written a failure, not a finished scene", async () => {
+ vi.mocked(saveGeneratedScene).mockRejectedValue(new Error("This computer's encoder refused every H.264 configuration."));
+ const { jobId, job } = harness();
+ await emit("vidfab-job", { jobId, state: "framesReady", detail: "" });
+ expect(job()).toMatchObject({ status: "failed", stage: "failed" });
+ expect(job().error).toMatch(/rendered but could not be saved/);
+ // Nothing to insert into a timeline, and the job must not claim otherwise.
+ expect(job().outputRelativePath ?? null).toBeNull();
+ });
+
+ it("encodes one set of frames once, however many times the event arrives", async () => {
+ let release = () => undefined as void;
+ vi.mocked(saveGeneratedScene).mockImplementation(() => new Promise((resolve) => {
+ release = () => resolve({ relativePath: "media/generated/job-01.mp4", bytes: 1, note: null });
+ }));
+ const { jobId } = harness();
+ await emit("vidfab-job", { jobId, state: "framesReady", detail: "" });
+ await emit("vidfab-job", { jobId, state: "framesReady", detail: "" });
+ expect(saveGeneratedScene).toHaveBeenCalledTimes(1);
+ await act(async () => { release(); await Promise.resolve(); });
+ });
+
+ it("carries progress through the render and then through the encode", async () => {
+ let report: ((encoded: number, total: number) => void) | undefined;
+ vi.mocked(saveGeneratedScene).mockImplementation(async (options) => {
+ report = options.onProgress;
+ return { relativePath: "media/generated/job-01.mp4", bytes: 1, note: null };
+ });
+ const { jobId, job } = harness();
+
+ await emit("vidfab-progress", { jobId, stage: "denoising", step: 25, totalSteps: 50 });
+ const rendering = job().progress;
+ expect(job().status).toBe("generating");
+ // Rendering never reaches the part of the bar encoding owns, so a finished
+ // render cannot look like a stalled one.
+ expect(rendering).toBeGreaterThan(0.12);
+ expect(rendering).toBeLessThan(0.9);
+
+ await emit("vidfab-job", { jobId, state: "framesReady", detail: "" });
+ await act(async () => { report?.(60, 120); await Promise.resolve(); });
+ expect(job().status).toBe("completed");
+ });
+
+ it("passes queued, failed and cancelled through as themselves", async () => {
+ const { jobId, job } = harness();
+ await emit("vidfab-job", { jobId, state: "queued", detail: "Queued behind any active vidfab generation." });
+ expect(job()).toMatchObject({ status: "queued", stage: "queued" });
+
+ await emit("vidfab-job", { jobId, state: "failed", detail: "The transformer weights could not be read." });
+ expect(job()).toMatchObject({ status: "failed", stage: "failed", error: "The transformer weights could not be read." });
+
+ await emit("vidfab-job", { jobId, state: "cancelled", detail: "Generation cancelled at the next vidfab checkpoint." });
+ expect(job()).toMatchObject({ status: "cancelled", stage: "failed" });
+ expect(saveGeneratedScene).not.toHaveBeenCalled();
+ });
+
+ it("listens for nothing in the browser preview, where there is no engine", () => {
+ delete scope.__TAURI_INTERNALS__;
+ harness();
+ expect(listen).not.toHaveBeenCalled();
+ });
+});
+
+/** The workspace holds the config this hook writes into; a stale copy would
+ * undo whatever else the app did while a render was running. */
+describe("how the hook writes", () => {
+ it("hands up an updater rather than a config it read minutes ago", async () => {
+ vi.mocked(saveGeneratedScene).mockResolvedValue({ relativePath: "media/generated/job-01.mp4", bytes: 1, note: null });
+ const writes: Array<(current: ProjectConfig) => ProjectConfig> = [];
+ const fresh = createProjectConfig({ name: "Ceramic lamp", prompt: "A quiet product film", aspectRatio: "16:9", resolution: "1080p", targetDurationSeconds: 30 });
+ function Harness() {
+ useGenerationEvents({ folderPath: "C:\\Ceramic Lamp", onChange: (update) => { writes.push(update); } });
+ return null;
+ }
+ render(<Harness />);
+ await emit("vidfab-job", { jobId: fresh.generationJobs[0].id, state: "framesReady", detail: "" });
+ expect(writes.length).toBeGreaterThan(0);
+ expect(writes.every((write) => typeof write === "function")).toBe(true);
+ // Applied to a config the hook never saw — a project renamed while the
+ // render ran — the rename survives and the scene is still finished.
+ const renamed = { ...fresh, name: "Renamed mid-render" };
+ const result = writes.reduce((config, write) => write(config), renamed);
+ expect(result.name).toBe("Renamed mid-render");
+ expect(result.generationJobs[0].outputRelativePath).toBe("media/generated/job-01.mp4");
+ });
+});
diff --git a/src/components/workspace/useGenerationEvents.ts b/src/components/workspace/useGenerationEvents.ts
new file mode 100644
index 0000000..f3975a5
--- /dev/null
+++ b/src/components/workspace/useGenerationEvents.ts
@@ -0,0 +1,142 @@
+import { listen } from "@tauri-apps/api/event";
+import { useEffect, useRef } from "react";
+import { saveGeneratedScene } from "../../lib/generatedVideo";
+import { isTauri } from "../../lib/persistence";
+import type { GenerationJob, ProjectConfig } from "../../lib/project";
+
+/* Everything the video engine says about a scene, and what to do about it.
+ *
+ * This lives in the WORKSPACE rather than in the Generator, and that is the
+ * point: a render takes minutes, and the natural thing to do while it runs is
+ * to go and work on the timeline. When these listeners were mounted by the
+ * Generator, doing that unmounted them — progress stopped landing, and the
+ * event announcing a finished render arrived at nobody. Now the whole project
+ * screen carries them, so a scene that finishes while the user is somewhere
+ * else is still recorded and still saved.
+ *
+ * Saving is the second half. vidfab produces pictures and frees them; a finished
+ * render is a few hundred megabytes waiting in Rust's memory that nothing else
+ * will claim. As soon as the engine says the frames are ready, this encodes
+ * them (see lib/generatedVideo.ts) and writes the .mp4 into the project. */
+
+/** The event the queue emits when a scene's state changes. */
+interface JobEvent {
+ jobId: string;
+ state: "queued" | "framesReady" | "failed" | "cancelled" | string;
+ detail: string;
+}
+
+interface ProgressEvent {
+ jobId: string;
+ stage: string;
+ step: number;
+ totalSteps: number;
+}
+
+/** Rendering is most of the wait, so it owns most of the bar; encoding is the
+ * last slice, and it gets its own so a finished render does not sit at 92%
+ * looking stalled while the encoder works. */
+const RENDER_CEILING = 0.9;
+const ENCODE_FLOOR = 0.9;
+
+export function useGenerationEvents({ folderPath, onChange }: {
+ folderPath: string;
+ /** The updater form, always: every write here happens after an await, so the
+ * config this component last saw is not the one to build from. */
+ onChange: (update: (current: ProjectConfig) => ProjectConfig) => void;
+}) {
+ /* Held in refs so the subscription is made ONCE. It has to be: re-subscribing
+ on every progress tick would drop events in the gap, and these events are
+ the only record that a render happened at all. */
+ const write = useRef(onChange);
+ write.current = onChange;
+ const folder = useRef(folderPath);
+ folder.current = folderPath;
+ /** Scenes already being encoded, so a repeated event — or a remount in
+ * StrictMode — cannot start a second encode of the same frames. */
+ const saving = useRef(new Set<string>());
+
+ useEffect(() => {
+ if (!isTauri()) return;
+ let disposed = false;
+ const updateJob = (jobId: string, updates: Partial<GenerationJob>) => {
+ write.current((current) => ({
+ ...current,
+ generationJobs: current.generationJobs.map((job) => (job.id === jobId ? { ...job, ...updates, updatedAt: new Date().toISOString() } : job)),
+ }));
+ };
+
+ /** Encode the frames the engine just finished, and write the file.
+ *
+ * This deliberately keeps going after `disposed`: the project screen can
+ * unmount while an encode is in flight, and stopping there would leave the
+ * frames in memory and the scene with nothing to show for the render. The
+ * writes it makes are updaters against whatever config is current, and the
+ * Rust side is told to let the frames go either way. */
+ const save = async (jobId: string) => {
+ if (saving.current.has(jobId)) return;
+ saving.current.add(jobId);
+ updateJob(jobId, { status: "ready", stage: "encoding", progress: ENCODE_FLOOR, error: null });
+ try {
+ const saved = await saveGeneratedScene({
+ folderPath: folder.current,
+ jobId,
+ onProgress: (encoded, total) => {
+ if (total > 0) updateJob(jobId, { progress: Math.min(0.99, ENCODE_FLOOR + (encoded / total) * (1 - ENCODE_FLOOR)) });
+ },
+ });
+ updateJob(jobId, {
+ status: "completed",
+ stage: "completed",
+ progress: 1,
+ outputRelativePath: saved.relativePath,
+ // A note means something was left out of the file — the file exists
+ // and the scene is finished, so this is not a failure, but it is not
+ // silence either.
+ error: saved.note,
+ });
+ } catch (reason) {
+ /* The render happened and the file did not. Failed is the honest state:
+ there is nothing to insert into the timeline, and the only way to get
+ this scene is to run it again. */
+ updateJob(jobId, {
+ status: "failed",
+ stage: "failed",
+ error: `The scene rendered but could not be saved as a video file. ${reason instanceof Error ? reason.message : String(reason)}`,
+ });
+ } finally {
+ saving.current.delete(jobId);
+ }
+ };
+
+ const subscriptions = Promise.all([
+ listen<ProgressEvent>("vidfab-progress", ({ payload }) => {
+ if (disposed) return;
+ const progress = payload.totalSteps > 0
+ ? Math.min(RENDER_CEILING - 0.02, 0.12 + (Math.max(0, payload.step) / payload.totalSteps) * (RENDER_CEILING - 0.14))
+ : payload.stage === "delivering" ? RENDER_CEILING - 0.02 : 0.08;
+ updateJob(payload.jobId, {
+ status: "generating",
+ stage: payload.stage === "starting" || payload.stage === "transformerLoad" ? "preparing" : "generating",
+ progress,
+ });
+ }),
+ listen<JobEvent>("vidfab-job", ({ payload }) => {
+ if (disposed) return;
+ if (payload.state === "framesReady") {
+ void save(payload.jobId);
+ return;
+ }
+ updateJob(payload.jobId, payload.state === "failed"
+ ? { status: "failed", stage: "failed", error: payload.detail }
+ : payload.state === "cancelled"
+ ? { status: "cancelled", stage: "failed", error: payload.detail }
+ : { status: "queued", stage: "queued" });
+ }),
+ ]);
+ return () => {
+ disposed = true;
+ void subscriptions.then((unlisten) => unlisten.forEach((stop) => stop()));
+ };
+ }, []);
+}
diff --git a/src/lib/generatedVideo.test.ts b/src/lib/generatedVideo.test.ts
new file mode 100644
index 0000000..a955266
--- /dev/null
+++ b/src/lib/generatedVideo.test.ts
@@ -0,0 +1,93 @@
+// @vitest-environment jsdom
+
+import { invoke } from "@tauri-apps/api/core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { releaseRendered, renderedSummary, saveGeneratedScene } from "./generatedVideo";
+
+vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn() }));
+
+const invoked = vi.mocked(invoke);
+const scope = globalThis as unknown as Record<string, unknown>;
+
+/** A render waiting in Rust's memory, as `generated_summary` reports it. */
+const summary = (over: Record<string, unknown> = {}) => ({
+ jobId: "job-01", width: 1344, height: 768, frameCount: 120, fps: 24,
+ audioChannels: 2, audioSampleRate: 48_000, audioSamples: 480_000, ...over,
+});
+
+const desktop = () => { scope.__TAURI_INTERNALS__ = {}; };
+
+beforeEach(() => {
+ invoked.mockReset();
+ delete scope.__TAURI_INTERNALS__;
+ delete scope.VideoEncoder;
+ delete scope.VideoFrame;
+});
+afterEach(() => {
+ delete scope.__TAURI_INTERNALS__;
+ delete scope.VideoEncoder;
+ delete scope.VideoFrame;
+});
+
+/* jsdom has no WebCodecs, so nothing here encodes anything — and that is
+ exactly the half worth pinning in a test. What a save does BEFORE the
+ encoder is where it can be wrong in ways that cost the user a render: asking
+ the wrong side of the app, keeping hold of half a gigabyte of frames after a
+ failure, or reporting a file that was never written. */
+describe("saving a rendered scene", () => {
+ it("cannot save from the browser preview, and says which half is missing", async () => {
+ await expect(saveGeneratedScene({ folderPath: "/p", jobId: "job-01" })).rejects.toThrow(/desktop app/);
+ expect(invoked).not.toHaveBeenCalled();
+ });
+
+ it("says a webview with no encoder cannot make a video file", async () => {
+ desktop();
+ await expect(saveGeneratedScene({ folderPath: "/p", jobId: "job-01" })).rejects.toThrow(/no WebCodecs VideoEncoder/);
+ // Nothing was asked of Rust: there is no point pulling frames that cannot
+ // be encoded.
+ expect(invoked).not.toHaveBeenCalled();
+ });
+
+ it("says when the frames are gone rather than writing an empty file", async () => {
+ desktop();
+ scope.VideoEncoder = class {};
+ scope.VideoFrame = class {};
+ invoked.mockResolvedValueOnce(null);
+ await expect(saveGeneratedScene({ folderPath: "/p", jobId: "job-01" })).rejects.toThrow(/no longer in memory/);
+ expect(invoked).toHaveBeenCalledWith("generated_summary", { jobId: "job-01" });
+ });
+
+ it("hands the frames back even when the encode never starts", async () => {
+ desktop();
+ /* An encoder that refuses every configuration. Hundreds of megabytes are
+ waiting in Rust at this point, and a save that gives up without
+ releasing them leaks the lot for the life of the app. */
+ scope.VideoEncoder = { isConfigSupported: async () => ({ supported: false }) };
+ scope.VideoFrame = class {};
+ invoked.mockImplementation(async (command: string) => (command === "generated_summary" ? summary() : true));
+ await expect(saveGeneratedScene({ folderPath: "/p", jobId: "job-01" })).rejects.toThrow(/refused every H.264/);
+ expect(invoked).toHaveBeenCalledWith("release_generated_frames", { jobId: "job-01" });
+ });
+
+ it("refuses a render with no pictures in it", async () => {
+ desktop();
+ scope.VideoEncoder = class {};
+ scope.VideoFrame = class {};
+ invoked.mockResolvedValueOnce(summary({ frameCount: 0 }));
+ await expect(saveGeneratedScene({ folderPath: "/p", jobId: "job-01" })).rejects.toThrow(/no pictures/);
+ });
+});
+
+describe("what the app asks Rust about a render", () => {
+ it("reports nothing waiting in the browser preview instead of calling a command that is not there", async () => {
+ await expect(renderedSummary("job-01")).resolves.toBeNull();
+ await expect(releaseRendered("job-01")).resolves.toBe(false);
+ expect(invoked).not.toHaveBeenCalled();
+ });
+
+ it("never lets a failed release become a failed save", async () => {
+ desktop();
+ invoked.mockRejectedValueOnce(new Error("the queue lock is poisoned"));
+ await expect(releaseRendered("job-01")).resolves.toBe(false);
+ });
+});
diff --git a/src/lib/generatedVideo.ts b/src/lib/generatedVideo.ts
new file mode 100644
index 0000000..15611ab
--- /dev/null
+++ b/src/lib/generatedVideo.ts
@@ -0,0 +1,322 @@
+import { invoke } from "@tauri-apps/api/core";
+import { bitrateFor, outputCodec } from "./export";
+import { isTauri } from "./persistence";
+
+/* Turning a finished render into a file in the project folder.
+ *
+ * vidfab makes pictures, not files: it hands Rust raw frames and raw audio and
+ * frees them. Encoding is this side's job — WebCodecs owns the machine's
+ * hardware encoder and PolStudio ships no FFmpeg by design (CLAUDE.md) — so a
+ * saved scene is a round trip:
+ *
+ * Rust holds the frames → this reads them one at a time → WebCodecs
+ * encodes → mp4-muxer muxes → Rust writes the .mp4 into the project.
+ *
+ * The frames are pulled ONE AT A TIME rather than in a single read, because a
+ * whole render is hundreds of megabytes and the encoder only ever wants the
+ * next one. What is held in memory here is one frame plus whatever the encoder
+ * has not yet drained.
+ *
+ * Nothing here invents a fallback. A machine with no VideoEncoder cannot save a
+ * scene, and this says so rather than writing something that is not a video. */
+
+/** The shape of a render still waiting in Rust's memory. */
+export interface RenderedSummary {
+ jobId: string;
+ width: number;
+ height: number;
+ frameCount: number;
+ fps: number;
+ audioChannels: number;
+ audioSampleRate: number;
+ /** Interleaved samples across every channel. Zero means it rendered silent. */
+ audioSamples: number;
+}
+
+/** What was written, in the project's own terms. */
+export interface SavedGeneration {
+ /** The path to record on the job — Rust's own answer, never a guess here. */
+ relativePath: string;
+ bytes: number;
+ /** Null when everything the render produced is in the file. A sentence when
+ * something was left out, so a silent video is never silently silent. */
+ note: string | null;
+}
+
+/** How often a keyframe is written: every two seconds, so the file can be
+ * seeked and a long delta chain cannot quietly cost quality. */
+const KEYFRAME_SECONDS = 2;
+/** How many frames may be in flight before this stops handing the encoder more.
+ * Each one is a full picture, so an unbounded queue is an unbounded heap. */
+const ENCODE_QUEUE_LIMIT = 8;
+const AUDIO_BLOCK = 1024;
+const AUDIO_CODEC = "mp4a.40.2";
+const AUDIO_BITRATE = 192_000;
+/** Generated footage is a MASTER, not a delivery file: it is what every later
+ * export is cut from, so it is encoded at the highest preset the app has. */
+const GENERATED_QUALITY = "high" as const;
+
+const describe = (reason: unknown) => (reason instanceof Error ? reason.message : String(reason));
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+/** What Rust still holds for this scene, or null if nothing does. */
+export async function renderedSummary(jobId: string): Promise<RenderedSummary | null> {
+ if (!isTauri()) return null;
+ return invoke<RenderedSummary | null>("generated_summary", { jobId });
+}
+
+/** One frame's pixels, RGBA, straight out of the render. */
+async function renderedFrame(jobId: string, index: number): Promise<Uint8Array> {
+ return new Uint8Array(await invoke<ArrayBuffer>("generated_frame", { jobId, index }));
+}
+
+/** The render's soundtrack, interleaved, as Rust holds it. */
+async function renderedAudio(jobId: string): Promise<Float32Array> {
+ return new Float32Array(await invoke<ArrayBuffer>("generated_audio", { jobId }));
+}
+
+/** Gives the frames back. Called on the way out whether or not a file was
+ * written: a render nobody can encode is still hundreds of megabytes. */
+export async function releaseRendered(jobId: string): Promise<boolean> {
+ if (!isTauri()) return false;
+ return invoke<boolean>("release_generated_frames", { jobId }).catch(() => false);
+}
+
+/** Writes the muxed bytes into the project folder. The path is Rust's to
+ * decide — this names the scene, not the file. Raw IPC body for the same
+ * reason an export uses one: a JSON array of numbers for a 30 MB file is
+ * hundreds of megabytes of text. */
+async function writeGeneratedVideo(folderPath: string, jobId: string, bytes: Uint8Array): Promise<{ relativePath: string; bytes: number }> {
+ return invoke<{ relativePath: string; bytes: number }>("write_generated_video", bytes, {
+ headers: {
+ "x-generated-folder": encodeURIComponent(folderPath),
+ "x-generated-job": encodeURIComponent(jobId),
+ },
+ });
+}
+
+/** The codec string this machine actually accepts for this picture, asked of
+ * the encoder rather than assumed from the name. */
+async function pickCodec(width: number, height: number, fps: number, bitrate: number): Promise<{ codec: string; tried: string[] }> {
+ const tried: string[] = [];
+ for (const candidate of outputCodec("h264").candidates(width, height, fps)) {
+ tried.push(candidate);
+ const config: VideoEncoderConfig = {
+ codec: candidate,
+ width,
+ height,
+ bitrate,
+ framerate: fps,
+ // Length-prefixed AVC with the parameter sets in the sample description,
+ // which is the only shape mp4-muxer can put in an .mp4.
+ avc: { format: "avc" },
+ };
+ const support = await VideoEncoder.isConfigSupported(config).catch(() => ({ supported: false }));
+ if (support.supported) return { codec: candidate, tried };
+ }
+ throw new Error(`This computer's encoder refused every H.264 configuration PolStudio offers (${tried.join(", ")}).`);
+}
+
+/** Makes a `VideoFrame` out of raw RGBA.
+ *
+ * The buffer constructor is the direct route and what every current Chromium
+ * supports; a webview that refuses it gets the canvas route instead, which
+ * copies the same pixels through an ImageData. Which one is in use is decided
+ * ONCE, on the first frame, so a fallback is not re-tested 360 times. */
+function frameFactory(width: number, height: number) {
+ let viaCanvas: CanvasRenderingContext2D | null = null;
+ const canvasFrame = (pixels: Uint8Array, timestamp: number, duration: number) => {
+ if (!viaCanvas) {
+ const canvas = document.createElement("canvas");
+ canvas.width = width;
+ canvas.height = height;
+ const context = canvas.getContext("2d", { willReadFrequently: false });
+ if (!context) throw new Error("This computer gave no 2D canvas to build frames in.");
+ viaCanvas = context;
+ }
+ viaCanvas.putImageData(new ImageData(new Uint8ClampedArray(pixels.buffer, pixels.byteOffset, pixels.byteLength), width, height), 0, 0);
+ return new VideoFrame(viaCanvas.canvas, { timestamp, duration, alpha: "discard" });
+ };
+ let direct = true;
+ return (pixels: Uint8Array, timestamp: number, duration: number): VideoFrame => {
+ if (direct) {
+ try {
+ return new VideoFrame(pixels, {
+ format: "RGBA",
+ codedWidth: width,
+ codedHeight: height,
+ timestamp,
+ duration,
+ });
+ } catch {
+ direct = false;
+ }
+ }
+ return canvasFrame(pixels, timestamp, duration);
+ };
+}
+
+/** Whether this machine will encode the render's own sound as AAC. The render
+ * decides the rate and the channel count, so the question is asked with those
+ * numbers rather than with the export pipeline's 48 kHz stereo. */
+async function audioSupported(summary: RenderedSummary): Promise<boolean> {
+ if (summary.audioSamples === 0 || summary.audioChannels <= 0 || summary.audioSampleRate <= 0) return false;
+ if (typeof AudioEncoder === "undefined" || typeof AudioData === "undefined") return false;
+ const support = await AudioEncoder.isConfigSupported({
+ codec: AUDIO_CODEC,
+ sampleRate: summary.audioSampleRate,
+ numberOfChannels: summary.audioChannels,
+ bitrate: AUDIO_BITRATE,
+ }).catch(() => ({ supported: false }));
+ return Boolean(support.supported);
+}
+
+/** Feeds the render's interleaved samples to the AAC encoder, in the blocks
+ * AAC works in. */
+async function encodeAudio(
+ summary: RenderedSummary,
+ samples: Float32Array,
+ add: (chunk: EncodedAudioChunk, meta?: EncodedAudioChunkMetadata) => void,
+): Promise<void> {
+ const channels = summary.audioChannels;
+ const total = Math.floor(samples.length / channels);
+ const failure: { reason: Error | null } = { reason: null };
+ const encoder = new AudioEncoder({
+ output: (chunk, meta) => add(chunk, meta),
+ error: (reason) => { failure.reason = reason instanceof Error ? reason : new Error(String(reason)); },
+ });
+ encoder.configure({
+ codec: AUDIO_CODEC,
+ sampleRate: summary.audioSampleRate,
+ numberOfChannels: channels,
+ bitrate: AUDIO_BITRATE,
+ });
+ try {
+ for (let offset = 0; offset < total; offset += AUDIO_BLOCK) {
+ if (failure.reason) throw failure.reason;
+ const count = Math.min(AUDIO_BLOCK, total - offset);
+ // f32-planar: every channel's block laid end to end, de-interleaved from
+ // the way vidfab returns them.
+ const planar = new Float32Array(count * channels);
+ for (let channel = 0; channel < channels; channel += 1) {
+ for (let frame = 0; frame < count; frame += 1) {
+ planar[channel * count + frame] = samples[(offset + frame) * channels + channel];
+ }
+ }
+ const data = new AudioData({
+ format: "f32-planar",
+ sampleRate: summary.audioSampleRate,
+ numberOfFrames: count,
+ numberOfChannels: channels,
+ timestamp: Math.round((offset * 1_000_000) / summary.audioSampleRate),
+ data: planar,
+ });
+ encoder.encode(data);
+ data.close();
+ while (encoder.encodeQueueSize > 16) await tick();
+ }
+ await encoder.flush();
+ if (failure.reason) throw failure.reason;
+ } finally {
+ if (encoder.state !== "closed") encoder.close();
+ }
+}
+
+/**
+ * Encodes the render waiting for `jobId` and writes it into the project.
+ *
+ * Throws if there is nothing to encode, if this computer cannot encode, or if
+ * the write fails — every one of which is a sentence the Generator shows. The
+ * frames are handed back either way.
+ */
+export async function saveGeneratedScene(options: {
+ folderPath: string;
+ jobId: string;
+ /** Called as frames go into the encoder, for the progress bar. */
+ onProgress?: (encoded: number, total: number) => void;
+}): Promise<SavedGeneration> {
+ const { folderPath, jobId } = options;
+ if (!isTauri()) throw new Error("Saving a rendered scene needs the desktop app.");
+ if (typeof VideoEncoder === "undefined" || typeof VideoFrame === "undefined") {
+ throw new Error("This webview has no WebCodecs VideoEncoder, so a rendered scene cannot be turned into a video file here.");
+ }
+ const summary = await renderedSummary(jobId);
+ if (!summary) {
+ throw new Error("The rendered frames are no longer in memory, so there is nothing to save. Run the scene again.");
+ }
+ if (summary.frameCount <= 0 || summary.width <= 0 || summary.height <= 0) {
+ throw new Error("The render came back with no pictures in it.");
+ }
+
+ try {
+ const fps = summary.fps > 0 ? summary.fps : 24;
+ const bitrate = bitrateFor(summary.width, summary.height, fps, GENERATED_QUALITY);
+ const { codec } = await pickCodec(summary.width, summary.height, fps, bitrate);
+ const withAudio = await audioSupported(summary);
+
+ const { ArrayBufferTarget, Muxer } = await import("mp4-muxer");
+ const target = new ArrayBufferTarget();
+ const muxer = new Muxer({
+ target,
+ video: { codec: outputCodec("h264").muxer, width: summary.width, height: summary.height, frameRate: Math.round(fps) },
+ ...(withAudio
+ ? { audio: { codec: "aac" as const, numberOfChannels: summary.audioChannels, sampleRate: summary.audioSampleRate } }
+ : {}),
+ fastStart: "in-memory",
+ });
+
+ /* On an object because the encoder writes it from its own callback, where
+ TypeScript's flow analysis cannot follow the assignment. */
+ const failure: { reason: Error | null } = { reason: null };
+ const encoder = new VideoEncoder({
+ output: (chunk, meta) => muxer.addVideoChunk(chunk, meta),
+ error: (reason) => { failure.reason = reason instanceof Error ? reason : new Error(String(reason)); },
+ });
+ encoder.configure({ codec, width: summary.width, height: summary.height, bitrate, framerate: fps, avc: { format: "avc" } });
+
+ const makeFrame = frameFactory(summary.width, summary.height);
+ /* Computed from the index every time rather than accumulated, so a rate
+ that does not divide a microsecond evenly cannot drift the last frame
+ away from the clock. */
+ const timestampUs = (index: number) => Math.round((index * 1_000_000) / fps);
+ const keyframeEvery = Math.max(1, Math.round(fps * KEYFRAME_SECONDS));
+
+ try {
+ for (let index = 0; index < summary.frameCount; index += 1) {
+ if (failure.reason) throw failure.reason;
+ const pixels = await renderedFrame(jobId, index);
+ const frame = makeFrame(pixels, timestampUs(index), timestampUs(index + 1) - timestampUs(index));
+ encoder.encode(frame, { keyFrame: index % keyframeEvery === 0 });
+ frame.close();
+ options.onProgress?.(index + 1, summary.frameCount);
+ // Let the encoder drain, and let the window paint: this loop is the
+ // whole of a five-second render's encode and it must not freeze the UI.
+ while (encoder.encodeQueueSize > ENCODE_QUEUE_LIMIT) await tick();
+ if (index % 8 === 7) await tick();
+ }
+ await encoder.flush();
+ if (failure.reason) throw failure.reason;
+ } finally {
+ if (encoder.state !== "closed") encoder.close();
+ }
+
+ let note: string | null = null;
+ if (withAudio) {
+ await encodeAudio(summary, await renderedAudio(jobId), (chunk, meta) => muxer.addAudioChunk(chunk, meta));
+ } else if (summary.audioSamples > 0) {
+ // The render HAD sound and the file does not: say so rather than hand
+ // back a silent video that looks complete.
+ note = "Saved without sound: this computer's encoder would not take the render's audio.";
+ }
+
+ muxer.finalize();
+ const written = await writeGeneratedVideo(folderPath, jobId, new Uint8Array(target.buffer));
+ return { relativePath: written.relativePath, bytes: written.bytes, note };
+ } finally {
+ // Whatever happened, the render stops occupying memory here.
+ await releaseRendered(jobId);
+ }
+}
+
+/** The same failure, said the same way wherever it is caught. */
+export const describeSaveFailure = (reason: unknown) => describe(reason);
diff --git a/src/styles/generator.css b/src/styles/generator.css
index e3d98b5..8ff67d4 100644
--- a/src/styles/generator.css
+++ b/src/styles/generator.css
@@ -1522,12 +1522,6 @@
/* The states that cannot produce a file still get real controls, so the user
is never left with prose and no way forward. */
-.job-actions__choices {
- display: grid;
- gap: var(--space-3);
- margin-top: var(--space-4);
-}
-
.job-actions .primary-button:disabled {
cursor: not-allowed;
color: var(--text-muted);
@@ -1538,57 +1532,28 @@
}
.job-actions__note {
+ display: flex;
+ align-items: center;
+ gap: var(--space-2);
margin: var(--space-3) 0 0;
color: var(--text-muted);
font-size: var(--text-sm);
line-height: var(--leading-normal);
}
-/* Expectation-setting, not an alarm: sits directly under the generate button
- so the limit is known before an expensive render, never after it. */
-
-.job-actions__limit {
- display: flex;
- align-items: flex-start;
- gap: var(--space-2);
- margin: var(--space-3) 0 0;
- padding: var(--space-3) var(--space-4);
- border: 1px solid var(--line);
- border-radius: var(--radius-md);
+/* The path a scene was saved to, which is a file name and reads as one. */
+.job-actions__note code {
color: var(--text-secondary);
- background: var(--panel);
- font-size: var(--text-sm);
- line-height: var(--leading-normal);
+ font: var(--weight-medium) var(--text-xs) / 1.4 var(--font-mono);
+ overflow-wrap: anywhere;
}
-.job-actions__limit svg {
+/* Encoding is the one thing in this panel that is HAPPENING rather than
+ waiting to be started, so its icon turns. */
+.job-actions__note .spin {
flex: 0 0 auto;
- margin-top: 2px;
- color: var(--text-muted);
-}
-
-/* Shown when the honest answer is "there is no next step here". */
-
-.job-actions__blocked {
- padding: var(--space-4);
- border: 1px solid color-mix(in srgb, var(--warning) 32%, transparent);
- border-radius: var(--radius-lg);
- background: color-mix(in srgb, var(--warning) 8%, var(--panel-2));
-}
-
-.job-actions__blocked b {
- display: block;
- color: var(--warning);
- font-size: var(--text-base);
- font-weight: var(--weight-semibold);
- line-height: var(--leading-snug);
-}
-
-.job-actions__blocked p {
- margin: var(--space-2) 0 0;
- color: var(--text-secondary);
- font-size: var(--text-sm);
- line-height: var(--leading-normal);
+ color: var(--accent-bright);
+ animation: spin 1.4s linear infinite;
}
/* --- Empty state ----------------------------------------------------------- */