Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Lineage and albums

Suno lets you build on a clip: remix it, extend it, or edit it. Each new clip records the one it came from, which forms a lineage that runs back to an original root clip. rs-suno follows that lineage to group related clips into albums and to lay out files predictably.

Root resolution

For every clip, rs-suno walks the lineage back to its root ancestor, the original clip a family of remixes and edits grew from. It fills gaps by looking up parents directly, and it keeps a durable archive of what it has resolved (see the lineage store below), so ancestry stays stable across runs even after Suno purges an intermediate clip.

Albums from lineage

Clips that share a root are grouped into one lineage album. The album title is chosen simply:

  • If the root ancestor is a real, distinct clip, the album takes the root clip’s title.
  • Otherwise (a clip that is its own root), the album takes the clip’s own title.

So a song and all its remixes and extensions land in one album named after the original, while a standalone clip sits in an album of its own name.

Overriding an album name

When a derived title is undesirable, you can rename an album by its lineage root id in the [accounts.<label>.albums] config table (see album name overrides). The preferred name replaces the derived one everywhere the album appears: the folder path, the ALBUM tag, the change hash, and album art. On the next sync the existing folder is moved to the new name and the emptied old directory pruned, with no re-download and deletion safety intact.

Track numbers

Within an album, tracks are numbered by when each version was made: the earliest created_at is track 1, the next track 2, and so on. The number is written to the audio tags (TRACKNUMBER and TRACKTOTAL for FLAC, the equivalent TRCK/trkn for MP3, WAV, and ALAC), so a player lists the album in creation order, and it also prefixes the file name (07 - …) via the default template’s {track2} placeholder.

TRACKTOTAL is the number of that album’s downloaded tracks. A single-track album is numbered 1 of 1 by default; set number_singletons = false to leave lone songs unnumbered (and unprefixed).

Because the number is part of the file name, a newly generated sibling can renumber an album and rename every file in it. That is harmless on disk, and the .m3u8 sidecars are rewritten to match, but it can confuse a media server that tracks playlist membership by file. See media servers for a stable-naming recipe.

Setting a lead track

Sometimes the version you think of as “song 1” was not made first, for example when you edited the main version after generating a batch of remixes. Flag it as the album’s lead and it is promoted to track 1, with the rest shifting down while keeping their relative order:

[accounts.me]
lead_tracks = [
  "b320f4cf",   # the 8-char code from a file name, or the full clip id
]

Each entry is a clip id or a unique prefix of one (such as the [b320f4cf] code in a file name); the album is found from that clip’s lineage, so you never name the album here. There is one lead per album, and an entry that matches no downloaded clip, or more than one, is reported and ignored.

File and folder layout

Files are named deterministically from the clip and its lineage:

{creator}/{album}/{track2} - {creator}-{title} [{id8}]
  • {creator} is your display name (falling back to your handle).
  • {album} is the lineage album title described above.
  • {track} is the album track number (for example 7); {track2} is the same number zero-padded to two digits (07). An unnumbered track renders neither, and its trailing separator is dropped so no orphan - is left behind.
  • {title} is the clip’s title.
  • {id8} is the first eight characters of the clip id ({id} is the full id, {root_id8} the first eight of the lineage root, {handle} your handle).

For example, a FLAC download might land at:

alice/Neon Horizon/03 - alice-Neon Horizon (Remix) [8d9e0f1a].flac

Names are made safe for the filesystem. Unicode is preserved where it is valid in a path; awkward characters are replaced, and over-long components are shortened.

Collision safety

Two protections make the layout collision-free:

  • Same-title clips never clash. The [{id8}] suffix in every file name keeps two clips with the same title in separate files.
  • Distinct roots never share a folder. If two different roots happen to have the same album title, the folders are separated by a short root-id suffix, so one album can never absorb another’s tracks.

Lineage tags

The lineage is also written into each file’s metadata, including the parent clip, the root clip, and a compact summary of the chain. See Artwork and animated covers for the full list of tags.

The lineage store

Resolved ancestry is saved beside your library in .suno-lineage.json. It is an append-durable archive: once an ancestor is known, it is kept, even if the clip is later trashed or removed upstream. This keeps album grouping stable over time. Because it cannot be rebuilt once Suno purges old clips, a corrupt store stops the run rather than being silently discarded.