Lumi content library

The content library is a core Lumi service for storing and delivering streaming and multimedia resources. Administrators manage it from Admin → Resources.

Storage

Files are stored under:

data/content-library/files/

Temporary uploads remain under the same data directory so normal Lumi backup and update boundaries preserve them. Deletion removes the stored file directly, which also works on Windows network-backed storage where directory renames may be restricted.

The Resources page displays:

bytes currently used by registered resources;
physical free space on the filesystem hosting Lumi's content directory;
Lumi's configured free-space reserve;
an optional content-library quota;
the effective space available to Lumi, which is the smaller of remaining quota and usable physical space.

A quota of 0 means that Lumi does not impose an additional library limit. Physical disk space and the configured reserve still apply.

Saved quotas, reserves, per-file limits, and per-upload file counts apply to the next upload immediately. The storage cards, settings fields, upload guidance, and client-side selection checks update without a page refresh.

Access levels

Locked

Locked resources do not have a permanent public URL. They can be read by:

authenticated Lumi administrators through the WebUI preview/download route;
Lumi server code through global.lumiFrameworks.resources;
a short-lived signed URL explicitly created by Lumi.

Exposed

Exposed resources receive a high-entropy, read-only URL under /media/.... The URL supports HTTP byte ranges for video/audio seeking and can be used in OBS browser/media sources, overlays, alerts, and external integrations.

Changing an exposed resource back to locked removes its token. The previous URL stops resolving. Exposing it again creates a new URL.

Core framework API

Core features and plugins running inside Lumi can use:

const resources = global.lumiFrameworks.resources;

const all = resources.list({ category: "audio" });
const item = resources.get(resourceId);
const absolutePath = resources.resolvePath(resourceId);
const { stream } = resources.openReadStream(resourceId);

// Returns a permanent URL only when the resource is exposed.
const publicUrl = resources.publicUrl(resourceId, "https://lumi.example.com");

// Works for locked or exposed resources and expires automatically.
const temporaryUrl = resources.createSignedUrl(resourceId, {
  base_url: "https://lumi.example.com",
  ttl_seconds: 300
});

global.lumiFrameworks.content is an alias of the same API.

Supported formats

The library accepts common streaming assets and verifies that file contents match their extensions. Supported groups include:

images and graphics: PNG/APNG, JPEG/JFIF, WebP, GIF, AVIF, HEIC/HEIF, BMP, TIFF, ICO, PSD, and sanitized SVG;
audio: MP3, WAV, Ogg/Opus, FLAC, M4A, AAC, WebM audio, Matroska audio, WMA, CAF, and AIFF;
video: MP4/M4V, MOV, WebM, OGV, MKV, AVI, MPEG, transport stream formats, 3GP, FLV, WMV, and MXF;
captions/data: WebVTT, SRT, ASS/SSA, JSON, and Lottie JSON;
documents and fonts: PDF, WOFF/WOFF2, TTF/TTC, and OTF.

Browser preview support depends on the codecs installed in the browser/OBS Chromium build. A file can be accepted and delivered correctly even when the browser cannot decode its preview, such as some MKV, AVI, HEIC, PSD, WMA, or MXF files.

Active web-document formats such as HTML and JavaScript are intentionally not accepted as resources. Safe custom webpages remain the responsibility of Lumi's custom page and overlay web-source systems.

Delivery behavior

Raw delivery includes:

Accept-Ranges: bytes and single-range 206 Partial Content responses;
stable MIME types and X-Content-Type-Options: nosniff;
ETags for efficient revalidation;
permissive CORS/Cross-Origin-Resource-Policy headers for exposed and signed media;
read-only routes with no mutation capability.

Admin downloads use a dedicated attachment route so browsers download the original file instead of opening their built-in audio or video player.

Verification

Run:

npm run verify:content

The focused check creates a temporary database and content directory, verifies locked/exposed transitions, URL signing, token invalidation, storage accounting, file deletion, byte-range parsing, route registration, and required WebUI elements.

4.3 KiB Raw Blame History