The .vybe file format, version 1

A .vybe file holds one song and everything that belongs with it: metadata, cover art, lyrics, credits, a waveform, the full song in one or more codecs and short preview clips. It is one small file that any app can read with a few lines of code.

This document is the full specification. The reference reader and writer is src/vybe.js in this kit (MIT license). Home page: https://vybemusic.com/open/

1. Layout

A file is a fixed size header, an index with one entry per chunk, then the chunk bytes.

Index entry (28 bytes):

Rules for the chunk area:

• Chunks have no header of their own. The index is the only description.
• Each chunk starts on a 4 byte boundary. Gaps between chunks are zero bytes.
• META is always the first chunk in the index and the first in the file.
• Writers order the other chunks small first: PEAK, ARTW, POPS, PAAC, PMP3, AOPS, AAAC, AMP3, then unknown types, then SIGN last. Readers must not depend on the order (except that META is first).
• A chunk type appears at most once. If a reader finds a type twice, it uses the first entry.
• Offsets and lengths are u64. Readers in languages without 64 bit integers (JavaScript) may refuse values above 2^53.

2. Chunk types

Every chunk except META is optional. A valid file has at least one audio chunk (AOPS, AAAC or AMP3), but readers should cope with files that have none (they show metadata only).

The SIGN chunk

SIGN is written only by the VYBE server when a song is published through VYBE. Its content is not part of this specification and can change at any time. Readers treat it as opaque bytes: keep it when copying a file, never create one, and do not try to interpret it. File flag bit0 is set when the file has a SIGN chunk. A file without SIGN is still a complete, valid .vybe file. Editing any other chunk of a signed file makes the signature invalid, so tools that change a signed file should drop SIGN and clear bit0.

3. META

META is a JSON object. Writers include every key below; values are null when unknown. Readers must ignore keys they do not know.

{
  "format": "vybe", "v": 1,
  "title": "Neon Tide",
  "artist": {"name": "Ayo Lumen", "slug": "ayo-lumen"},
  "album": "Night Drive", "track_no": 3, "disc_no": 1,
  "duration": 215.42, "sample_rate": 44100, "channels": 2,
  "bpm": 122, "bpm_confidence": 0.93,
  "key": "A minor", "camelot": "8A", "key_confidence": 0.81,
  "energy": 0.72, "danceability": 0.88, "valence": 0.31,
  "loudness_lufs": -9.4, "loudness_range": 5.1, "true_peak_db": -0.8,
  "spectral_centroid": 2210.4,
  "vybes": ["latenight", "hype"], "vybe_scores": {"latenight": 0.91, "hype": 0.77},
  "mood": "Late Night", "genre": "House", "language": "en", "explicit": false,
  "lyrics": {"plain": "...", "synced": [{"t": 12.4, "line": "..."}]},
  "beats": {"first": 0.482, "period": 0.4918, "downbeat": 0.482},
  "sections": [{"start": 0, "end": 16.2, "label": "intro", "energy": 0.6}],
  "drop": 63.9,
  "preview": {"start": 47.2, "len": 60},
  "energy_curve": [0.41, 0.44],
  "credits": [{"name": "Ayo Lumen", "role": "producer"}],
  "rights": {"master_owner": null, "publishing_owner": null},
  "license": {"share_partners": true, "commercial": false, "territories": ["WW"]},
  "isrc": "USABC2600001", "upc": null,
  "created": "2026-10-21T09:00:00.000Z",
  "encoder": "VYBE Studio 1",
  "source": {"format": "wav", "sample_rate": 44100, "bits": 24, "bytes": 38211044, "sha256": "..."},
  "fingerprint": "vf1.AbC...",
  "streams": {
    "AOPS": {"codec": "opus", "kbps": 160, "container": "ogg", "sample_rate": 48000, "channels": 2, "pre_skip": 312},
    "POPS": {"codec": "opus", "kbps": 160, "container": "ogg", "preview": true, "start": 47.2, "len": 60}
  }
}

Fields

VYBE ids:

4. Song information (schema 1.1)

Files made with version 1.1 of the kit, and by VYBE Studio, carry the full song information: every artist and what they did, the release, the rights lines and the lyrics with their parts. These fields live in META like all the others, so the file format version stays 1. A file that has them says "schema": "1.1".

