@arsenstorm/olos

OLOS

Open Live Object Streaming protocol primitives. A generic live object streaming protocol: a low-latency append-only stream log over plain object storage (S3, R2, GCS), with CMAF/LL-HLS as its first profile.

Install

npm install @arsenstorm/olos

Imports

import { OLOS_PROTOCOL_NAME, OLOS_WIRE_VERSION } from "@arsenstorm/olos";
import type { Session } from "@arsenstorm/olos/types";

Subpath	Use for
@arsenstorm/olos/runtime	Session routes, publisher loops, HLS serving.
@arsenstorm/olos/s3	S3 upload grants, observation, events, recovery, retention. Needs @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner installed by the consumer (optional peer dependencies).
@arsenstorm/olos/media	CMAF/LL-HLS profile: media session/track/object profiles, validators, schemas, publisher pacing.
@arsenstorm/olos/hls	HLS rendering and blocking-reload helpers.
@arsenstorm/olos/protocol	Coordinator stores and adapter conformance.
@arsenstorm/olos/state	Lower-level state transitions and policies.
@arsenstorm/olos/schema	JSON Schemas for wire objects.
@arsenstorm/olos/validation	Runtime payload validators.
@arsenstorm/olos/types	Public protocol data types.
@arsenstorm/olos/config	Protocol constants and policy defaults.
@arsenstorm/olos/conformance	Assertion metadata and store checks.

Quick start

A complete OLOS endpoint with S3-backed live media (the CMAF/LL-HLS profile):

import {
  createMemorySerializedCoordinatorStoreBackend,
  createSerializedCoordinatorStore,
} from "@arsenstorm/olos/protocol";
import { createStoredS3CoordinatorRuntimeHandler } from "@arsenstorm/olos/s3";
import { S3Client } from "@aws-sdk/client-s3";

const store = createSerializedCoordinatorStore(
  createMemorySerializedCoordinatorStoreBackend()
);

const s3 = new S3Client({ region: "us-east-1" });

const handleOlos = createStoredS3CoordinatorRuntimeHandler({
  allowedDeliveryOrigins: ["https://media.example.com"],
  bucket: "olos-media",
  client: s3,
  expiresInSeconds: 5,
  providerId: "s3_primary",
  store,
});

export default { fetch: (req: Request) => handleOlos(req) };

Publishers create a session, then loop: get a presigned slot, PUT media bytes to S3, post a commit. Viewers GET HLS manifests. The handler covers it.

A session declares the profile it runs under and a profile per track. Core treats profile objects as opaque; @arsenstorm/olos/media defines and validates the CMAF/LL-HLS ones:

import { CMAF_LLHLS_PROFILE_ID } from "@arsenstorm/olos/media";

await fetch("https://olos.example.com/sessions", {
  body: JSON.stringify({
    deliveryBaseUrl: "https://media.example.com",
    session: {
      createdAt: new Date().toISOString(),
      epoch: 1,
      olos: "1.0",
      profile: { id: CMAF_LLHLS_PROFILE_ID, partTarget: 0.5, segmentTarget: 2 },
      sessionId: "session_1",
      state: "live",
      tracks: [
        {
          profile: { bitrate: 5_000_000, codec: "avc1.640028", kind: "video" },
          trackId: "v1080",
        },
      ],
    },
  }),
  headers: { "content-type": "application/json" },
  method: "POST",
});

Slot requests and commits carry the same kind of opaque profile object (for LL-HLS: { duration, independent, programDateTime }).

Working setups:

• examples/api — Cloudflare Worker + Durable Object + R2.
• examples/streamer — OBS-to-OLOS bridge using ffmpeg micro-segments.
• examples/player — LL-HLS player at the PART-HOLD-BACK spec floor.

Routes

The handler mounts:

Method	Path	Purpose
POST	/sessions	Create a session.
POST	/sessions/:id/s3/slots	Issue a presigned upload slot.
POST	/sessions/:id/s3/commits	Observe and commit an upload.
POST	/sessions/:id/s3/events	Accept S3 object-created events.
POST	/sessions/:id/s3/reconcile-plan	List in-flight slots for recovery.
POST	/sessions/:id/s3/reconcile	Recover slots after missed events.
POST	/sessions/:id/s3/retention	Prune retired state and delete retired media.
POST	/sessions/:id/upload-slots/:slotId/complete	Publisher completion hint (alternative to waiting for events).
POST	/sessions/:id/transition	Advance session state.
POST	/sessions/:id/heartbeat	Publisher liveness ping.
GET	/sessions/:id/health	Live / starting / stale summary.
GET	/v1/live/:id/master.m3u8	Master playlist (variants, audio groups).
GET	/v1/live/:id/.../media.m3u8	LL-HLS playlist with _HLS_msn blocking reload.

The /sessions and /v1/live prefixes are the defaults. The handler's sessionPath and livePath options configure them. Error responses always carry error.code from the registered OLOS_ERROR_CODES set, next to error.message.

Layers

OLOS is layered. Core defines the commit semantics. Above it are a profile (the CMAF/LL-HLS profile ships in @arsenstorm/olos/media and @arsenstorm/olos/hls), a storage binding (@arsenstorm/olos/s3), a delivery mapping, the direct-public deployment profile, and runtime guidance. Spec Section 2 defines the layers and the split between what OLOS owns and what your app owns.

Further reading

• Production pipeline — wiring a real deployment.
• Store adapters — coordinator store on SQL, KV, or Durable Objects.
• Direct-public deployment — when uploaded media is readable before the manifest gates it.
• Conformance — assertion catalogue covering the protocol surface.

Release check

bun --filter '@arsenstorm/olos' publish:check