@cloudspe/video-core

Framework-free video engine for Livepeer worker pools. VOD + Live HLS dispatch with an adapter-driven billing / auth / storage / webhooks surface — bring your own. MIT.

npm install @cloudspe/video-core

The engine handles what (orchestration, manifest assembly, payment quoting, retries, webhook signing); how is your call. Wire your own Postgres + Stripe? Done. Bring your own Redis-backed rate limiter? Done. Plug into S3 / R2 / RustFS / Wasabi for storage? Done. The full adapter set is nine interfaces, each ~10 lines.

Quickstart

The examples/minimal-shell/ directory ships a runnable Fastify app (~200 LOC) that wires the engine to in-memory adapters. It's the fastest way to see the surface:

cd examples/minimal-shell
npm install
node start.js

# In another terminal:
curl -s -X POST http://localhost:8080/v1/uploads \
  -H "Authorization: Bearer demo-token" \
  -H "Content-Type: application/json" \
  -d '{"offering":"h264-1080p","encodingTier":"baseline"}' | jq

The example uses InMemoryWallet, FakeAuthResolver, and FakeStorageProvider from @cloudspe/video-core/testing — useful for kicking the tires; not for production. Real adopters supply production adapters (Postgres-backed wallet, JWT or API-key auth, S3-compatible storage).

For a fully-wired reference, see Cloud-SPE/livepeer-video-platform — the proprietary shell + worker that this engine ships out of.

The adapter surface

You implement these. The engine calls them.

| Adapter | Purpose | |---|---| | Wallet | reserve / commit / refund against a video-shaped CostQuote (time × codec × rendition × tier) | | AuthResolver | request headers / IP → Caller | | AdminAuthResolver | admin-token → { actor } | | RateLimiter | per-(callerId, capability) token bucket | | Logger | info / warn / error / debug with structured context | | StorageProvider | S3-shaped bytes transport (engine owns the path conventions) | | WebhookSink | signed delivery + retry queue | | WorkerResolver | discover workers by capability | | WorkerClient | dispatch to a worker URL with a payment ticket header | | EventBus | per-caller event emit; the WebhookSink fan-out lives here | | StreamKeyHasher | argon2id / scrypt for live stream keys (and shared with API keys) |

@cloudspe/video-core/testing exports reference fakes for every one of these. They're not for production but they let you build, test, and reason about a shell without wiring real backends first.

Dispatchers (the framework-free entry points)

import {
  dispatchUploadCreate,
  dispatchVodSubmit,
  dispatchVodStatus,
  dispatchLiveStreamCreate,
  dispatchLiveStreamStop,
  dispatchLiveStreamStatus,
  dispatchPlaybackResolve,
} from '@cloudspe/video-core';

Each dispatcher is a pure function over a DispatchCommon deps bag (plus its own input). The Fastify adapter at @cloudspe/video-core/fastify provides registerVideoRoutes(app, deps) that mounts them as HTTP routes and maps VideoCoreError → JSON envelope via toHttpError. If Fastify isn't your framework, the dispatchers work just as well behind Express, Hono, h3, or whatever you ship.

dispatchAbrSubmit + dispatchAbrStatus are stubs at MVP — the ABR-on-demand surface lands post-1.0.

Architecture

                  ┌─────────────────────────────┐
                  │  HTTP framework (Fastify,   │
                  │  Express, Hono, …)          │
                  └─────────────┬───────────────┘
                                │
                  ┌─────────────▼───────────────┐
                  │  @cloudspe/video-core      │
                  │                             │
                  │   • Dispatchers             │
                  │   • Job orchestrator        │
                  │   • Manifest builder        │
                  │   • Cost quoter             │
                  │   • Webhook signer          │
                  │   • Storage path conventions│
                  └─┬───────────────────────────┘
                    │ adapter calls
                    ▼
   ┌────────────┐  ┌──────────────┐  ┌───────────────┐
   │   Wallet   │  │ AuthResolver │  │   Storage     │
   │ (your impl)│  │ (your impl)  │  │  (your impl)  │
   └────────────┘  └──────────────┘  └───────────────┘
   …all eleven adapters configured by the operator…
                    │
                    ▼
            ┌───────────────────────┐
            │ Livepeer worker pool  │
            │ (FFmpeg + RTMP + HLS) │
            └───────────────────────┘

Optional read-only operator dashboard

@cloudspe/video-core/dashboard exports registerOperatorDashboard(app, deps) for an opt-in /admin/ops/* mount. Vanilla TS; no Lit / RxJS / Vite. Serves a small HTML page that polls /admin/ops/data.json every 5s and renders worker pool + recent assets + active live streams + recent webhook deliveries. Adopters supply a DashboardDataSource (or use the default factory createDefaultDashboardDataSource over their existing repos).

What this engine is not

• Not a managed video platform. You run it. The engine is the middle layer; you bring storage, billing, auth, deployment.
• Not a transcoder. The engine orchestrates work; the actual encode happens in a Livepeer worker (or any worker that satisfies the engine's capability + payment-ticket protocol).
• Not framework-coupled. Fastify is shipped as one optional adapter. The dispatchers themselves don't import fastify or any other HTTP framework.

Documentation

• docs/architecture.md — how the engine fits together; what it owns vs what the operator owns.
• docs/adapters.md — the full adapter surface with TypeScript shapes + reference-fake pointers.
• docs/examples.md — walkthroughs of examples/minimal-shell/ and examples/wallets/.
• CONTRIBUTING.md — how to file bugs, propose features, run the test suite, follow our coding conventions.
• SECURITY.md — how to report vulnerabilities.
• CODE_OF_CONDUCT.md — Contributor Covenant v2.1.
• GOVERNANCE.md — maintainers, decision rules, forking guidance.
• CHANGELOG.md — Keep-a-Changelog formatted.

Versioning

Pre-1.0: breaking changes may land in any 0.x release; documented in CHANGELOG.md. Adapter shape changes are minor bumps pre-1.0 and major bumps post-1.0. 1.0.0 cuts when the engine has been adopted by an external operator and the adapter surface has been stable across at least one release cycle.

Build + test

npm install
npm run build           # tsc → dist/
npm test                # vitest run
npm run typecheck       # tsc --noEmit
npm run lint            # eslint

Coverage gate is 75% lines / branches / functions / statements.

License

MIT — see LICENSE.

Copyright (c) 2026 Cloud-SPE contributors.