Songs — .jsong

Status: draft. Concrete reference content + structural placeholders; flesh out the prose + screenshots when ready.

Purpose

A .jsong file is one song's full cue timeline, saved as plain JSON. Use it to back up a single song, move a song to another machine, send a song to a bandmate, or post a song to a community site. The format is open and documented — any application can read it.

What's in the file

Top-level field	Contains
format	"jsong" — the format identifier.
version	2 — current version. v1 files ("vl3-song-v1") also import.
name, artist, genre, default_tempo, notes	Song metadata.
meta	Provenance block — see below.
cues	Ordered array of cue objects — the timeline.
extensions	Reserved object for third-party data (empty on VL Studio export).

meta block

Field	Use
source	App + version that wrote the file (e.g., "VL Studio 1.0"). Populated by VL Studio on export.
created_at	Timestamp of when the song was originally created in VL Studio.
license	Optional — "original", "public-domain", "cc-by-4.0", etc. Lets sharing platforms filter content by license. Null on VL Studio export; set it manually if you're posting publicly.
author	Optional — who created the song. Useful for attribution.
tags	Optional — free-form tags for browsing.

cues array

Each cue is an object with:

Cue field	Contains
position	Cue order within the song.
label	Section name ("Verse 1", "Chorus").
timestamp_ms	For backing-track-driven auto-advance — milliseconds into the track. Null if foot-advance only.
preset_name, preset_slot	Reference to a preset in the author's library. Used as a lookup hint on import.
actions	Array of automation actions that fire when the cue is entered (CC, key/scale, tempo, TALK, HardTune key source).
lyrics	Brief on-screen hint shown in Performer Mode (a few words).
notes	Performance directions (dynamics, transitions, audience cues).
backing_track_path	Absolute filesystem path to the backing track, or null.
lyric_lines	Optional structured lyric data (multiple lines per cue).

How to export

Songs page → open a song → Export action → choose a save location. VL Studio writes the file with a slugified version of the song name (e.g., Here Comes the Sun.jsong).

How to import

Songs page → Import button → file picker. You can select multiple .jsong files at once. Each file becomes a new song in your library.

Round-trip — preset linkage is not preserved on import

The export captures each cue's preset_name and preset_slot, but the current import path does not read those fields. Imported songs come in with cues that have no preset attached — you'll need to re-link each cue to a preset in your destination library manually.

If the same author imports their own export back into the same library, the same applies: cues lose their preset link on round-trip.

This is on the roadmap to fix. If the round-trip matters to your workflow, keep the songs in a full backup instead — backups preserve full preset references.

Backing-track paths are absolute

The backing_track_path is the absolute path on the source machine. Importing on a different machine where that path doesn't exist means the cue's backing track won't play in Performer Mode. Either:

• Place the backing-track files at the same absolute path on the destination machine.
• Set up a shared folder structure (network share, sync tool) so paths resolve everywhere.
• Re-set each cue's Backing Track via Browse after import.

What round-trips cleanly

• Cue labels, positions, and timestamps
• All automation actions (CC, key/scale, tempo, TALK, HardTune key source)
• Lyrics and performance notes
• Default tempo and song-level metadata

What does not round-trip

• Preset references on cues — preset_name / preset_slot are exported but ignored on import (see warning above).
• Backing-track files — only the path is exported, not the audio. Files need to follow separately or be relinked.
• extensions object — VL Studio reads but doesn't currently store extensions, so any data a third-party app put there is lost on the next export.

Sharing publicly

The format was designed to support community sharing — that's why meta.license and meta.author exist. If you ever post .jsong files to a community site, two responsibilities are yours, not the format's:

1. Lyrics are copyrighted. The lyrics field is intentionally a short on-screen hint (a few words per cue) rather than a full lyric sheet. Treat it as a performer memory aid, not a reproduction. Distributing files containing full copyrighted lyrics is distributing copyrighted material.
2. Set the license. VL Studio doesn't fill meta.license for you on export — populate it before sharing so others know what they can do with the file.

See also

• Songs — authoring the cue timelines that get exported as .jsong.
• Sharing & Files — overview of all interchange formats.
• Full backups — the lossless way to round-trip songs with preset linkage intact.