@omelhorsite/video-sdk 0.2.0

package/README.md

@@ -0,0 +1,103 @@
+# `@omelhorsite/video-sdk`
+
+The engine of the omelhorsite video editor, as a library: the project model,
+the math that puts every clip where it belongs, the effects, the karaoke
+captions, the compiler that turns all of it into `ffmpeg` arguments, and the
+client for the omelhorsite cloud.
+
+```sh
+bun add @omelhorsite/video-sdk
+```
+
+It is pure. Nothing here reads a file or spawns a process: files come in and
+go out as `Blob` or `Uint8Array`, and rendering is a function that returns the
+arguments for `ffmpeg`. That is what lets it run in Bun, Node 18+ and the
+browser alike.
+
+## The project
+
+A `Project` is `{ width, height, fps, assets[], tracks[] }`. Tracks render
+bottom to top in array order; a clip is `{ start, duration, in }` in seconds on
+the project timeline, and a visual clip carries a `transform` whose `x`/`y` are
+the centre in normalised coordinates and whose `scale` multiplies the size the
+asset gets when fitted inside the frame.
+
+An `.omsv` file is a ZIP with that object and all of its media inside,
+portable and self-contained.
+
+```ts
+import { emptyProject, packProject, unpackProject, isZipData } from "@omelhorsite/video-sdk";
+
+const project = emptyProject();
+project.assets.push({ id: "a1", kind: "video", name: "clip.mp4", path: "clip.mp4", duration: 12 });
+project.tracks[1].clips.push({
+  id: "c1", kind: "video", assetId: "a1", start: 0, duration: 4, in: 2,
+  transform: { x: 0.5, y: 0.5, scale: 1, opacity: 1 }, fadeIn: 0, fadeOut: 0, muted: false, volume: 1,
+});
+
+const bytes = packProject({ project, assetBytes: new Map([["a1", clipBytes]]), nowIso: new Date().toISOString() });
+const { project: again, assetBytes } = unpackProject(bytes);
+```
+
+## Rendering
+
+`compile` returns the `ffmpeg` argument list for the whole project in one
+pass: layers, transforms, fades, text, effects and captions. Text arrives
+rasterised, as PNGs the caller provides, so what was drawn is what gets
+composited.
+
+```ts
+import { compile, projectDuration } from "@omelhorsite/video-sdk";
+
+const { args } = compile(project, { output: "out.mp4", preset: "slow", crf: 17, textImages });
+// spawn("ffmpeg", args)
+```
+
+`placement.ts` is the one place that decides where a clip goes (`fittedSize`,
+`clipRect`, `visibleAt`); a preview drawn with the same functions matches the
+export by construction.
+
+## Effects and captions
+
+- `makeFlashClip(id, cutAt)` builds the flash transition that hides a cut;
+  `DEFAULT_FLASH` holds its parameters.
+- Captions live in the project in source time (`project.captions[].words`,
+  `{ t0, t1, text }`), so cutting or reordering never invalidates them.
+  `timelineWords(project)` brings the words onto the timeline; `groupWords`
+  and `captionStates` do the karaoke grouping.
+- `sliceProject(project, from, to)` cuts a window out of a project for a fast
+  partial render.
+
+## The omelhorsite cloud
+
+`Cloud` signs in with the device grant, keeps whole projects in the account's
+storage, and runs transcription and captions on the server. It takes a
+`TokenStore` for the tokens and, when the host needs it, a `fetch`.
+
+```ts
+import { Cloud, memoryTokenStore, describeCloudError } from "@omelhorsite/video-sdk";
+
+const cloud = new Cloud({ store: memoryTokenStore() });
+await cloud.login({ onPrompt: (p) => show(p.userCode, p.url) });
+
+const saved = await cloud.uploadProject({ data: bytes, name: "promo" }, { onProgress: report });
+const projects = await cloud.listProjects();
+const { data } = await cloud.downloadProject(saved.id);
+
+const tx = await cloud.transcribe({ data: wav, name: "voice.wav" }, { language: "pt" });
+const captioned = await cloud.captions({ data: mp4, name: "render.mp4" }, { words: timelineWords(project) });
+```
+
+`stringTokenStore` adapts anything that can keep a string (a file, a
+keychain) into a `TokenStore`. `describeCloudError` turns any failure into a
+sentence fit for a screen. Progress arrives per finished transfer, or per byte
+where the runtime has `XMLHttpRequest` and no custom `fetch` was given.
+
+## Developing
+
+```sh
+bun test            # renders real mp4 files with the system ffmpeg
+bun run typecheck
+bun run check:isolate
+bun run build
+```