Skip to content

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

feat(api): ids, error codes, exports as jobs, and frames inline

Jareerb862141afa98
diff --git a/src/Cargo.lock b/src/Cargo.lock
index 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.toml
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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