Old files keep working. Files from before 1.1 have no schema key (read it as "1.0"), only artist, maybe credits and lyrics.plain. Readers must handle both. The easy way is VybeInfo.read(meta) from src/vybe-info.js, or file.info() from src/vybe.js: both give the same shape for any file, old or new. Writers of schema 1.1 still write artist (see below) so that older readers show the right name.

Example

{
  "format": "vybe", "v": 1, "schema": "1.1",
  "title": "Midnight Drive", "version": "Radio Edit",
  "artists": [
    {"name": "Nia Vale", "role": "main", "slug": "nia-vale"},
    {"name": "Kai Moro", "role": "main", "slug": "kai-moro"},
    {"name": "Juno", "role": "featured", "slug": "juno"}
  ],
  "display_artist": "Nia Vale & Kai Moro feat. Juno",
  "artist": {"name": "Nia Vale & Kai Moro feat. Juno", "slug": "nia-vale"},
  "credits": [
    {"name": "Nia Vale", "role": "lyricist", "role_label": "Lyricist"},
    {"name": "Sam Ortiz", "role": "producer", "role_label": "Producer"},
    {"name": "Ivy Chen", "role": "mastering_engineer", "role_label": "Mastering engineer"},
    {"name": "Omar Diaz", "role": "guitar", "role_label": "Guitar"}
  ],
  "people": {
    "main_artists": ["Nia Vale", "Kai Moro"], "featured_artists": ["Juno"],
    "lyricists": ["Nia Vale"], "composers": [], "singers": [],
    "producers": ["Sam Ortiz"], "engineers": ["Ivy Chen"]
  },
  "album": "Night Roads", "album_artist": null,
  "release": {
    "title": "Night Roads", "type": "album", "date": "2025-06-13", "year": 2025, "original_year": null,
    "track_no": 2, "track_total": 10, "disc_no": 1, "disc_total": 1,
    "label": "Moonlit Records", "upc": "0123456789012", "catalog_no": "MLR-022"
  },
  "label": "Moonlit Records", "publisher": null, "year": 2025,
  "copyright": {"c": "2025 Nia Vale", "p": "2025 Moonlit Records"},
  "isrc": "USABC2512345", "iswc": null, "upc": "0123456789012",
  "genre": "R&B", "subgenres": ["Alternative R&B"], "language": "en", "explicit": false,
  "comment": null, "recorded": null, "tags": [],
  "declared": {"bpm": 118, "key": "A major"},
  "lyrics": {
    "plain": "yeah yeah\n\nCity lights are calling out my name\n...",
    "synced": [{"t": 12.4, "line": "City lights are calling out my name", "section": "Verse 1"}],
    "sections": [
      {"type": "intro", "label": "Intro", "n": null, "performer": null, "start": 1.2, "end": 12.4, "lines": ["yeah yeah"], "inferred": false},
      {"type": "verse", "label": "Verse 1", "n": 1, "performer": "Nia", "start": 12.4, "end": 30.1, "lines": ["City lights are calling out my name", "..."], "inferred": false},
      {"type": "hook", "label": "Hook", "n": null, "performer": null, "start": 30.1, "end": 45.8, "lines": ["We ride we ride into the night", "..."], "inferred": false}
    ],
    "structure": ["Intro", "Verse 1", "Hook"],
    "language": "en",
    "writers": ["Nia Vale"]
  },
  "links": {}
}

Fields

lyrics in schema 1.1:

The sections key at the top level of META (from the audio analysis, with intro, verse, chorus, drop and so on, measured from the sound) is a different thing and stays as it was.

Credit roles

Writers map free text roles onto these ids ("Produced by", "Prod.", "Beat maker" become producer; "Mixed by" becomes mixing_engineer, and so on).

Lyric sections

Artists say hook, so the chorus is called hook. Markers like [Chorus], (Pre-Chorus), Refrain:, [Hook x2], {Bridge} or **Drop** are all read.

Lyrics text with markers

Tools that let people edit lyrics use one plain text form: each part starts with its label in square brackets on its own line, with an optional performer.

[Intro]
yeah yeah

[Verse 1: Nia]
City lights are calling out my name
Every road is running through the rain

[Pre Hook]
Hold on hold on

[Hook]
We ride we ride into the night

