98 lines
3.9 KiB
Markdown
98 lines
3.9 KiB
Markdown
# 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.
|