@omnimedia/omnitool 1.1.0-8 → 1.1.0-80

package/README.md

@@ -1,120 +1,337 @@
 
 # 🚧 Work In Progress
 
-> **Note:** Omni Tools is under development. Expect breaking changes, evolving APIs, and experimental features.
+> **Note:** Omnitool is under development. Expect breaking changes, evolving APIs, and experimental features.
 
 ---
 
-# 🎬 Omnitool
+## ✅ What this library is
 
-> Code-first video editing toolkit behind [Omniclip](https://omniclip.app) — build timelines, render videos, and automate workflows.
+- API for building and rendering timelines in the browser
+- Uses WebCodecs, Web Workers, and the File System Access API for export
+- usage is currently JavaScript/TypeScript only, cli soon
 
----
+## 🚀 Install
 
-## 🧱 Modular by Design
+```bash
+npm i @omnimedia/omnitool
+```
 
-Omni Tools is a collection of composable utilities for working with Omniclip timelines — via code, JSON, or CLI.
+## 📦 Quick Start
 
-- ✅ Define timelines in JSON or TypeScript
-- ✅ Automate rendering with CLI tools
-- ✅ Ideal for scripting, CI/CD, and AI-generated workflows
+#### Declaring the timeline
 
----
-
-## 🚀 Quick Start
+```ts
+import {Driver, Omni, Datafile} from "@omnimedia/omnitool"
+
+const driver = await Driver.setup()
+const omni = new Omni(driver)
+
+const {clip} = await omni.load({
+	clip: Datafile.make(file) // file is a File or Blob
+})
+
+const timeline = omni.timeline(o => {
+	const caption = o.text("Hello world", {
+		duration: 1500,
+		styles: {fill: "white", fontSize: 48}
+	})
+	const xfade = o.transition.crossfade(500)
+	const softened = o.filter.blur.make({strength: 8, quality: 4})
+
+	return o.sequence(
+		o.stack(
+			o.video(clip, {start: 0, duration: 3000, filterIds: [softened.id]}),
+			caption
+		),
+		o.gap(400),
+		xfade,
+		o.video(clip, {start: 5000, duration: 2500}),
+		o.audio(clip, {start: 5000, duration: 2500})
+	)
+})
+```
 
-### Install
+Declarative helper style (no explicit `o` in timeline declarations):
 
-```bash
-npm i @omnimedia/omnitool
+```ts
+import {
+	Driver, Omni, Datafile,
+	timeline, stack, video, audio, text, gap, transition, filter
+} from "@omnimedia/omnitool"
+
+const driver = await Driver.setup()
+const omni = new Omni(driver)
+const {clip} = await omni.load({clip: Datafile.make(file)})
+
+const timeline = timeline(
+	stack(
+		filter.blur(
+			video(clip, {start: 0, duration: 3000}),
+			{strength: 8, quality: 4}
+		),
+		text("Hello world", {duration: 1500}),
+	),
+	gap(400),
+	transition.crossfade(500),
+	video(clip, {start: 5000, duration: 2500}),
+	audio(clip, {start: 5000, duration: 2500})
+)
 ```
 
----
+## 🎛 Filters
 
-## 📦 Example (Programmatic Timeline)
+Filter application:
 
 ```ts
-import { subtitle, crossfade, sequence, stack, video } from "@omni/tools"
-
-const watermark = subtitle("omniclip")
-const xfade = crossfade(500)
-
-const timeline = sequence(
-  video("opening-credits.mp4"),
-  xfade,
-  stack(
-    video("skateboarding.mp4"),
-    watermark
-  ),
-  xfade,
-  stack(
-    video("biking.mp4"),
-    watermark
-  )
+const timeline = omni.timeline(o =>
+	o.stack(
+		o.filter.blur(
+			o.video(clip, {duration: 3000}),
+			{strength: 8, quality: 4}
+		),
+		o.filter.glow(
+			o.text("Hello world", {duration: 3000}),
+			{distance: 12, outerStrength: 2, color: "#ffffff"}
+		)
+	)
 )
-	
 ```
 
----
+Reusable filter items:
 
-## 🧩 Timeline Format (Omni Timeline Format)
+```ts
+const timeline = omni.timeline(o => {
+	const blur = o.filter.blur.make({strength: 8, quality: 4})
+
+	return o.stack(
+		o.video(clip, {duration: 3000, filterIds: [blur.id]}),
+		o.text("Caption", {duration: 3000, styles: {fill: "white"}})
+	)
+})
+```
 
-Every timeline is defined as a graph:
+Filter metadata for UI:
 
-```json
-{
-  "format": "omni-timeline@1",
-  "root": "root-1",
-  "items": [
-    ["root-1", ["sequence", { "children": ["video-1", "stack-1"] }]],
-    ["video-1", ["video", { ... }]],
-    ["stack-1", ["stack", { "children": ["text-1", "audio-1"] }]],
-    ["text-1", ["text", { ... }]],
-    ["audio-1", ["audio", { ... }]]
-  ]
-}
+```ts
+import {
+	filters
+} from "@omnimedia/omnitool"
+
+const available = Object.entries(filters)
+const blur = filters.blur
+const schema = blur.schema
 ```
 
-Each item is a `[id, item]` pair. Items can reference others by ID, forming a directed graph of reusable, composable blocks.
+## 🧭 Spatial Transforms
 
----
+```ts
+const timeline = omni.timeline(o => {
+	const move = o.spatial(o.transform({
+		position: [120, 40],
+		scale: [0.6, 0.6],
+		rotation: 0.2
+	}))
+
+	const title = o.text("Lower third", {
+		duration: 2000,
+		styles: {fill: "white", fontSize: 36}
+	})
+	o.set(title.id, {spatialId: move.id})
+
+	return o.stack(
+		o.video(clip, {duration: 4000}),
+		title
+	)
+})
+```
 
-## 🖥 CLI Usage
+Animated spatial transforms:
 
-```bash
-# Build a timeline (manually or via AI)
-omnitool build-template promo.json
+```ts
+const timeline = omni.timeline(o => {
+	const slideIn = o.animatedSpatial(
+		o.anim.transform("linear", [
+			[0, o.transform({position: [-400, 0]})],
+			[1000, o.transform({position: [0, 0]})],
+		])
+	)
+
+	const title = o.text("Lower third", {
+		duration: 2000,
+		styles: {fill: "white", fontSize: 36}
+	})
+	o.set(title.id, {spatialId: slideIn.id})
+
+	return o.stack(
+		o.video(clip, {duration: 4000}),
+		title
+	)
+})
+```
 
-# Validate structure
-omnitool validate promo.json
+Animation application:
 
-# Render video
-omnitool export promo.json --output final.mp4
+```ts
+const timeline = omni.timeline(o => {
+	const title = o.animate.opacity(
+		o.text("Lower third", {
+			duration: 2000,
+			styles: {fill: "white", fontSize: 36},
+		}),
+		"easeIn",
+		[
+			[0, 0],
+			[700, 1],
+		]
+	)
+
+	return o.stack(
+		o.video(clip, {duration: 4000}),
+		title
+	)
+})
+```
 
-# Batch render
-omnitool batch-export ./projects/* --output-dir ./exports
+Reusable animation:
+
+```ts
+const timeline = omni.timeline(o => {
+	const fadeIn = o.animate.opacity.make("easeIn", [
+		[0, 0],
+		[700, 1],
+	])
+
+	const title = o.text("Lower third", {
+		duration: 2000,
+		styles: {fill: "white", fontSize: 36},
+	})
+	o.set(title.id, {animationId: fadeIn.id})
+
+	return o.stack(
+		o.video(clip, {duration: 4000}),
+		title
+	)
+})
 ```
 
----
+Animation registry:
 
-## ✅ Use Cases
+```ts
+import {animations} from "@omnimedia/omnitool"
 
-- Render videos from scripts, templates, or AI
-- Build and test timelines without opening the UI
-- Generate video pipelines from code or prompts
+Object.entries(animations).forEach(([property, meta]) => {
+	console.log(property, meta.type, meta.defaultTerp, meta.channels)
+	// transform transform linear [...]
+	// opacity scalar linear [...]
+})
+```
 
----
+Each animation definition describes the semantic shape of the animation: its value kind, default interpolation, and numeric channels with defaults and units. This is useful for tools that need to create valid keyframes without hardcoding Omnitool's track layout.
 
-## 📘 More to come
+Worker URL notes:
+- `Driver.setup()` defaults to `/node_modules/@omnimedia/omnitool/x/driver/driver.worker.bundle.min.js`.
+- If you serve the worker from a different location, pass `workerUrl`:
 
-- `omnitool preview` – headless timeline viewer
-- `omnitool optimize` – auto-fit timeline elements
-- `omnitool ai` – native prompt-to-timeline generation
+```ts
+const workerUrl = new URL(
+	"/path/to/driver.worker.bundle.min.js",
+	window.location.href
+)
+const driver = await Driver.setup({workerUrl})
+```
 
----
+## ▶️ Playback
+
+```ts
+const player = await omni.playback(timeline)
+
+document.body.appendChild(player.canvas)
+player.play()
+```
+
+Notes:
+- Call `player.update(timeline)` if you update the timeline.
+
+## 📤 Export
+
+```ts
+await omni.render(timeline, framerate)
+```
+
+## 🧩 Timeline Format (TimelineFile)
 
-## 🧠 Learn More
+All durations and timestamps are in milliseconds.
 
-Omni Tools powers AI agents, programmatic editing, and upcoming new version of omniclip video editor.
+```json
+{
+	"format": "timeline",
+	"info": "https://omniclip.app/",
+	"version": 0,
+	"rootId": 123,
+	"items": [
+		{"id": 123, "kind": 0, "childrenIds": [456, 789]},
+		{"id": 456, "kind": 2, "mediaHash": "...", "start": 0, "duration": 3000},
+		{"id": 789, "kind": 4, "content": "Hello", "duration": 1500}
+	]
+}
+```
+
+Timeline items:
+- 0 `Sequence`
+- 1 `Stack`
+- 2 `Video`
+- 3 `Audio`
+- 4 `Text`
+- 5 `Gap`
+- 6 `Spatial`
+- 7 `Transition`
+- 8 `TextStyle`
+- 9 `Filter`
+
+## 🗺️ Roadmap
+- CLI commands:
+
+```bash
+# build a reusable template from a timeline
+omnitool build-template promo.json
+# validate a timeline file
+omnitool validate promo.json
+# export a timeline to a video file
+omnitool export promo.json --output final.mp4
+# batch export multiple timelines
+omnitool batch-export ./projects/* --output-dir ./exports
+# headless timeline viewer
+omnitool preview promo.json
+# auto-fit timeline elements
+omnitool optimize promo.json
+# prompt-to-timeline generation
+omnitool ai "make a 15s promo for tea"
+```
+
+- smooth seeking
+- keyframes
+- custom filters, likely via driver-side registration with timeline sugar such as:
+
+```ts
+// Register custom filter
+driver.registerFilter({
+	type: "vhs",
+	make: params => new Filter(/* ... */),
+	schema: {
+		intensity: {type: "number", min: 0, max: 1, default: 0.5},
+		scanlines: {type: "boolean", default: true},
+	},
+})
+
+// Use custom filter
+const timeline = omni.timeline(o =>
+	o.filter.custom(
+		"vhs",
+		o.video(clip, {duration: 3000}),
+		{intensity: 0.8}
+	)
+)
+```
 
-→ [Visit Omniclip](https://omniclip.app)
+- server-side, not just browsers

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@omnimedia/omnitool",
-	"version": "1.1.0-8",
+	"version": "1.1.0-80",
 	"description": "open source video processing tools",
 	"license": "MIT",
 	"author": "Przemysław Gałęzki",
@@ -19,31 +19,33 @@
 		"_ln-s": "ln -s \"$(realpath s)\" x/s",
 		"_ln-assets": "ln -s \"$(realpath assets)\" x/assets",
 		"_scute": "scute -v",
-		"test": "node x/tests.test.js",
+		"test": "echo \"node tests disabled for now\"",
 		"test-debug": "node inspect x/tests.test.js"
 	},
 	"devDependencies": {
-		"@e280/science": "^0.0.6",
-		"@e280/scute": "^0.0.0-7",
-		"@types/node": "^24.2.0",
+		"@e280/science": "^0.1.4",
+		"@e280/scute": "^0.1.2",
+		"@types/node": "^25.0.3",
+		"@types/wicg-file-system-access": "^2023.10.7",
 		"http-server": "^14.1.1",
 		"npm-run-all": "^4.1.5",
-		"typescript": "^5.9.2"
+		"typescript": "^5.9.3"
 	},
 	"dependencies": {
-		"@benev/slate": "^0.3.9",
-		"@e280/comrade": "^0.0.0-23",
-		"@e280/renraku": "^0.5.0-29",
-		"@e280/stz": "^0.0.0-34",
-		"@huggingface/transformers": "^3.7.1",
+		"@e280/comrade": "^0.1.0",
+		"@e280/renraku": "^0.5.3",
+		"@e280/sly": "^0.2.5",
+		"@e280/strata": "^0.2.5",
+		"@e280/stz": "^0.2.15",
+		"@huggingface/transformers": "^3.8.1",
 		"comrade": "^0.0.3",
 		"gl-transitions": "^1.43.0",
-		"gsap": "^3.13.0",
-		"mediabunny": "^1.14.3",
-		"mp4-muxer": "^5.2.1",
-		"pixi.js": "^8.10.1",
-		"wavesurfer.js": "^7.10.0",
-		"web-demuxer": "^2.3.8"
+		"gsap": "^3.14.2",
+		"lit": "^3.3.2",
+		"mediabunny": "^1.27.3",
+		"pixi-filters": "^6.1.5",
+		"pixi.js": "^8.14.3",
+		"wavesurfer.js": "^7.12.1"
 	},
 	"homepage": "https://github.com/omni-media/omnitool#readme",
 	"repository": {

package/s/context.ts

@@ -1,7 +0,0 @@
-import {Driver} from "./driver/driver.js"
-
-const workerUrl = new URL("../driver/driver.worker.bundle.min.js", import.meta.url)
-
-export const context = {
-	driver: Driver.setup({workerUrl})
-}

package/s/demo/demo.bundle.ts

@@ -1,21 +1,22 @@
 
-import {context} from "../context.js"
+import {Driver} from "../driver/driver.js"
+import type {Omni, TimelineFile} from "../timeline/index.js"
+import {playbackTest} from "./routines/playback-test.js"
 import {waveformTest} from "./routines/waveform-test.js"
+import {TimelineSchemaTest } from "./routines/timeline-setup.js"
 import {filmstripTest} from "./routines/filmstrip-test.js"
-import {transcriberTest} from "./routines/transcriber-test.js"
 import {setupTranscodeTest} from "./routines/transcode-test.js"
 
-const driver = await context.driver
-const results = document.querySelector(".results")!
+const driver = await Driver.setup({workerUrl: new URL("../driver/driver.worker.bundle.min.js", import.meta.url)})
 
-const fetchButton = document.querySelector(".fetch")
-const importButton = document.querySelector(".import") as HTMLButtonElement
+const transcodeCard = document.querySelector("[data-demo='transcode']") as HTMLElement
+const filmstripCard = document.querySelector("[data-demo='filmstrip']") as HTMLElement
+const waveformCard = document.querySelector("[data-demo='waveform']") as HTMLElement
+const playbackCard = document.querySelector("[data-demo='playback']") as HTMLElement
+const exportCard = document.querySelector("[data-demo='export']") as HTMLElement
+const exportButton = exportCard.querySelector("[data-action='export']") as HTMLButtonElement
 
-fetchButton?.addEventListener("click", startDemoFetch)
-importButton?.addEventListener("click", startDemoImport)
-
-waveformTest()
-const transcriber = await transcriberTest(driver)
+let exportState: {timeline: TimelineFile; omni: Omni} | null = null
 
 // hello world test
 {
@@ -24,45 +25,105 @@ const transcriber = await transcriberTest(driver)
 	else console.error("❌ FAIL driver call didn't work")
 }
 
-// transcoding tests
-async function startDemoImport()
-{
-	const [fileHandle] = await window.showOpenFilePicker()
-	const file = await fileHandle.getFile()
-	const transcode = setupTranscodeTest(driver, file)
-	await filmstripTest(file)
-	run(transcode, fileHandle.name)
-	await transcriber.transcribe(file)
-}
-
-async function startDemoFetch()
-{
+const setProgress = (card: HTMLElement, state: "idle" | "running" | "done") => {
+	const progress = card.querySelector(".progress") as HTMLProgressElement | null
+	const status = card.querySelector(".status") as HTMLSpanElement | null
 
-	// which videos to run tests on
-	const videos = [
-		"/assets/temp/gl.mp4",
-	]
+	if (!progress || !status)
+		return
 
-	// running each test in sequence
-	for (const url of videos) {
-		const transcode = setupTranscodeTest(driver, "/assets/temp/gl.mp4")
-		run(transcode, url)
+	if (state === "running") {
+		progress.removeAttribute("value")
+		status.textContent = "running"
+	} else if (state === "done") {
+		progress.value = 1
+		status.textContent = "done"
+	} else {
+		progress.value = 0
+		status.textContent = "idle"
 	}
 }
 
-async function run(transcode: ReturnType<typeof setupTranscodeTest>, label: string) {
-	// create result div
-	const div = document.createElement("div")
-	results.append(div)
+const bindDemo = (
+	card: HTMLElement,
+	run: (file: File, card: HTMLElement) => Promise<void>
+) => {
+	const input = card.querySelector("input[type='file']") as HTMLInputElement
+	const button = card.querySelector("[data-action='run']") as HTMLButtonElement
 
-	// add video label
-	const p = document.createElement("p")
-	p.textContent = label
-	div.append(p)
+	button.disabled = true
+	input.addEventListener("input", () => {
+		button.disabled = !input.files?.length
+	})
 
-	// add the canvas to dom
-	div.append(transcode.canvas)
+	button.addEventListener("click", async () => {
+		const file = input.files?.[0]
+		if (!file)
+			return
 
-	// run the test
+		button.disabled = true
+		setProgress(card, "running")
+		try {
+			await run(file, card)
+			setProgress(card, "done")
+		} finally {
+			button.disabled = false
+		}
+	})
+}
+
+bindDemo(transcodeCard, async (file, card) => {
+	const preview = card.querySelector(".demo-preview") as HTMLDivElement
+	const transcode = setupTranscodeTest(driver, file)
+	preview.replaceChildren(transcode.canvas)
 	await transcode.run()
+})
+
+bindDemo(filmstripCard, async (file, card) => {
+	await filmstripTest(file, card)
+})
+
+bindDemo(waveformCard, async (file, card) => {
+	await waveformTest(driver, file, card)
+})
+
+{
+	const input = playbackCard.querySelector("input[type='file']") as HTMLInputElement
+	input.addEventListener("input", async () => {
+		const file = input.files?.[0]
+		if (!file)
+			return
+
+		const {timeline, omni} = await TimelineSchemaTest(driver, file)
+		await playbackTest(timeline, omni, playbackCard)
+	})
+}
+
+{
+	const input = exportCard.querySelector("input[type='file']") as HTMLInputElement
+	input.addEventListener("input", async () => {
+		const file = input.files?.[0]
+		if (!file)
+			return
+
+		setProgress(exportCard, "running")
+		const {timeline, omni} = await TimelineSchemaTest(driver, file)
+		exportState = {timeline, omni}
+		exportButton.disabled = false
+
+		const preview = exportCard.querySelector(".demo-preview") as HTMLDivElement
+		const player = await omni.playback(timeline)
+		await player.seek(0)
+		preview.replaceChildren(player.canvas)
+		setProgress(exportCard, "done")
+	})
 }
+
+exportButton.addEventListener("click", async () => {
+	if (!exportState)
+		return
+
+	setProgress(exportCard, "running")
+	await exportState.omni.render(exportState.timeline)
+	setProgress(exportCard, "done")
+})