VybeInfo.parseLyrics(text) turns this into sections, and VybeInfo.lyricsText(sections) turns sections back into this text. When the text has no markers, VybeInfo.inferSections(text) finds the parts: the stanza that repeats most is the hook, a different repeated stanza that always comes right before it is the pre hook, and a short first or last stanza is the intro or outro.

Where writers find the information

The converter in this kit (VybeInfo.capture) reads, in this order:

• every tag in the source file: ID3 (MP3, WAV, AIFF) including TXXX user frames, TIPL and TMCL credit lists and SYLT timed lyrics; Vorbis comments (FLAC, Ogg), where several ARTIST values mean several artists; MP4 atoms (M4A) including freeform ---- atoms; WAV LIST/INFO;
• the file name, for example 03 - Artist - Title (feat. X).wav;
• the title itself: "(feat. X)", "[Prod. Y]", "(Radio Edit)" and "(Explicit)" are moved to the right fields;
• a .lrc file (timed lyrics) and a .txt file (lyrics) with the same name as the song, and cover.jpg or folder.jpg in the same folder;
• the audio analysis for BPM, key and VYBEs. When the tags say a different BPM or key, the measured value is kept, the tag value goes to declared, and the converter shows a check.

5. Picking a stream

A file can carry the same song in up to three codecs. Readers pick the first one they can play, in this order:

1. Opus (AOPS, preview POPS): smallest for the same quality. Plays in Chrome, Edge, Firefox, Android and recent Safari.
2. AAC (AAAC, preview PAAC): for iOS AVPlayer, older Safari and hardware players.
3. MP3 (AMP3, preview PMP3): plays everywhere.

In a browser, test Opus with audio.canPlayType('audio/ogg; codecs="opus"'). WebM Opus support alone is not enough. Vybe.canPlay(codec) does this for you, and file.audio() returns the best playable stream.

Previews: when a preview would cover 80% or more of the song, writers skip the preview chunks. Readers then play the full stream from meta.preview.start for meta.preview.len seconds (the SDK returns fullStream: true).

MIME types for the stream bytes:

6. Reading only what you need (HTTP Range)

The whole index sits in the first 12 + 28 x N bytes. The first 1024 bytes always hold the index of a file with up to 36 chunks, and usually META too. A player that wants a preview card does not need to download the song:

1. GET song.vybe with Range: bytes=0-1023. Check the magic and version, read N and the index. If 12 + 28 x N is more than you received, request bytes=0-(12 + 28 x N - 1).
2. Find META in the index. If offset + length is inside the bytes you already have, parse it from there; otherwise request exactly bytes=offset-(offset + length - 1).
3. Request only the chunks you need (for example ARTW, PEAK and POPS), one Range request each. Check each chunk against its CRC32 if integrity matters.

If the server ignores Range and answers 200 with the whole file, use the whole file. Vybe.open(url) in src/vybe.js implements all of this and caches chunks. Servers can also proxy a single stream: remote.range('AOPS') returns {start, end} for one upstream Range request.

7. Writing

• Write META first, then the other chunks, each on a 4 byte boundary with zero padding.
• Compute CRC32 over each chunk's exact bytes.
• Set ARTW flag bit0 when the image is webp.
• Never write a SIGN chunk, and keep file flag bit0 at 0.
• Vybe.pack({meta, chunks}) does all of this.
• To change only the song information of a finished file, rewrite META and copy every other chunk byte for byte: Vybe.withMeta(file, meta) or vybe edit. Drop any SIGN chunk, since it signed the old META.

8. Versioning and compatibility

• New chunk types and new META fields can be added within version 1. Readers must ignore chunk types and META fields they do not know, and tools that copy files should keep unknown chunks.
• A change that would break existing readers (a different header or index layout, or a different meaning for an existing chunk type) bumps the version number. Readers refuse versions they do not support.
• META.schema names the version of the META fields ("1.1" now). It only ever adds fields, so a reader for schema 1.1 reads 1.0 files, and an older reader still finds title, artist and lyrics.plain in 1.1 files.

9. Verifying a file

A file is valid when:

1. It starts with VYBE and its version is supported.
2. The index fits in the file, and every chunk lies inside the file after the index, without overlapping another chunk.
3. The first chunk is META and it is a UTF-8 JSON object.
4. Every chunk matches its CRC32.
5. File flag bit0 is set exactly when there is a SIGN chunk.

vybe verify file.vybe from this kit checks all of these and exits with code 1 when the file is not valid.