@omnimedia/omnitool 1.1.0-9 → 1.1.0-90

package/README.md

@@ -1,120 +1,405 @@
 
 # 🚧 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
 
----
+```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})
+	)
+})
+```
 
-## 🚀 Quick Start
+Declarative helper style (no explicit `o` in timeline declarations):
 
-### Install
+```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})
+)
+```
 
-```bash
-npm i @omnimedia/omnitool
+## 🎛 Filters
+
+Filter application:
+
+```ts
+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:
 
-## 📦 Example (Programmatic Timeline)
+```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"}})
+	)
+})
+```
+
+Filter metadata for UI:
 
 ```ts
-import { subtitle, crossfade, sequence, stack, video } from "@omni/tools"
+import {
+	filters
+} from "@omnimedia/omnitool"
 
-const watermark = subtitle("omniclip")
-const xfade = crossfade(500)
+const available = Object.entries(filters)
+const blur = filters.blur
+const schema = blur.schema
+```
 
-const timeline = sequence(
-  video("opening-credits.mp4"),
-  xfade,
-  stack(
-    video("skateboarding.mp4"),
-    watermark
-  ),
-  xfade,
-  stack(
-    video("biking.mp4"),
-    watermark
-  )
-)
-	
+## 🧭 Spatial Transforms
+
+```ts
+const timeline = omni.timeline(o => {
+	const move = o.spatial(o.transform({
+		position: [120, 40],
+		scale: [0.6, 0.6],
+		rotation: 12
+	}))
+
+	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
+	)
+})
 ```
 
----
+Animations:
 
-## 🧩 Timeline Format (Omni Timeline Format)
+```ts
+const timeline = omni.timeline(o => {
+	const fadeIn = o.animate.opacity.make("easeIn", [
+		[0, 0],
+		[700, 1],
+	])
+	const slideOut = o.animate.transform.make("linear", [
+		[0, o.transform({position: [0, 0]})],
+		[1000, o.transform({position: [400, 0]})],
+	])
+
+	const title = o.text("Lower third", {
+		duration: 2000,
+		styles: {fill: "white", fontSize: 36}
+	})
+	o.set(title.id, {animationIds: [fadeIn.id, slideOut.id]})
+
+	return o.stack(
+		o.video(clip, {duration: 4000}),
+		title
+	)
+})
+```
 
-Every timeline is defined as a graph:
+Built-in transform animations:
 
-```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
+const animOut = {
+	duration: 500,
+	offset: item.duration - 500,
 }
+const slideIn = o.animate.presets.slideIn.make()
+const slideOut = o.animate.presets.slideOut.make(animOut)
+const spinIn = o.animate.presets.spinIn.make()
+const spinOut = o.animate.presets.spinOut.make(animOut)
+const zoomIn = o.animate.presets.zoomIn.make()
+const zoomOut = o.animate.presets.zoomOut.make(animOut)
+const bounceIn = o.animate.presets.bounceIn.make()
+const bounceOut = o.animate.presets.bounceOut.make(animOut)
 ```
 
-Each item is a `[id, item]` pair. Items can reference others by ID, forming a directed graph of reusable, composable blocks.
+Built-in scalar animations:
 
----
+```ts
+const fadeIn = o.animate.presets.fadeIn.make()
+const fadeOut = o.animate.presets.fadeOut.make(animOut)
+```
 
-## 🖥 CLI Usage
+Animation application:
 
-```bash
-# Build a timeline (manually or via AI)
-omnitool build-template promo.json
+```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
+	)
+})
+```
 
-# Validate structure
-omnitool validate promo.json
+Reusable animation:
 
-# Render video
-omnitool export promo.json --output final.mp4
+```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, {animationIds: [fadeIn.id]})
+
+	return o.stack(
+		o.video(clip, {duration: 4000}),
+		title
+	)
+})
+```
 
-# Batch render
-omnitool batch-export ./projects/* --output-dir ./exports
+Animation metadata:
+
+```ts
+import {animatableProperties, animationPresets} from "@omnimedia/omnitool"
+
+Object.entries(animatableProperties).forEach(([property, meta]) => {
+	console.log(property, meta.type, meta.defaultTerp, meta.channels)
+	// transform transform linear [...]
+	// opacity scalar linear [...]
+})
+
+Object.entries(animationPresets).forEach(([preset, meta]) => {
+	console.log(preset, meta.type, meta.label, meta.defaults)
+	// slideIn motion Slide in {...}
+	// slideOut motion Slide out {...}
+	// spinIn motion Spin in {...}
+	// spinOut motion Spin out {...}
+	// zoomIn motion Zoom in {...}
+	// zoomOut motion Zoom out {...}
+	// bounceIn motion Bounce in {...}
+	// bounceOut motion Bounce out {...}
+	// fadeIn scalar Fade in {...}
+	// fadeOut scalar Fade out {...}
+})
 ```
 
----
+Animatable properties describe what can be keyframed, such as `transform` and `opacity`.
+Animation presets describe built-in recipes, such as `slideIn` and `fadeIn`.
+Use `animationPresets` to list available recipes, and `o.animate.presets` to create animation items.
+Use `o.animate` to create or apply animation items.
 
-## ✅ Use Cases
+Preset options:
+- `duration` sets the animation duration, defaulting to `700`.
+- `offset` shifts generated keyframes in item-local time.
+  Useful for out animations: `item.duration - 500` starts `slideOut` 500ms before the item ends.
+- `from` sets the start value, like opacity `0` or position `[-400, 0]`.
+- `to` sets the end value, like opacity `1` or position `[0, 0]`.
+- `terp` sets interpolation, defaulting to the preset's `terp`.
 
-- Render videos from scripts, templates, or AI
-- Build and test timelines without opening the UI
-- Generate video pipelines from code or prompts
+Utils:
 
----
+```ts
+import {resolveScalarAnimation, resolveTransformAnimation} from "@omnimedia/omnitool"
 
-## 📘 More to come
+const transform = resolveTransformAnimation(localTime, transformAnimation)
+const opacity = resolveScalarAnimation(localTime, opacityAnimation)
+```
 
-- `omnitool preview` – headless timeline viewer
-- `omnitool optimize` – auto-fit timeline elements
-- `omnitool ai` – native prompt-to-timeline generation
+`resolveTransformAnimation` resolves an animated transform at the given local time.
+`resolveScalarAnimation` resolves an animated scalar value at the given local time.
+`localTime` is time relative to the item being resolved.
+`clamp` is the default and currently only extrapolation mode, holding the first or last keyframe value outside the authored range.
 
----
+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
+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)
+await player.play()
+player.playbackRate = 0.5 // slow motion
+player.playbackRate = -1 // reverse
+```
+
+Notes:
+- Call `await player.update(timeline)` if you update the timeline.
+- `playbackRate` supports slower, faster, and reverse visual playback. Audio currently plays only at `1`.
+
+## 📤 Export
+
+```ts
+await omni.render(timeline, framerate)
+```
+
+## 🧩 Timeline Format (TimelineFile)
+
+All durations and timestamps are in milliseconds.
+
+```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:
 
-## 🧠 Learn More
+```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:
 
-Omni Tools powers AI agents, programmatic editing, and upcoming new version of omniclip video editor.
+```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-9",
+	"version": "1.1.0-90",
 	"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})
-}