@omnimedia/omnitool 1.1.0-5 → 1.1.0-51

package/README.md

@@ -1,120 +1,183 @@
 
 # 🚧 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
 
----
-
-## 🧱 Modular by Design
+## 🚀 Install
 
-Omni Tools is a collection of composable utilities for working with Omniclip timelines — via code, JSON, or CLI.
+```bash
+npm i @omnimedia/omnitool
+```
 
-- ✅ Define timelines in JSON or TypeScript
-- ✅ Automate rendering with CLI tools
-- ✅ Ideal for scripting, CI/CD, and AI-generated workflows
+## 📦 Quick Start
 
----
+#### 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)
+
+	return o.sequence(
+		o.stack(
+			o.video(clip, {start: 0, duration: 3000}),
+			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
+} 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(
+		video(clip, {start: 0, duration: 3000}),
+		text("Hello world", {duration: 1500}),
+	),
+	gap(400),
+	transition.crossfade(500),
+	video(clip, {start: 5000, duration: 2500}),
+	audio(clip, {start: 5000, duration: 2500})
+)
 ```
 
----
+## 🧭 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
+	)
+})
+```
 
-## 📦 Example (Programmatic Timeline)
+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`:
 
 ```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 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()
+```
 
-## 🧩 Timeline Format (Omni Timeline Format)
+Notes:
+- Call `player.update(timeline)` if you update the timeline.
 
-Every timeline is defined as a graph:
+## 📤 Export
+
+```ts
+await omni.render(timeline, framerate)
+```
+
+## 🧩 Timeline Format (TimelineFile)
+
+All durations and timestamps are in milliseconds.
 
 ```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", { ... }]]
-  ]
+	"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}
+	]
 }
 ```
 
-Each item is a `[id, item]` pair. Items can reference others by ID, forming a directed graph of reusable, composable blocks.
+Timeline items:
+- 0 `Sequence`
+- 1 `Stack`
+- 2 `Video`
+- 3 `Audio`
+- 4 `Text`
+- 5 `Gap`
+- 6 `Spatial`
+- 7 `Transition`
+- 8 `TextStyle`
 
----
-
-## 🖥 CLI Usage
+## 🗺️ Roadmap
+- CLI commands:
 
 ```bash
-# Build a timeline (manually or via AI)
+# build a reusable template from a timeline
 omnitool build-template promo.json
-
-# Validate structure
+# validate a timeline file
 omnitool validate promo.json
-
-# Render video
+# export a timeline to a video file
 omnitool export promo.json --output final.mp4
-
-# Batch render
+# 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"
 ```
 
----
-
-## ✅ Use Cases
-
-- Render videos from scripts, templates, or AI
-- Build and test timelines without opening the UI
-- Generate video pipelines from code or prompts
-
----
-
-## 📘 More to come
-
-- `omnitool preview` – headless timeline viewer
-- `omnitool optimize` – auto-fit timeline elements
-- `omnitool ai` – native prompt-to-timeline generation
-
----
-
-## 🧠 Learn More
-
-Omni Tools powers AI agents, programmatic editing, and upcoming new version of omniclip video editor.
+- smooth seeking
+- keyframes
+- server-side, not just browsers
 
-→ [Visit Omniclip](https://omniclip.app)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@omnimedia/omnitool",
-	"version": "1.1.0-5",
+	"version": "1.1.0-51",
 	"description": "open source video processing tools",
 	"license": "MIT",
 	"author": "Przemysław Gałęzki",
@@ -19,30 +19,32 @@
 		"_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",
-		"mediabunny": "^1.4.4",
-		"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.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,103 @@ 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)
+const setProgress = (card: HTMLElement, state: "idle" | "running" | "done") => {
+	const progress = card.querySelector(".progress") as HTMLProgressElement
+	const status = card.querySelector(".status") as HTMLSpanElement
+
+	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 startDemoFetch()
-{
+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
 
-	// which videos to run tests on
-	const videos = [
-		"/assets/temp/gl.mp4",
-	]
+	button.disabled = true
+	input.addEventListener("input", () => {
+		button.disabled = !input.files?.length
+	})
 
-	// running each test in sequence
-	for (const url of videos) {
-		const transcode = setupTranscodeTest(driver, "/assets/temp/gl.mp4")
-		run(transcode, url)
-	}
+	button.addEventListener("click", async () => {
+		const file = input.files?.[0]
+		if (!file)
+			return
+
+		button.disabled = true
+		setProgress(card, "running")
+		try {
+			await run(file, card)
+			setProgress(card, "done")
+		} finally {
+			button.disabled = false
+		}
+	})
 }
 
-async function run(transcode: ReturnType<typeof setupTranscodeTest>, label: string) {
-	// create result div
-	const div = document.createElement("div")
-	results.append(div)
+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()
+})
 
-	// add video label
-	const p = document.createElement("p")
-	p.textContent = label
-	div.append(p)
+bindDemo(filmstripCard, async (file, card) => {
+	await filmstripTest(file, card)
+})
 
-	// add the canvas to dom
-	div.append(transcode.canvas)
+bindDemo(waveformCard, async (file, card) => {
+	await waveformTest(driver, file, card)
+})
 
-	// run the test
-	await transcode.run()
+{
+	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")
+})
+