@animacamos/core

Platform-neutral core primitives for real-time video / camera applications.

@animacamos/core defines the fundamental contract shared by any TypeScript/JavaScript application that captures, transports, or outputs video frames in real time. It is deliberately tiny, dependency-free, and agnostic of:

• WebRTC, signaling, RTP
• Tauri, Electron, WebView
• React, Vue, Next.js
• any operating system
• any concrete virtual-camera implementation
• any UI framework

What's inside

| Concept | TypeScript | Rust (twin crate) | |---------|------------|-------------------| | Session lifecycle | Session, SessionState, SessionId | Session, SessionState, SessionId | | Device descriptor | Device, DeviceKind | Device, DeviceKind | | Video characteristics | VideoFormat, PixelFormat | VideoFormat, PixelFormat | | Decoded frame | VideoFrame, Timestamp | VideoFrame, Timestamp | | Latest-frame-wins fan-out | FrameHub, FrameHubConsumer | FrameHub, FrameHubConsumer | | Camera output contract | CameraOutput (interface) | CameraOutput (trait) | | Events | CoreEvent, EventBus | CoreEvent, EventBus | | Errors | CoreError, AnimacamosError | CoreError |

Install

npm install @animacamos/core
# or
bun add @animacamos/core

Example

import { Session, makeVideoFormat, makeVideoFrame, FrameHub } from "@animacamos/core";

const session = new Session();
session.connect();
session.markConnected();

const hub = new FrameHub();
const fmt = makeVideoFormat(1920, 1080, "I420", 30);
if (fmt.ok) {
  const data = new Uint8Array(1920 * 1080 * 3 / 2);
  const frame = makeVideoFrame(fmt.value, data, 0);
  if (frame.ok) hub.publish(frame.value);
}

See examples/basic.ts for a runnable program.

Design principles

1. Zero runtime dependencies.
2. Strict TypeScript — strict, noUncheckedIndexedAccess, noUnusedLocals.
3. Small public surface — only the documented types are exported from the package root.
4. Latest-frame-wins — the FrameHub never accumulates stale frames.
5. Backpressure by contract — CameraOutput.pushFrame never blocks.
6. Framework-agnostic — no React, Vue, or DOM dependency.

What this package does NOT include

• WebRTC, RTP, signaling
• any H.264 / VPx decoder
• any concrete camera backend (v4l2, Media Foundation, CoreMediaIO)
• Tauri / Electron / WebView integration
• any UI
• any network code
• any authentication / licensing

Coherence with the Rust crate

The TypeScript types mirror the Rust crate animacamos-core concept-for-concept. The internal implementations differ (Rust uses atomics + Arc, TS uses a simple class), but the public contract is the same — a Rust core and a TS frontend can exchange these structures via plain JSON / structured clones.

License

MIT. See LICENSE.