Velum files
Velum files
Everything people export from Velum Studio, share, download or double-click is a Velum file. There are six types, and they all use one container, so one reader and one set of rules covers them all.
The types
| Extension | MIME type | What it holds |
|---|---|---|
.velumscenes |
application/x-velum-scenes |
A scene collection: scenes, sources, effects, automations, Screen Detect detectors, Dynamic Source libraries, framings, and every media file they use |
.velumprofile |
application/x-velum-profile |
Settings: canvas sizes, audio, the platforms and servers you stream to (never their keys), and the dock layout |
.velumtheme |
application/x-velum-theme |
A theme, with its preview, icon and any fonts or pictures it uses. See Sharing a theme. |
.velumpreset |
application/x-velum-preset |
One piece to drop into any collection: a layer, a scene, a Dynamic Source with its library, or an automation |
.velumbackup |
application/x-velum-backup |
Everything, for moving to a new computer: every collection and its media, settings, layout, themes and saved looks |
.velumplugin |
application/x-velum-plugin |
A plugin. See Packaging and signing. |
Studio's own working files on disk stay plain JSON. Velum files are for moving things between computers and people. Double-clicking one opens Studio with an import sheet, and if Studio is already running, the file goes to that Studio.
The container
A Velum file is a zip archive. Entries are stored or deflated (no other compression methods, no encryption), with forward-slash paths.
manifest.json what the file is, and a fingerprint of everything else
<type>.json the type's own content, in the same shape Studio stores it
preview.png optional: a picture of it, shown before importing
media/ the files it uses, each stored once
signature.ed25519 optionalThe type's JSON is named after the type: collection.json, profile.json, theme.json, preset.json, backup.json, plugin.json.
The manifest
{
"type": "velum.scenes",
"format": 1,
"created": "2026-10-04T20:15:00Z",
"app": "0.1.0",
"name": "Racing Setup",
"description": "My race nights",
"thumbnail": "preview.png",
"contents": [
{"path": "collection.json", "sha256": "9f2c…", "bytes": 48211},
{"path": "media/3fa94c1e0b7d22a8/logo.png", "sha256": "3fa94c1e0b7d22a8…", "bytes": 120533}
],
"left_out": [
{"used_by": "Intro", "name": "intro.mov", "reason": "missing"}
],
"folders": {
"folders/1": {"name": "Slides", "files": [{"name": "01.png", "media": "media/77ab…/01.png"}]}
}
}| Field | Meaning |
|---|---|
type |
velum.scenes, velum.profile, velum.theme, velum.preset, velum.backup or velum.plugin. |
format |
The container format, currently 1. Older formats are upgraded when a file is opened. A file with a newer format than the reader understands is refused with a message saying so; it is never half-read. |
created |
When the file was made (RFC 3339, UTC). |
app |
The Studio version that made it. |
name, description |
Shown before importing. |
thumbnail |
The preview picture's path in the file, if it has one. |
contents |
Every file in the archive except manifest.json and signature.ed25519: its path, its SHA-256 (lowercase hex) and its size in bytes. |
left_out |
Media the exporting computer couldn't include: what used it, the file's name, and why (missing, too_large (over 2 GB), unreadable). |
folders |
Folders a source plays from (a playlist or slideshow folder), keyed by the reference used in the type's JSON. |
Media
Files are stored under media/<first 16 hex digits of the SHA-256>/<file name>, so the same content is stored once however many sources use it and whatever it was called. In the type's JSON, every file path is rewritten to one of:
media/<fingerprint>/<name>: a file in the archive;folders/<n>: a folder described in the manifest'sfolders;missing/<name>: a file that wasn't included (seeleft_out). On import it points at<media folder>/<name>, so putting the file there brings it back.
Shared files never contain paths from the computer that made them. A backup, which you restore on your own next computer, keeps the full path of a file it couldn't include.
Reading rules
A reader must refuse the file, before using anything in it, when:
- any entry's path is absolute, or contains a
..or.part, an empty part, a backslash, a drive letter, a control character, or a name Windows reserves (con,nul,com1…); - an entry is a symbolic link or is encrypted;
- two entries have names that differ only in case;
- an entry is in the archive but not in
contents, or incontentsbut not in the archive; - an entry's size differs from its
contentssize; - the type is unknown, or the format is newer than the reader supports;
- the file is over its type's limits (below);
signature.ed25519is present and doesn't verify.
Every read checks the bytes against the SHA-256 in contents, and stops at the size contents gives, so an entry can never inflate past what the manifest says.
Limits
| Type | Entries | Total unpacked | One entry |
|---|---|---|---|
.velumtheme |
512 | 20 MB | 20 MB |
.velumprofile |
64 | 64 MB | 32 MB |
.velumpreset |
20,000 | 64 GB | 2 GB |
.velumscenes |
100,000 | 256 GB | 2 GB |
.velumbackup |
400,000 | 1 TB | 2 GB |
.velumplugin |
20,000 | 2 GB | 512 MB |
Signature
signature.ed25519 is JSON:
{"key": "<Ed25519 public key, 64 hex digits>", "signature": "<128 hex digits>"}The signature is Ed25519 over the exact bytes of manifest.json. Because the manifest holds the SHA-256 of every other file, one signature covers the whole file. Studio shows whether a file is unsigned, signed by its maker, or signed by the publisher (files listed in the public gallery). Plugins use the same scheme.
Never a secret
Stream keys, tokens, passwords and sign-ins are kept in the computer's keychain and are never written into a Velum file. Destinations are exported without their keys, and addresses lose any user name, password or key in them. After importing, Studio asks you to sign in or paste keys again. Studio also refuses to write an export that would contain any value from its keychain, even one typed into a text layer.
The types in detail
.velumscenes
collection.json is a Studio collection exactly as Studio saves it, with file paths rewritten as above. Importing always creates a new collection: if the name is taken, Studio picks a free one (racing-setup-2). Media goes into the new collection's own media folder or a folder you choose; a Dynamic Source's files go back into its library's folder.
.velumprofile
{
"schema": "velum.profile",
"schema_version": 1,
"canvases": [{"role": "main", "resolution": [2560, 1440], "fps": {"num": 60, "den": 1}}],
"settings": {"canvas/view": "both", "destinations/platforms": "[{\"id\":…,\"name\":\"Twitch\",…}]"},
"layout": {"format": "velum.window-layout", "version": 1, "docks": "…"}
}settings holds Studio's audio, canvas and destination settings, each in the form Studio stores it. Before applying a profile, Studio shows exactly what changes, and keeps the current dock layout as a layout named "Before import".
.velumtheme
The theme, its preview and icon, and optional fonts, pictures and licences. A theme contains no code: any other file is refused. See Sharing a theme.
.velumpreset
{
"schema": "velum.preset",
"schema_version": 1,
"kind": "source",
"name": "Logo",
"root": "<id>",
"item": { "…": "the layer: position, crop, look, framings" },
"sources": [], "scenes": [], "rules": [], "detectors": [],
"refs": {},
"canvas": [1920, 1080]
}kind |
What it carries |
|---|---|
source |
A layer's source with its effects, and the layer itself; anything the source shows (a Mirror's source) comes along |
scene |
A scene with everything it places, nested scenes included |
dynamic |
A Dynamic Source with its library: every item, its rule and its file |
automation |
An automation, its Screen Detect detector if it uses one, and in refs the names of the scenes, layers, effects and framings it acts on |
Dropping a preset adds new copies with new ids, in one step you can undo. Names already used get a number ("Logo 2"). Positions are stored relative to the canvas height, so a preset fits any canvas size.
.velumbackup
backup.json lists the collections (collections/<folder>/collection.json in the archive), the settings, the window layout and saved looks. The archive also holds the themes (themes/…) and stream-info.json. Media is shared across collections and stored once. Restoring never overwrites anything: a collection whose folder name is taken is restored beside it under a free name, and a theme that's already there is kept.
.velumplugin
plugin.json describes the plugin. See Packaging and signing.

