# 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:

```text
data/content-library/files/
```

Temporary uploads and deletion staging remain under the same data directory so normal Lumi backup and update boundaries preserve them.

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.

## 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:

```js
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.

## Verification

Run:

```bash
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.