Developer
Log in

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.

Text
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  optional

The type's JSON is named after the type: collection.json, profile.json, theme.json, preset.json, backup.json, plugin.json.

The manifest

JSONmanifest.json
{
  "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's folders;
  • missing/<name>: a file that wasn't included (see left_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 in contents but not in the archive;
  • an entry's size differs from its contents size;
  • the type is unknown, or the format is newer than the reader supports;
  • the file is over its type's limits (below);
  • signature.ed25519 is 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:

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

JSONprofile.json
{
  "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

JSONpreset.json
{
  "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.

to open · ↑ ↓ to move · Esc to close