The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.
Rust ffmpegfree-video-editormodel-context-protocolnon-linear-editoroffline-firstopen-source-video-editorself-hostedvideo-editingvideo-editing-automationvideo-editing-softwarevideo-editing-toolsvideo-editorvoice-cloningyoutube-automationyoutube-shorts
feat(api): ids, error codes, exports as jobs, and frames inline
Jareerb862141afa98
diff --git a/src/Cargo.lock b/src/Cargo.lockindex 712d1ebe..7c1799c0 100644--- a/src/Cargo.lock+++ b/src/Cargo.lock@@ -1184,6 +1184,7 @@ dependencies = [name = "concat-api"version = "0.2.2"dependencies = [+ "base64 0.22.1","concat-effects","concat-export","concat-host",diff --git a/src/crates/concat-api/Cargo.toml b/src/crates/concat-api/Cargo.tomlindex 5a5b70b1..f2bd9499 100644--- a/src/crates/concat-api/Cargo.toml+++ b/src/crates/concat-api/Cargo.toml@@ -16,6 +16,8 @@ serde_json.workspace = true# The frame method hands back a PNG: the one picture format every# caller reads and that keeps the compositor's pixels exact.png = "0.17"+# A frame handed back inline crosses as text.+base64 = "0.22"[dev-dependencies]tempfile = "3"diff --git a/src/crates/concat-api/src/lib.rs b/src/crates/concat-api/src/lib.rsindex 86f1f2fc..ca88b382 100644--- a/src/crates/concat-api/src/lib.rs+++ b/src/crates/concat-api/src/lib.rs@@ -6,34 +6,41 @@//!//! The command line, a daemon on a socket, an MCP server, a plugin: each is//! a transport, and a transport is a loop that reads a [`Request`], hands-//! it to [`Api::dispatch`], and writes the [`Response`] and any [`Event`]s-//! back. Nothing about what a request *means* lives in a transport, so two-//! of them cannot disagree, and a method added here reaches all of them.+//! it to [`Api::dispatch`], and writes the [`Response`] back, forwarding+//! the [`Event`]s the API's jobs raise as they come. Nothing about what a+//! request *means* lives in a transport, so two of them cannot disagree,+//! and a method added here reaches all of them. What a line transport puts+//! around the three is the JSON-RPC 2.0 envelope in [`rpc`].//!//! The crate decides nothing about the edit either. Edits are//! `concat_project` [`Command`]s carried as they are; projects, media,//! templates, titles, cutouts and exports are `concat_host`'s. What this//! crate owns is the choreography the window performs by hand - probe then-//! add, paint titles and find masks before rendering, save through the+//! add, find masks and paint titles before rendering, save through the//! session - stated once so a file exported here is the file the window//! would have written.//!//! One [`Api`] holds one session per open project folder. It is not//! thread-safe by design: a transport that serves several callers owns the//! one `Api` and serialises through it, the way the window's event loop-//! does, and a long method blocks its caller. [`Api::exporter`] is the one-//! handle that crosses threads, so a cancel can reach a running export.+//! does. A method that would keep everyone waiting - an export - runs as a+//! job on its own thread instead: [`Api::dispatch`] returns its name at+//! once and the job reports through the [`EventSink`] the API was made+//! with, from that thread, which is why the sink must be `Send + Sync`.pub mod message;+pub mod rpc;use std::collections::BTreeMap;use std::path::{Path, PathBuf};use std::sync::Arc;+use std::thread::JoinHandle;+use base64::Engine as _;use concat_effects::Catalogue;use concat_effects::manifest::Kind;-use concat_export::ExportClip;-use concat_host::cutout::{self, Cutouts};+use concat_export::{ExportClip, ExportRequest};+use concat_host::cutout::{self, AnalyseRequest, Cutouts};use concat_host::export::{self, Exporter};use concat_host::preview::{FrameSpec, Monitor};use concat_host::session::EditorView;@@ -43,8 +50,8 @@ use concat_project::Command;use concat_project::model::VideoSettings;pub use message::{- API_VERSION, Dirs, Done, Event, ExportSpec, Fill, PackageInfo, ParamInfo, Reply, Request,- Response, VersionInfo, Written,+ API_VERSION, ApiError, Dirs, Done, ErrorCode, Event, ExportSpec, Fill, PackageInfo, ParamInfo,+ Picture, Reply, Request, Response, Started, VersionInfo, Written,};/// The export sheet's middle quality, and what an export gets when the@@ -53,32 +60,41 @@ const DEFAULT_CRF: u8 = 20;/// The x264 preset every export uses unless told otherwise.const DEFAULT_PRESET: &str = "medium";+/// Where a job's events go. Called from the job's thread, so a transport+/// that writes them to a caller locks its writer inside.+pub type EventSink = Arc<dyn Fn(Event) + Send + Sync>;+/// The dispatcher: the open sessions and the services behind them.pub struct Api {dirs: AppDirs,/// Open projects by canonical folder path.sessions: BTreeMap<String, Session>,titles: Titles,- cutouts: Cutouts,+ cutouts: Arc<Cutouts>,monitor: Monitor,exporter: Exporter,+ events: EventSink,+ jobs: Jobs,}impl Api {- /// An API over this machine's app directories.- pub fn new() -> Result<Api, String> {- Ok(Api::with_dirs(AppDirs::locate()?))+ /// An API over this machine's app directories, reporting its jobs+ /// through `events`.+ pub fn new(events: EventSink) -> Result<Api, String> {+ Ok(Api::with_dirs(AppDirs::locate()?, events))}/// An API over the given directories: a test's scratch, or an embedder/// with a home of its own.- pub fn with_dirs(dirs: AppDirs) -> Api {+ pub fn with_dirs(dirs: AppDirs, events: EventSink) -> Api {Api {titles: Titles::new(&dirs),- cutouts: Cutouts::new(&dirs.data),+ cutouts: Arc::new(Cutouts::new(&dirs.data)),monitor: Monitor::new(),exporter: Exporter::new(),sessions: BTreeMap::new(),+ events,+ jobs: Jobs::default(),dirs,}}@@ -88,19 +104,31 @@ impl Api {&self.dirs}- /// The export slot, for a transport that needs to cancel from another- /// thread while [`Api::dispatch`] blocks on [`Request::ExportRun`].+ /// The export slot, for an embedder that shares it with a window.pub fn exporter(&self) -> Exporter {self.exporter.clone()}- /// Runs one request. Events fire through `notify` as the work goes;- /// the response is what the request is worth.- pub fn dispatch(&mut self, request: Request, notify: &mut dyn FnMut(Event)) -> Response {- self.run(request, notify).into()+ /// How many jobs are still running.+ pub fn running(&mut self) -> usize {+ self.jobs.reap();+ self.jobs.threads.len()+ }++ /// Waits for every running job to end. A transport calls this before+ /// it exits, so an export begun on its last line still finishes.+ pub fn finish(&mut self) {+ self.jobs.finish();}- fn run(&mut self, request: Request, notify: &mut dyn FnMut(Event)) -> Result<Reply, String> {+ /// Runs one request. The response is what the request is worth; a job+ /// it begins reports through the sink from then on.+ pub fn dispatch(&mut self, request: Request) -> Response {+ self.jobs.reap();+ self.run(request).into()+ }++ fn run(&mut self, request: Request) -> Result<Reply, ApiError> {let view = |view: EditorView| Ok(Reply::View(Box::new(view)));match request {Request::Version => Ok(Reply::Version(self.version())),@@ -124,12 +152,14 @@ impl Api {Ok(Reply::Done(Done {}))}Request::ProjectSetVideo { path, video } => {- view(self.session_mut(&path)?.set_video(video)?)+ view(self.session_mut(&path)?.set_video(video).map_err(refused)?)}Request::EditApply { path, command } => view(self.apply(&path, *command)?),Request::EditUndo { path } => view(self.session_mut(&path)?.undo()),Request::EditRedo { path } => view(self.session_mut(&path)?.redo()),- Request::MediaProbe { path } => Ok(Reply::Media(media::probe(&path)?)),+ Request::MediaProbe { path } => {+ Ok(Reply::Media(media::probe(&path).map_err(ApiError::failed)?))+ }Request::MediaImport { path, file } => view(self.import(&path, &file)?),Request::CatalogueList { kind } => Ok(Reply::Packages(catalogue(kind.as_deref())?)),Request::TemplateList => Ok(Reply::Templates(templates::list(&self.dirs.config))),@@ -142,11 +172,9 @@ impl Api {Request::TemplateSave { path, name } => {Ok(Reply::Template(self.save_template(&path, &name)?))}- Request::ExportRun { path, spec } => {- Ok(Reply::Written(self.export(&path, &spec, notify)?))- }- Request::ExportCancel => {- self.exporter.cancel();+ Request::ExportRun { path, spec } => Ok(Reply::Started(self.export(&path, &spec)?)),+ Request::ExportCancel { job } => {+ self.cancel(&job)?;Ok(Reply::Done(Done {}))}Request::PreviewFrame {@@ -155,12 +183,13 @@ impl Api {output,width,height,- } => Ok(Reply::Written(self.frame(- &path,- time,- &output,- width.zip(height),- )?)),+ } => {+ let size = width.zip(height);+ match output {+ Some(output) => Ok(Reply::Written(self.frame(&path, time, &output, size)?)),+ None => Ok(Reply::Picture(self.picture(&path, time, size)?)),+ }+ }}}@@ -180,7 +209,7 @@ impl Api {location: &str,name: &str,video: VideoSettings,- ) -> Result<EditorView, String> {+ ) -> Result<EditorView, ApiError> {let info = projects::create(location,name,@@ -188,24 +217,25 @@ impl Api {video.height,video.rate_num,video.rate_den,- )?;+ )+ .map_err(ApiError::failed)?;self.adopt(info)}/// [`Request::ProjectOpen`].- pub fn open(&mut self, path: &str) -> Result<EditorView, String> {+ pub fn open(&mut self, path: &str) -> Result<EditorView, ApiError> {let key = key_of(path);if let Some(session) = self.sessions.get(&key) {return Ok(session.view());}- let info = projects::open(path)?;+ let info = projects::open(path).map_err(ApiError::failed)?;self.adopt(info)}/// Opens a session on a project the host just described and puts it at/// the front of the recents list.- fn adopt(&mut self, info: ProjectInfo) -> Result<EditorView, String> {- let session = Session::open_info(&info)?;+ fn adopt(&mut self, info: ProjectInfo) -> Result<EditorView, ApiError> {+ let session = Session::open_info(&info).map_err(ApiError::failed)?;// Recents are a convenience for the launch screen; a machine whose// config folder cannot be written still edits.let _ = projects::remember(&self.dirs.config, &info);@@ -215,7 +245,7 @@ impl Api {}/// [`Request::ProjectClose`].- pub fn close(&mut self, path: &str, save: bool) -> Result<(), String> {+ pub fn close(&mut self, path: &str, save: bool) -> Result<(), ApiError> {if save {self.save(path, None)?;}@@ -231,18 +261,18 @@ impl Api {}/// [`Request::ProjectSave`].- pub fn save(&mut self, path: &str, name: Option<&str>) -> Result<(), String> {- self.session_mut(path)?.save(name)+ pub fn save(&mut self, path: &str, name: Option<&str>) -> Result<(), ApiError> {+ self.session_mut(path)?.save(name).map_err(ApiError::failed)}/// [`Request::EditApply`].- pub fn apply(&mut self, path: &str, command: Command) -> Result<EditorView, String> {- self.session_mut(path)?.apply(command)+ pub fn apply(&mut self, path: &str, command: Command) -> Result<EditorView, ApiError> {+ self.session_mut(path)?.apply(command).map_err(refused)}/// [`Request::MediaImport`]: the probe and the add, as one.- pub fn import(&mut self, path: &str, file: &str) -> Result<EditorView, String> {- let item = media::probe(file)?.to_new_media();+ pub fn import(&mut self, path: &str, file: &str) -> Result<EditorView, ApiError> {+ let item = media::probe(file).map_err(ApiError::failed)?.to_new_media();self.apply(path, Command::AddMedia { item })}@@ -253,7 +283,7 @@ impl Api {location: &str,name: &str,fills: Vec<Fill>,- ) -> Result<EditorView, String> {+ ) -> Result<EditorView, ApiError> {// Every file is probed before anything is made, so a bad path// refuses the whole request rather than leaving a folder behind.let fills = fills@@ -261,11 +291,14 @@ impl Api {.map(|fill| {Ok(SlotFill {media_id: fill.media_id,- item: media::probe(&fill.file)?.to_new_media(),+ item: media::probe(&fill.file)+ .map_err(ApiError::failed)?+ .to_new_media(),})})- .collect::<Result<Vec<SlotFill>, String>>()?;- let info = templates::instantiate(template, location, name, fills)?;+ .collect::<Result<Vec<SlotFill>, ApiError>>()?;+ let info =+ templates::instantiate(template, location, name, fills).map_err(ApiError::failed)?;self.adopt(info)}@@ -274,7 +307,7 @@ impl Api {&mut self,path: &str,name: &str,- ) -> Result<concat_host::templates::TemplateInfo, String> {+ ) -> Result<concat_host::templates::TemplateInfo, ApiError> {let session = self.session(path)?;templates::save(&self.dirs.config,@@ -283,36 +316,30 @@ impl Api {session.path(),name,)+ .map_err(ApiError::failed)}/// [`Request::ExportRun`]: what the window's Export sheet does, in its- /// order. Masks first, because the frame loop reads whatever is in the- /// project's cache and draws the picture as shot where there is none;- /// then titles, which rejoin the clip list as stills; then the render.- pub fn export(- &mut self,- path: &str,- spec: &ExportSpec,- notify: &mut dyn FnMut(Event),- ) -> Result<Written, String> {+ /// order, on a thread of its own. Masks first, because the frame loop+ /// reads whatever is in the project's cache and draws the picture as+ /// shot where there is none; then the render, with the titles already+ /// painted here and rejoining the clip list as stills.+ pub fn export(&mut self, path: &str, spec: &ExportSpec) -> Result<Started, ApiError> {let session = self.session(path)?;if session.project().active().clips.is_empty() {- return Err("There is nothing on the timeline to export".to_owned());+ return Err(ApiError::new(+ ErrorCode::Refused,+ "There is nothing on the timeline to export",+ ));}let settings = session.settings();let width = spec.width.unwrap_or(settings.width);let height = spec.height.unwrap_or(settings.height);-- let project_dir = PathBuf::from(session.path());- let project = session.project().clone();- self.find_masks(&project, &project_dir, notify)?;-- let session = self.session(path)?;- let titles = self.title_clips(session, width, height);let codec = match spec.codec.as_deref() {None => export::VideoCodec::H264,- Some(name) => export::VideoCodec::parse(name)- .ok_or_else(|| format!("unknown codec {name:?}: h264, hevc or av1"))?,+ Some(name) => export::VideoCodec::parse(name).ok_or_else(|| {+ ApiError::invalid(format!("unknown codec {name:?}: h264, hevc or av1"))+ })?,};let host_spec = export::ExportSpec {output: spec.output.clone(),@@ -324,49 +351,59 @@ impl Api {codec,ten_bit: spec.ten_bit.unwrap_or(false),};++ let project_path = session.path().to_owned();+ let project_dir = PathBuf::from(&project_path);+ let masks: Vec<(String, AnalyseRequest)> =+ Cutouts::requests(session.project(), &project_dir)+ .into_iter()+ .filter(|(_, request)| Cutouts::outstanding(request) != 0)+ .collect();+ let titles = self.title_clips(session, width, height);let mut request = export::request(session, &host_spec, titles);request.width = width;request.height = height;request.rate_num = spec.rate_num.unwrap_or(settings.rate_num);request.rate_den = spec.rate_den.unwrap_or(settings.rate_den);- let job = self.exporter.begin()?;- let written = export::run(&request, job.cancel_flag(), |progress| {- notify(Event::from(progress));- })?;- Ok(Written {- path: written,- width,- height,- })+ let slot = self+ .exporter+ .begin()+ .map_err(|message| ApiError::new(ErrorCode::Busy, message))?;+ let started = Started {+ job: self.jobs.mint(),+ path: project_path,+ output: spec.output.clone(),+ };+ let job = ExportJob {+ name: started.job.clone(),+ path: started.path.clone(),+ request,+ masks,+ cutouts: Arc::clone(&self.cutouts),+ events: Arc::clone(&self.events),+ };+ let thread = std::thread::Builder::new()+ .name(format!("export {}", started.job))+ .spawn(move || job.run(slot))+ .map_err(|error| ApiError::failed(format!("could not start the export: {error}")))?;+ self.jobs.threads.push((started.job.clone(), thread));+ Ok(started)}- /// Runs every cutout analysis the timeline still needs, one after the- /// other, so the export that follows cuts every clip it should.- fn find_masks(- &self,- project: &concat_project::Project,- project_dir: &Path,- notify: &mut dyn FnMut(Event),- ) -> Result<(), String> {- for (media_id, request) in Cutouts::requests(project, project_dir) {- if Cutouts::outstanding(&request) == 0 {- continue;- }- self.cutouts.analyse(&request, &mut |progress| {- let (fetching, fraction) = match progress {- cutout::Progress::Fetching { received, total } => {- (true, received as f32 / total.max(1) as f32)- }- cutout::Progress::Analysing(fraction) => (false, fraction),- };- notify(Event::CutoutProgress {- media_id: media_id.clone(),- fetching,- fraction,- });- })?;+ /// [`Request::ExportCancel`].+ pub fn cancel(&mut self, job: &str) -> Result<(), ApiError> {+ self.jobs.reap();+ if !self.jobs.threads.iter().any(|(name, _)| name == job) {+ return Err(ApiError::new(+ ErrorCode::NotFound,+ format!("no job {job} is running"),+ ));}+ // Whichever phase it is in: the analysis ahead of the render, or+ // the render itself.+ self.cutouts.cancel();+ self.exporter.cancel();Ok(())}@@ -380,56 +417,182 @@ impl Api {.collect()}- /// [`Request::PreviewFrame`]: the paused monitor's true frame, to a- /// file.+ /// [`Request::PreviewFrame`] with an output: the paused monitor's true+ /// frame, to a file.pub fn frame(&mut self,path: &str,time: f64,output: &str,size: Option<(u32, u32)>,- ) -> Result<Written, String> {+ ) -> Result<Written, ApiError> {+ let (width, height, pixels) = self.pixels(path, time, size)?;+ write_png(Path::new(output), width, height, &pixels)?;+ Ok(Written {+ path: output.to_owned(),+ width,+ height,+ })+ }++ /// [`Request::PreviewFrame`] without one: the same frame, inline.+ pub fn picture(+ &mut self,+ path: &str,+ time: f64,+ size: Option<(u32, u32)>,+ ) -> Result<Picture, ApiError> {+ let (width, height, pixels) = self.pixels(path, time, size)?;+ let mut png = Vec::new();+ encode_png(&mut png, width, height, &pixels)+ .map_err(|error| ApiError::failed(format!("could not encode the frame: {error}")))?;+ Ok(Picture {+ width,+ height,+ png: base64::engine::general_purpose::STANDARD.encode(png),+ })+ }++ /// The composited RGBA frame at `time`.+ fn pixels(+ &mut self,+ path: &str,+ time: f64,+ size: Option<(u32, u32)>,+ ) -> Result<(u32, u32, Vec<u8>), ApiError> {let session = self.session(path)?;let settings = session.settings();let (width, height) = size.unwrap_or((settings.width, settings.height));if width == 0 || height == 0 {- return Err("A frame needs a width and a height".to_owned());+ return Err(ApiError::invalid("A frame needs a width and a height"));}let mut clips = session.flattened_clips();clips.extend(self.title_clips(session, width, height));- let pixels = self.monitor.frame(- Arc::new(clips),- &settings,- FrameSpec {- time,- width,- height,- },- )?;- write_png(Path::new(output), width, height, &pixels)?;- Ok(Written {- path: output.to_owned(),- width,- height,- })+ let pixels = self+ .monitor+ .frame(+ Arc::new(clips),+ &settings,+ FrameSpec {+ time,+ width,+ height,+ },+ )+ .map_err(ApiError::failed)?;+ Ok((width, height, pixels))}- fn session(&self, path: &str) -> Result<&Session, String> {+ fn session(&self, path: &str) -> Result<&Session, ApiError> {self.sessions.get(&key_of(path)).ok_or_else(|| not_open(path))}- fn session_mut(&mut self, path: &str) -> Result<&mut Session, String> {+ fn session_mut(&mut self, path: &str) -> Result<&mut Session, ApiError> {self.sessions.get_mut(&key_of(path)).ok_or_else(|| not_open(path))}}+/// The jobs the API has begun, by name, with the thread each runs on.+#[derive(Default)]+struct Jobs {+ minted: u64,+ threads: Vec<(String, JoinHandle<()>)>,+}++impl Jobs {+ /// The next name.+ fn mint(&mut self) -> String {+ self.minted += 1;+ format!("j{}", self.minted)+ }++ /// Forgets the threads that have ended.+ fn reap(&mut self) {+ self.threads.retain(|(_, thread)| !thread.is_finished());+ }++ /// Waits for the rest.+ fn finish(&mut self) {+ for (_, thread) in self.threads.drain(..) {+ let _ = thread.join();+ }+ }+}++/// An export in flight: everything its thread needs, owned.+struct ExportJob {+ name: String,+ path: String,+ request: ExportRequest,+ masks: Vec<(String, AnalyseRequest)>,+ cutouts: Arc<Cutouts>,+ events: EventSink,+}++impl ExportJob {+ /// The whole job, start to end, on the thread it is called from. The+ /// slot is held until this returns, so the next export waits its turn.+ fn run(self, slot: concat_host::jobs::Job) {+ let outcome = self.masks(&slot).and_then(|()| {+ export::run(&self.request, slot.cancel_flag(), |progress| {+ (self.events)(Event::progress(&self.name, &self.path, progress));+ })+ });+ let event = match outcome {+ Ok(output) => Event::ExportDone {+ job: self.name.clone(),+ path: self.path.clone(),+ output,+ width: self.request.width,+ height: self.request.height,+ },+ Err(message) => Event::ExportFailed {+ job: self.name.clone(),+ path: self.path.clone(),+ error: if slot.cancelled() {+ ApiError::new(ErrorCode::Cancelled, "The export was cancelled")+ } else {+ ApiError::failed(message)+ },+ },+ };+ (self.events)(event);+ }++ /// Runs every cutout analysis the timeline still needs, one after the+ /// other, so the render that follows cuts every clip it should.+ fn masks(&self, slot: &concat_host::jobs::Job) -> Result<(), String> {+ for (media_id, request) in &self.masks {+ if slot.cancelled() {+ return Err("cancelled".to_owned());+ }+ self.cutouts.analyse(request, &mut |progress| {+ let (fetching, fraction) = match progress {+ cutout::Progress::Fetching { received, total } => {+ (true, received as f32 / total.max(1) as f32)+ }+ cutout::Progress::Analysing(fraction) => (false, fraction),+ };+ (self.events)(Event::CutoutProgress {+ job: self.name.clone(),+ path: self.path.clone(),+ media_id: media_id.clone(),+ fetching,+ fraction,+ });+ })?;+ }+ Ok(())+ }+}+/// [`Request::CatalogueList`]: the built-in packages plus whatever/// [`Catalogue::install`] added, in id order.-fn catalogue(kind: Option<&str>) -> Result<Vec<PackageInfo>, String> {+fn catalogue(kind: Option<&str>) -> Result<Vec<PackageInfo>, ApiError> {let kind = match kind {None => None,Some("effect") => Some(Kind::Effect),@@ -438,9 +601,9 @@ fn catalogue(kind: Option<&str>) -> Result<Vec<PackageInfo>, String> {Some("transition") => Some(Kind::Transition),Some("generator") => Some(Kind::Generator),Some(other) => {- return Err(format!(+ return Err(ApiError::invalid(format!("{other:?} is not a kind: effect, filter, audio, transition or generator"- ));+ )));}};let mut packages: Vec<PackageInfo> = Catalogue::builtin()@@ -489,32 +652,48 @@ fn key_of(path: &str) -> String {.unwrap_or_else(|_| path.to_owned())}-fn not_open(path: &str) -> String {- format!("{path} is not open - open it first")+fn not_open(path: &str) -> ApiError {+ ApiError::new(+ ErrorCode::NotOpen,+ format!("{path} is not open - open it first"),+ )+}++/// The edit layer's no, as the code that says so.+fn refused(message: String) -> ApiError {+ ApiError::new(ErrorCode::Refused, message)}/// Writes RGBA pixels as a PNG, creating the folder above the file.-fn write_png(output: &Path, width: u32, height: u32, pixels: &[u8]) -> Result<(), String> {+fn write_png(output: &Path, width: u32, height: u32, pixels: &[u8]) -> Result<(), ApiError> {+ let could_not = |error: &dyn std::fmt::Display| {+ ApiError::failed(format!("could not write {}: {error}", output.display()))+ };if let Some(parent) = output.parent()&& !parent.as_os_str().is_empty(){- std::fs::create_dir_all(parent)- .map_err(|error| format!("could not create {}: {error}", parent.display()))?;+ std::fs::create_dir_all(parent).map_err(|error| {+ ApiError::failed(format!("could not create {}: {error}", parent.display()))+ })?;}- let file = std::fs::File::create(output)- .map_err(|error| format!("could not write {}: {error}", output.display()))?;- let mut encoder = png::Encoder::new(std::io::BufWriter::new(file), width, height);+ let file = std::fs::File::create(output).map_err(|error| could_not(&error))?;+ encode_png(std::io::BufWriter::new(file), width, height, pixels)+ .map_err(|error| could_not(&error))+}++/// Encodes RGBA pixels as a PNG into `sink`.+fn encode_png(+ sink: impl std::io::Write,+ width: u32,+ height: u32,+ pixels: &[u8],+) -> Result<(), png::EncodingError> {+ let mut encoder = png::Encoder::new(sink, width, height);encoder.set_color(png::ColorType::Rgba);encoder.set_depth(png::BitDepth::Eight);- let mut writer = encoder- .write_header()- .map_err(|error| format!("could not write {}: {error}", output.display()))?;- writer- .write_image_data(pixels)- .map_err(|error| format!("could not write {}: {error}", output.display()))?;- writer- .finish()- .map_err(|error| format!("could not write {}: {error}", output.display()))+ let mut writer = encoder.write_header()?;+ writer.write_image_data(pixels)?;+ writer.finish()}#[cfg(test)]@@ -523,16 +702,24 @@ mod tests {use concat_project::commands::NewMedia;use concat_project::model::MediaKind;use serde_json::json;+ use std::sync::Mutex;/// An API whose config and data live in a scratch folder that goes- /// away with the test.- fn api() -> (Api, tempfile::TempDir) {+ /// away with the test, and whose events pile up where a test can read+ /// them.+ fn api() -> (Api, tempfile::TempDir, Arc<Mutex<Vec<Event>>>) {let scratch = tempfile::tempdir().expect("scratch");let dirs = AppDirs {config: scratch.path().join("config"),data: scratch.path().join("data"),};- (Api::with_dirs(dirs), scratch)+ let events = Arc::new(Mutex::new(Vec::new()));+ let sink = Arc::clone(&events);+ let api = Api::with_dirs(+ dirs,+ Arc::new(move |event| sink.lock().expect("events").push(event)),+ );+ (api, scratch, events)}fn ok(response: Response) -> Reply {@@ -542,7 +729,7 @@ mod tests {}}- fn err(response: Response) -> String {+ fn err(response: Response) -> ApiError {match response {Response::Result(_) => panic!("worked, unexpectedly"),Response::Error(error) => error,@@ -556,10 +743,6 @@ mod tests {}}- fn quiet() -> impl FnMut(Event) {- |_| {}- }-fn still(path: &str) -> NewMedia {NewMedia {path: path.to_owned(),@@ -577,6 +760,17 @@ mod tests {}}+ /// A project named `name` under the scratch folder, open.+ fn project(api: &mut Api, scratch: &tempfile::TempDir, name: &str) -> String {+ let location = scratch.path().to_string_lossy().into_owned();+ ok(api.dispatch(Request::ProjectCreate {+ location: location.clone(),+ name: name.to_owned(),+ video: None,+ }));+ format!("{location}/{name}")+ }+#[test]fn a_request_parses_by_method_and_carries_a_command_verbatim() {let request: Request = serde_json::from_value(json!({@@ -604,79 +798,70 @@ mod tests {fn a_response_is_a_result_or_an_error_object() {let worked = serde_json::to_value(Response::Result(Reply::Done(Done {}))).expect("json");assert_eq!(worked, json!({ "result": {} }));- let refused = serde_json::to_value(Response::Error("no".to_owned())).expect("json");- assert_eq!(refused, json!({ "error": "no" }));+ let refused =+ serde_json::to_value(Response::Error(ApiError::new(ErrorCode::Refused, "no")))+ .expect("json");+ assert_eq!(+ refused,+ json!({ "error": { "code": "refused", "message": "no" } })+ );}#[test]fn create_edit_save_and_reopen_round_trip() {- let (mut api, scratch) = api();+ let (mut api, scratch, _) = api();let location = scratch.path().join("projects");std::fs::create_dir_all(&location).expect("location");let location = location.to_string_lossy().into_owned();- let created = view(ok(api.dispatch(- Request::ProjectCreate {- location: location.clone(),- name: "Round trip".to_owned(),- video: Some(VideoSettings {- width: 1080,- height: 1920,- rate_num: 60,- rate_den: 1,- }),- },- &mut quiet(),- )));+ let created = view(ok(api.dispatch(Request::ProjectCreate {+ location: location.clone(),+ name: "Round trip".to_owned(),+ video: Some(VideoSettings {+ width: 1080,+ height: 1920,+ rate_num: 60,+ rate_den: 1,+ }),+ })));assert_eq!(created.settings.width, 1080);assert_eq!(created.settings.height, 1920);assert_eq!(created.settings.rate_num, 60);let path = format!("{location}/Round trip");assert!(projects::is_project(Path::new(&path)));- let added = view(ok(api.dispatch(- Request::EditApply {- path: path.clone(),- command: Box::new(Command::AddMedia {- item: still("/nowhere/still.png"),- }),- },- &mut quiet(),- )));+ let added = view(ok(api.dispatch(Request::EditApply {+ path: path.clone(),+ command: Box::new(Command::AddMedia {+ item: still("/nowhere/still.png"),+ }),+ })));let media_id = added.created_id.expect("minted");- let placed = view(ok(api.dispatch(- Request::EditApply {- path: path.clone(),- command: Box::new(Command::AddClipAtFirstFree {- media_id,- start: 2.0,- }),- },- &mut quiet(),- )));+ let placed = view(ok(api.dispatch(Request::EditApply {+ path: path.clone(),+ command: Box::new(Command::AddClipAtFirstFree {+ media_id,+ start: 2.0,+ }),+ })));assert!(placed.can_undo);assert_eq!(placed.project.active().clips.len(), 1);- ok(api.dispatch(- Request::ProjectClose {- path: path.clone(),- save: true,- },- &mut quiet(),- ));+ ok(api.dispatch(Request::ProjectClose {+ path: path.clone(),+ save: true,+ }));assert_eq!(- err(api.dispatch(Request::ProjectGet { path: path.clone() }, &mut quiet())),+ err(api.dispatch(Request::ProjectGet { path: path.clone() })),not_open(&path));- let reopened = view(ok(- api.dispatch(Request::ProjectOpen { path: path.clone() }, &mut quiet())- ));+ let reopened = view(ok(api.dispatch(Request::ProjectOpen { path: path.clone() })));assert_eq!(reopened.project.active().clips.len(), 1);assert_eq!(reopened.project.active().clips[0].start, 2.0);assert!(!reopened.can_undo, "history does not survive a save");- let recents = match ok(api.dispatch(Request::ProjectList, &mut quiet())) {+ let recents = match ok(api.dispatch(Request::ProjectList)) {Reply::Projects(list) => list,_ => panic!("not a list"),};@@ -685,43 +870,36 @@ mod tests {}#[test]- fn a_refusal_is_the_command_layers_sentence() {- let (mut api, scratch) = api();- let location = scratch.path().to_string_lossy().into_owned();- let created = view(ok(api.dispatch(- Request::ProjectCreate {- location: location.clone(),- name: "Refused".to_owned(),- video: None,- },- &mut quiet(),- )));+ fn a_refusal_is_the_command_layers_sentence_with_its_code() {+ let (mut api, scratch, _) = api();+ let path = project(&mut api, &scratch, "Refused");+ let created = view(ok(api.dispatch(Request::ProjectGet { path: path.clone() })));let track_id = created.project.active().tracks[0].id.clone();- let refused = err(api.dispatch(- Request::EditApply {- path: format!("{location}/Refused"),- command: Box::new(Command::AddClip {- media_id: "m999".to_owned(),- track_id,- start: 0.0,- }),- },- &mut quiet(),- ));- assert_eq!(refused, "That media is no longer in the bin.");+ let refused = err(api.dispatch(Request::EditApply {+ path,+ command: Box::new(Command::AddClip {+ media_id: "m999".to_owned(),+ track_id,+ start: 0.0,+ }),+ }));+ assert_eq!(refused.code, ErrorCode::Refused);+ assert_eq!(refused.message, "That media is no longer in the bin.");}#[test]fn creating_over_a_project_is_refused() {- let (mut api, scratch) = api();+ let (mut api, scratch, _) = api();let location = scratch.path().to_string_lossy().into_owned();let create = || Request::ProjectCreate {location: location.clone(),name: "Twice".to_owned(),video: None,};- ok(api.dispatch(create(), &mut quiet()));- assert!(err(api.dispatch(create(), &mut quiet())).contains("already exists"));+ ok(api.dispatch(create()));+ let again = err(api.dispatch(create()));+ assert_eq!(again.code, ErrorCode::Failed);+ assert!(again.message.contains("already exists"));}#[test]@@ -730,7 +908,10 @@ mod tests {assert!(!packages.is_empty());assert!(packages.iter().all(|package| package.kind == "filter"));assert!(packages.windows(2).all(|pair| pair[0].id < pair[1].id));- assert!(catalogue(Some("look")).is_err());+ assert_eq!(+ catalogue(Some("look")).expect_err("not a kind").code,+ ErrorCode::Invalid+ );let all = catalogue(None).expect("all");assert!(all.len() > packages.len());assert!(all.iter().any(|package| !package.params.is_empty()));@@ -738,80 +919,152 @@ mod tests {#[test]fn a_method_on_a_closed_project_says_so() {- let (mut api, _scratch) = api();- assert_eq!(- err(api.dispatch(- Request::EditUndo {- path: "/never".to_owned()- },- &mut quiet()- )),- not_open("/never")- );+ let (mut api, _scratch, _) = api();+ let refused = err(api.dispatch(Request::EditUndo {+ path: "/never".to_owned(),+ }));+ assert_eq!(refused, not_open("/never"));+ assert_eq!(refused.code, ErrorCode::NotOpen);}#[test]fn undo_and_redo_step_the_history() {- let (mut api, scratch) = api();- let location = scratch.path().to_string_lossy().into_owned();- ok(api.dispatch(- Request::ProjectCreate {- location: location.clone(),- name: "History".to_owned(),- video: None,- },- &mut quiet(),- ));- let path = format!("{location}/History");- ok(api.dispatch(- Request::EditApply {- path: path.clone(),- command: Box::new(Command::AddTextClip {- track_id: None,- start: 0.0,- style: None,- duration: Some(3.0),- offset_y: None,- }),- },- &mut quiet(),- ));- let undone = view(ok(- api.dispatch(Request::EditUndo { path: path.clone() }, &mut quiet())- ));+ let (mut api, scratch, _) = api();+ let path = project(&mut api, &scratch, "History");+ ok(api.dispatch(Request::EditApply {+ path: path.clone(),+ command: Box::new(Command::AddTextClip {+ track_id: None,+ start: 0.0,+ style: None,+ duration: Some(3.0),+ offset_y: None,+ }),+ }));+ let undone = view(ok(api.dispatch(Request::EditUndo { path: path.clone() })));assert!(undone.project.active().clips.is_empty());assert!(undone.can_redo);- let redone = view(ok(api.dispatch(Request::EditRedo { path }, &mut quiet())));+ let redone = view(ok(api.dispatch(Request::EditRedo { path })));assert_eq!(redone.project.active().clips.len(), 1);}#[test]fn the_document_is_what_a_save_writes() {- let (mut api, scratch) = api();- let location = scratch.path().to_string_lossy().into_owned();- ok(api.dispatch(- Request::ProjectCreate {- location: location.clone(),- name: "Doc".to_owned(),- video: None,- },- &mut quiet(),- ));- let path = format!("{location}/Doc");- let document = match ok(api.dispatch(- Request::ProjectDocument { path: path.clone() },- &mut quiet(),- )) {+ let (mut api, scratch, _) = api();+ let path = project(&mut api, &scratch, "Doc");+ let document = match ok(api.dispatch(Request::ProjectDocument { path: path.clone() })) {Reply::Document(document) => document,_ => panic!("not a document"),};- ok(api.dispatch(- Request::ProjectSave {- path: path.clone(),- name: None,- },- &mut quiet(),- ));+ ok(api.dispatch(Request::ProjectSave {+ path: path.clone(),+ name: None,+ }));assert_eq!(projects::read_document(&path).expect("saved"), document);}++ #[test]+ fn an_empty_timeline_has_nothing_to_export_and_no_job_to_cancel() {+ let (mut api, scratch, _) = api();+ let path = project(&mut api, &scratch, "Empty");+ let refused = err(api.dispatch(Request::ExportRun {+ path,+ spec: ExportSpec {+ output: scratch+ .path()+ .join("out.mp4")+ .to_string_lossy()+ .into_owned(),+ ..ExportSpec::default()+ },+ }));+ assert_eq!(refused.code, ErrorCode::Refused);+ let missing = err(api.dispatch(Request::ExportCancel {+ job: "j1".to_owned(),+ }));+ assert_eq!(missing.code, ErrorCode::NotFound);+ assert_eq!(api.running(), 0);+ }++ #[test]+ fn an_export_is_a_job_that_reports_how_it_ended() {+ let (mut api, scratch, events) = api();+ let path = project(&mut api, &scratch, "Job");+ // A still that does not exist: the job starts, since the timeline+ // has a clip, and fails in the render, which is an event.+ let added = view(ok(api.dispatch(Request::EditApply {+ path: path.clone(),+ command: Box::new(Command::AddMedia {+ item: still("/nowhere/still.png"),+ }),+ })));+ ok(api.dispatch(Request::EditApply {+ path: path.clone(),+ command: Box::new(Command::AddClipAtFirstFree {+ media_id: added.created_id.expect("minted"),+ start: 0.0,+ }),+ }));+ let started = match ok(api.dispatch(Request::ExportRun {+ path: path.clone(),+ spec: ExportSpec {+ output: scratch+ .path()+ .join("out.mp4")+ .to_string_lossy()+ .into_owned(),+ ..ExportSpec::default()+ },+ })) {+ Reply::Started(started) => started,+ _ => panic!("not a job"),+ };+ assert_eq!(started.job, "j1");+ api.finish();+ let events = events.lock().expect("events");+ let last = events.last().expect("the job said how it ended");+ assert_eq!(last.job(), "j1");+ match last {+ Event::ExportFailed {+ path: at, error, ..+ } => {+ assert_eq!(at, &path);+ assert_eq!(error.code, ErrorCode::Failed);+ }+ other => panic!("ended with {other:?}"),+ }+ assert_eq!(api.running(), 0);+ }++ #[test]+ fn a_frame_comes_back_inline_when_no_output_is_named() {+ let (mut api, scratch, _) = api();+ let path = project(&mut api, &scratch, "Frame");+ let picture = match ok(api.dispatch(Request::PreviewFrame {+ path: path.clone(),+ time: 0.0,+ output: None,+ width: Some(16),+ height: Some(9),+ })) {+ Reply::Picture(picture) => picture,+ _ => panic!("not a picture"),+ };+ assert_eq!((picture.width, picture.height), (16, 9));+ let png = base64::engine::general_purpose::STANDARD+ .decode(picture.png)+ .expect("base64");+ let decoder = png::Decoder::new(std::io::Cursor::new(png));+ let reader = decoder.read_info().expect("a PNG");+ assert_eq!((reader.info().width, reader.info().height), (16, 9));++ let refused = err(api.dispatch(Request::PreviewFrame {+ path,+ time: 0.0,+ output: None,+ width: Some(0),+ height: Some(9),+ }));+ assert_eq!(refused.code, ErrorCode::Invalid);+ }}diff --git a/src/crates/concat-api/src/message.rs b/src/crates/concat-api/src/message.rsindex 323ef8df..daf20a4e 100644--- a/src/crates/concat-api/src/message.rs+++ b/src/crates/concat-api/src/message.rs@@ -8,8 +8,17 @@//! contract: a transport is free to carry it over stdin, a socket or a//! function call, but never to reinterpret it. Requests are tagged by//! `method`, events by `event`, and a response is `{"result": ...}` or-//! `{"error": "..."}`. Fields are camelCase, matching the document and the-//! command layer, so a caller learns one spelling.+//! `{"error": {"code": ..., "message": ...}}`. Fields are camelCase,+//! matching the document and the command layer, so a caller learns one+//! spelling. On a line or a socket the three travel inside the JSON-RPC 2.0+//! envelope [`crate::rpc`] describes, which adds an id to tie a response to+//! its request and nothing else.+//!+//! A method that takes longer than a caller should wait - an export - is a+//! job: the response names it at once, and everything that happens to it+//! comes back as [`Event`]s carrying that name, ending in `export.done` or+//! `export.failed`. A refusal is an [`ApiError`]: a [`ErrorCode`] a program+//! can branch on and the sentence a person would be shown.//!//! The edit vocabulary is not redefined here. [`Request::EditApply`] carries//! a `concat_project` [`Command`] as it is, so every operation the window@@ -29,7 +38,7 @@ use serde_json::Value;/// The version of this contract. Bumped when a method's shape changes in a/// way a caller written against the previous one would misread; adding a/// method or an optional field does not bump it.-pub const API_VERSION: &str = "0.1";+pub const API_VERSION: &str = "0.2";/// What a caller asks for. One variant per method, named `area.verb`.///@@ -182,9 +191,11 @@ pub enum Request {},/// Renders an open project's active timeline to a file, exactly as- /// the window's Export does: titles painted, cutouts analysed, then the- /// frame loop and the mix. Blocks until the file is written, reporting- /// through [`Event`]s.+ /// the window's Export does: cutouts analysed, titles painted, then the+ /// frame loop and the mix. Returns at once with the job's name; the+ /// render runs on its own thread and reports through [`Event`]s, ending+ /// in [`Event::ExportDone`] or [`Event::ExportFailed`]. One export runs+ /// at a time; a second is refused as [`ErrorCode::Busy`].#[serde(rename = "export.run")]ExportRun {/// The project folder.@@ -193,20 +204,26 @@ pub enum Request {#[serde(flatten)]spec: ExportSpec,},- /// Stops the export that is running, if one is. Meaningful only from a- /// transport that can speak while a dispatch blocks.+ /// Stops a running export at its next frame. The job then ends with+ /// [`Event::ExportFailed`] carrying [`ErrorCode::Cancelled`].#[serde(rename = "export.cancel")]- ExportCancel,+ ExportCancel {+ /// The job [`Started`] named.+ job: String,+ },- /// Composites the true frame at one instant and writes it as a PNG.+ /// Composites the true frame at one instant. Written as a PNG to+ /// `output` when there is one, and handed back inline as a+ /// [`Picture`] otherwise, for a caller on the far side of a socket.#[serde(rename = "preview.frame")]PreviewFrame {/// The project folder.path: String,/// The timeline instant, in seconds.time: f64,- /// The file to write.- output: String,+ /// The file to write; absent means the picture comes back inline.+ #[serde(default)]+ output: Option<String>,/// Frame width; the timeline's when absent.#[serde(default)]width: Option<u32>,@@ -281,9 +298,12 @@ pub enum Reply {Templates(Vec<TemplateInfo>),/// [`Request::TemplateSave`].Template(TemplateInfo),- /// [`Request::ExportRun`] and [`Request::PreviewFrame`]: the file- /// written.+ /// [`Request::ExportRun`]: the job that is now running.+ Started(Started),+ /// [`Request::PreviewFrame`] with an output: the file written.Written(Written),+ /// [`Request::PreviewFrame`] without one: the picture itself.+ Picture(Picture),/// Methods with nothing to say beyond having worked.Done(Done),}@@ -331,6 +351,30 @@ pub struct Written {pub height: u32,}+/// A job the API has begun. Every event about it carries `job`.+#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct Started {+ /// The job's name, unique for the life of the API: "j1", "j2", ...+ pub job: String,+ /// The project it works on.+ pub path: String,+ /// The file it will write.+ pub output: String,+}++/// A frame handed back without touching the disk.+#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct Picture {+ /// Its picture size.+ pub width: u32,+ /// Its picture size.+ pub height: u32,+ /// The PNG, base64 in the standard alphabet with padding.+ pub png: String,+}+/// The empty reply, an object so every reply is one.#[derive(Clone, Copy, PartialEq, Debug, Default, Serialize, Deserialize)]pub struct Done {}@@ -384,8 +428,89 @@ pub struct ParamInfo {pub labels: Vec<String>,}+/// Why a request has no reply, as a program reads it. The JSON-RPC number+/// each maps to is [`ErrorCode::number`].+#[derive(Clone, Copy, PartialEq, Eq, Debug, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub enum ErrorCode {+ /// The line was not JSON.+ Parse,+ /// The JSON was not a request: an unknown method, a missing or+ /// ill-typed field, a value out of range.+ Invalid,+ /// The project named is not open; open it first.+ NotOpen,+ /// A job, template or package named does not exist.+ NotFound,+ /// The edit layer said no. The message is the sentence the window+ /// would show, and the state is as it was.+ Refused,+ /// A one-at-a-time job is already running.+ Busy,+ /// The job was stopped by [`Request::ExportCancel`].+ Cancelled,+ /// Everything else: a file that could not be read or written, a decode+ /// that failed, a model that did not download.+ Failed,+}++impl ErrorCode {+ /// The code's JSON-RPC 2.0 number: the standard ones for the standard+ /// meanings, and server-defined ones (-32000 downwards) for the rest.+ pub fn number(self) -> i64 {+ match self {+ ErrorCode::Parse => -32700,+ ErrorCode::Invalid => -32600,+ ErrorCode::Failed => -32000,+ ErrorCode::NotOpen => -32001,+ ErrorCode::NotFound => -32002,+ ErrorCode::Refused => -32003,+ ErrorCode::Busy => -32004,+ ErrorCode::Cancelled => -32005,+ }+ }+}++/// A refusal: what kind, and the sentence a person would be shown.+#[derive(Clone, PartialEq, Eq, Debug, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct ApiError {+ /// What kind of refusal.+ pub code: ErrorCode,+ /// The sentence.+ pub message: String,+}++impl ApiError {+ /// An error of `code` saying `message`.+ pub fn new(code: ErrorCode, message: impl Into<String>) -> ApiError {+ ApiError {+ code,+ message: message.into(),+ }+ }++ /// [`ErrorCode::Invalid`].+ pub fn invalid(message: impl Into<String>) -> ApiError {+ ApiError::new(ErrorCode::Invalid, message)+ }++ /// [`ErrorCode::Failed`].+ pub fn failed(message: impl Into<String>) -> ApiError {+ ApiError::new(ErrorCode::Failed, message)+ }+}++impl std::fmt::Display for ApiError {+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ f.write_str(&self.message)+ }+}++impl std::error::Error for ApiError {}+/// A request's outcome. `{"result": ...}` when it worked, `{"error":-/// "..."}` with the sentence a person would be shown when it did not.+/// {"code": ..., "message": ...}}` when it did not.#[derive(Clone, Serialize)]#[serde(rename_all = "camelCase")]#[allow(clippy::large_enum_variant)]@@ -393,11 +518,11 @@ pub enum Response {/// The reply.Result(Reply),/// Why there is none.- Error(String),+ Error(ApiError),}-impl From<Result<Reply, String>> for Response {- fn from(result: Result<Reply, String>) -> Self {+impl From<Result<Reply, ApiError>> for Response {+ fn from(result: Result<Reply, ApiError>) -> Self {match result {Ok(reply) => Response::Result(reply),Err(error) => Response::Error(error),@@ -405,24 +530,19 @@ impl From<Result<Reply, String>> for Response {}}-/// Something that happened while a request ran. A transport forwards-/// these as they come; a caller that does not care ignores them.+/// Something that happened to a job. A transport forwards these to every+/// caller as they come; each names its job and its project, so a caller+/// keeps the ones it asked for and ignores the rest.#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]#[serde(tag = "event", rename_all_fields = "camelCase")]pub enum Event {- /// The export moved on.- #[serde(rename = "export.progress")]- ExportProgress {- /// Frames done.- frame: i64,- /// Frames in total.- total: i64,- /// "rendering", "mixing audio" or "muxing".- stage: String,- },/// A cutout's masks are being found ahead of an export.#[serde(rename = "cutout.progress")]CutoutProgress {+ /// The job.+ job: String,+ /// The project folder.+ path: String,/// The media being analysed.media_id: String,/// True while a model downloads, false while it runs.@@ -430,14 +550,66 @@ pub enum Event {/// How far along, `0..=1`.fraction: f32,},+ /// The export moved on.+ #[serde(rename = "export.progress")]+ ExportProgress {+ /// The job.+ job: String,+ /// The project folder.+ path: String,+ /// Frames done.+ frame: i64,+ /// Frames in total.+ total: i64,+ /// "video", "audio" or "mux".+ stage: String,+ },+ /// The export wrote its file. The job is over.+ #[serde(rename = "export.done")]+ ExportDone {+ /// The job.+ job: String,+ /// The project folder.+ path: String,+ /// The file written.+ output: String,+ /// Its picture size.+ width: u32,+ /// Its picture size.+ height: u32,+ },+ /// The export did not write its file. The job is over.+ #[serde(rename = "export.failed")]+ ExportFailed {+ /// The job.+ job: String,+ /// The project folder.+ path: String,+ /// Why: [`ErrorCode::Cancelled`] when asked to stop, otherwise what+ /// went wrong.+ error: ApiError,+ },}-impl From<Progress> for Event {- fn from(progress: Progress) -> Self {+impl Event {+ /// [`Event::ExportProgress`] for one report from the renderer.+ pub fn progress(job: &str, path: &str, progress: Progress) -> Event {Event::ExportProgress {+ job: job.to_owned(),+ path: path.to_owned(),frame: progress.frame,total: progress.total,stage: progress.stage.to_owned(),}}++ /// The job this event is about.+ pub fn job(&self) -> &str {+ match self {+ Event::CutoutProgress { job, .. }+ | Event::ExportProgress { job, .. }+ | Event::ExportDone { job, .. }+ | Event::ExportFailed { job, .. } => job,+ }+ }}diff --git a/src/crates/concat-api/src/rpc.rs b/src/crates/concat-api/src/rpc.rsnew file mode 100644index 00000000..0a5cafad--- /dev/null+++ b/src/crates/concat-api/src/rpc.rs@@ -0,0 +1,229 @@+// SPDX-License-Identifier: AGPL-3.0-or-later+// SPDX-FileCopyrightText: 2026 Jareer and Concat contributors++//! The JSON-RPC 2.0 envelope: what a line transport - stdin, a socket -+//! puts around a [`Request`], a [`Response`] and an [`Event`].+//!+//! A call is `{"jsonrpc": "2.0", "id": 1, "method": "edit.apply", "params":+//! {...}}`; its response is `{"jsonrpc": "2.0", "id": 1, "result": ...}` or+//! `{"jsonrpc": "2.0", "id": 1, "error": {"code": -32001, "message": "...",+//! "data": {"code": "notOpen"}}}`; an event is a notification, `{"jsonrpc":+//! "2.0", "method": "export.progress", "params": {...}}`. The id is the+//! caller's and comes back as given, so a caller with several requests in+//! flight tells the responses apart; every call gets a response, id or+//! not, because a transport that never answers is not one a script can+//! drive.+//!+//! For a person typing at the stdin transport, the bare shape+//! `{"method": "...", ...fields}` is accepted too: it is the request with no+//! envelope, and it is answered with a null id.++use serde_json::{Map, Value, json};++use crate::message::{ApiError, ErrorCode, Event, Request, Response};++/// A caller's id: a string, a number or null, echoed back as given.+pub type Id = Value;++/// One incoming line, parsed.+#[derive(Clone, PartialEq, Debug)]+pub struct Call {+ /// The caller's id, when it gave one.+ pub id: Option<Id>,+ /// What it asked for.+ pub request: Request,+}++impl Call {+ /// Parses one line. A line that is not a call comes back as the error+ /// to answer it with, alongside whatever id could be read from it, so+ /// the caller that sent it can still match the refusal.+ pub fn parse(line: &str) -> Result<Call, (Option<Id>, ApiError)> {+ let value: Value = serde_json::from_str(line)+ .map_err(|error| (None, ApiError::new(ErrorCode::Parse, error.to_string())))?;+ let Value::Object(mut object) = value else {+ return Err((None, ApiError::invalid("a request is a JSON object")));+ };+ let id = match object.remove("id") {+ None => None,+ Some(id @ (Value::String(_) | Value::Number(_) | Value::Null)) => Some(id),+ Some(_) => {+ return Err((+ None,+ ApiError::invalid("an id is a string, a number or null"),+ ));+ }+ };+ let refuse = |message: String| (id.clone(), ApiError::invalid(message));++ let flat = match object.remove("jsonrpc") {+ None => object,+ Some(Value::String(version)) if version == "2.0" => {+ let Some(Value::String(method)) = object.remove("method") else {+ return Err(refuse("a call names its method".to_owned()));+ };+ let mut flat = match object.remove("params") {+ None | Some(Value::Null) => Map::new(),+ Some(Value::Object(params)) => params,+ Some(_) => return Err(refuse("params is an object".to_owned())),+ };+ flat.insert("method".to_owned(), Value::String(method));+ flat+ }+ Some(_) => return Err(refuse("jsonrpc is \"2.0\"".to_owned())),+ };+ let request = serde_json::from_value::<Request>(Value::Object(flat))+ .map_err(|error| refuse(error.to_string()))?;+ Ok(Call { id, request })+ }+}++/// One outgoing line.+#[derive(Clone)]+#[allow(clippy::large_enum_variant)]+pub enum Message {+ /// The answer to a call.+ Reply {+ /// The call's id; null when it gave none.+ id: Option<Id>,+ /// The answer.+ response: Response,+ },+ /// Something that happened to a job.+ Event(Event),+}++impl Message {+ /// The line, without its newline.+ pub fn to_json(&self) -> String {+ self.to_value().to_string()+ }++ /// The envelope as a JSON value.+ pub fn to_value(&self) -> Value {+ match self {+ Message::Reply { id, response } => {+ let id = id.clone().unwrap_or(Value::Null);+ match response {+ Response::Result(reply) => {+ json!({ "jsonrpc": "2.0", "id": id, "result": reply })+ }+ Response::Error(error) => json!({+ "jsonrpc": "2.0",+ "id": id,+ "error": {+ "code": error.code.number(),+ "message": error.message,+ "data": { "code": error.code },+ },+ }),+ }+ }+ Message::Event(event) => {+ // The event's tag becomes the notification's method and the+ // rest of its fields its params, so an event reads like a+ // call the server made.+ let mut params = match serde_json::to_value(event) {+ Ok(Value::Object(fields)) => fields,+ _ => Map::new(),+ };+ let method = params.remove("event").unwrap_or(Value::Null);+ json!({ "jsonrpc": "2.0", "method": method, "params": params })+ }+ }+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::message::{Done, Reply};++ #[test]+ fn an_envelope_parses_to_the_request_it_wraps() {+ let call = Call::parse(+ r#"{"jsonrpc":"2.0","id":7,"method":"project.open","params":{"path":"/p"}}"#,+ )+ .expect("a call");+ assert_eq!(call.id, Some(json!(7)));+ assert_eq!(+ call.request,+ Request::ProjectOpen {+ path: "/p".to_owned()+ }+ );+ }++ #[test]+ fn a_bare_request_is_a_call_without_an_id() {+ let call = Call::parse(r#"{"method":"project.list"}"#).expect("a call");+ assert_eq!(call.id, None);+ assert_eq!(call.request, Request::ProjectList);+ let named = Call::parse(r#"{"id":"a","method":"project.list"}"#).expect("a call");+ assert_eq!(named.id, Some(json!("a")));+ }++ #[test]+ fn a_bad_line_says_why_and_keeps_the_id() {+ let (id, error) = Call::parse("{").expect_err("not JSON");+ assert_eq!((id, error.code), (None, ErrorCode::Parse));+ let (id, error) =+ Call::parse(r#"{"jsonrpc":"2.0","id":3,"method":"nope"}"#).expect_err("no such method");+ assert_eq!((id, error.code), (Some(json!(3)), ErrorCode::Invalid));+ assert!(error.message.contains("nope"), "{}", error.message);+ let (_, error) =+ Call::parse(r#"{"jsonrpc":"1.0","method":"version"}"#).expect_err("wrong version");+ assert_eq!(error.code, ErrorCode::Invalid);+ let (_, error) = Call::parse(r#"{"id":{},"method":"version"}"#).expect_err("bad id");+ assert_eq!(error.code, ErrorCode::Invalid);+ }++ #[test]+ fn a_reply_carries_the_id_and_an_error_its_code_twice() {+ let ok = Message::Reply {+ id: Some(json!(1)),+ response: Response::Result(Reply::Done(Done {})),+ };+ assert_eq!(+ ok.to_value(),+ json!({ "jsonrpc": "2.0", "id": 1, "result": {} })+ );+ let refused = Message::Reply {+ id: None,+ response: Response::Error(ApiError::new(ErrorCode::NotOpen, "/p is not open")),+ };+ assert_eq!(+ refused.to_value(),+ json!({+ "jsonrpc": "2.0",+ "id": null,+ "error": {+ "code": -32001,+ "message": "/p is not open",+ "data": { "code": "notOpen" }+ }+ })+ );+ }++ #[test]+ fn an_event_is_a_notification_named_after_its_tag() {+ let event = Message::Event(Event::ExportDone {+ job: "j1".to_owned(),+ path: "/p".to_owned(),+ output: "/o.mp4".to_owned(),+ width: 16,+ height: 9,+ });+ assert_eq!(+ event.to_value(),+ json!({+ "jsonrpc": "2.0",+ "method": "export.done",+ "params": {+ "job": "j1", "path": "/p", "output": "/o.mp4", "width": 16, "height": 9+ }+ })+ );+ }+}diff --git a/src/crates/concat-cli/src/main.rs b/src/crates/concat-cli/src/main.rsindex 84a8d9a6..52f2592a 100644--- a/src/crates/concat-cli/src/main.rs+++ b/src/crates/concat-cli/src/main.rs@@ -6,7 +6,7 @@//! This exists so the engine can be exercised end to end without a UI. The//! `render` command is the vertical slice: probe, build a timeline, plan every//! frame, decode, composite, encode. The `api` command is the Concat API's-//! first transport: JSON requests in, JSON responses and events out, one per+//! first transport: JSON-RPC requests in, responses and events out, one per//! line, so a script in any language edits and exports a project. `preview`//! is how the window's effect cards get their pictures: one still through one//! package at its defaults.@@ -14,8 +14,10 @@use std::error::Error;use std::io::{BufRead, Write};use std::path::PathBuf;+use std::sync::Arc;use clap::{Parser, Subcommand};+use concat_api::rpc::{Call, Message};use concat_core::time::{FrameRate, Rational};use concat_core::timeline::{Clip, MediaRef, Timeline, Track, TrackKind};use concat_media::{@@ -52,8 +54,9 @@ enum Command {fade: u64,},- /// Speak the Concat API: a JSON request per line on stdin, a response per- /// line on stdout, with events in between as they happen.+ /// Speak the Concat API: a JSON-RPC request per line on stdin, a+ /// response per line on stdout, with events from running jobs as they+ /// happen. A bare `{"method": ..., ...}` without the envelope works too.Api {/// One request to run instead of reading stdin.request: Option<String>,@@ -100,32 +103,22 @@ fn main() -> Result<(), Box<dyn Error>> {}}-/// The stdin transport. Every line in is one request; every line out is-/// one JSON object, either an event or the response, flushed as written so-/// a caller reading a pipe sees progress as it happens. A line that is not-/// a request gets an error response and the loop goes on.+/// The stdin transport. Every line in is one call; every line out is one+/// JSON object, a response or an event, written whole under stdout's lock+/// and flushed, so a caller reading a pipe sees progress as it happens and+/// never half a line. A line that is not a call gets an error response and+/// the loop goes on. At the end of input the jobs still running - an export+/// begun on the last line - are waited for, so their events are written+/// before the process exits.fn api(single: Option<String>) -> Result<(), Box<dyn Error>> {- let mut api = concat_api::Api::new()?;- let stdout = std::io::stdout();-- let mut serve = |line: &str| -> Result<(), Box<dyn Error>> {- let mut out = stdout.lock();- let response = match serde_json::from_str::<concat_api::Request>(line) {- Ok(request) => api.dispatch(request, &mut |event| {- // An event that cannot be written is a caller that went- // away; the response's write will say so.- let _ = serde_json::to_writer(&mut out, &event)- .and_then(|()| writeln!(out).map_err(serde_json::Error::io));- let _ = out.flush();- }),- Err(error) => concat_api::Response::Error(format!("not a request: {error}")),+ let mut api = concat_api::Api::new(Arc::new(|event| emit(&Message::Event(event))))?;+ let mut serve = |line: &str| {+ let (id, response) = match Call::parse(line) {+ Ok(call) => (call.id, api.dispatch(call.request)),+ Err((id, error)) => (id, concat_api::Response::Error(error)),};- serde_json::to_writer(&mut out, &response)?;- writeln!(out)?;- out.flush()?;- Ok(())+ emit(&Message::Reply { id, response });};-match single {Some(line) => serve(&line),None => {@@ -134,11 +127,20 @@ fn api(single: Option<String>) -> Result<(), Box<dyn Error>> {if line.trim().is_empty() {continue;}- serve(&line)?;+ serve(&line);}- Ok(())}}+ api.finish();+ Ok(())+}++/// One line to stdout. A line that cannot be written is a caller that+/// went away, and the loop learns that from stdin's end.+fn emit(message: &Message) {+ let mut out = std::io::stdout().lock();+ let _ = writeln!(out, "{}", message.to_json());+ let _ = out.flush();}/// One frame of `input`, scaled to the card's size, through `effect` at its