OnSong^® Bindery of Musical Dreams (aka Your Messy Folder)

The OnSong^® Binder file format is how OnSong yeets a song, a set, or a whole bleepin' book between libraries. Like the OnSong^® Archive it carries literally everything needed to rebuild your stuff somewhere else — the song text, attachments, styles, settings, transposition & annotations — but where an archive is one big mystery blob, a binder is a folder of boring regular files. That makes it readable, inspectable, & able to haul around the media your song depends on alongside the song itself in a platform-agnostic way (fancy!).

The OnSong^® Binder file format has a file extension of either .onsongbinder or .binder, & a MIME type of application/onsong-binder. (Riveting stuff, we know.)

What's Hidin' Inside

A binder is a ZIP archive. Unzip one & you'll find a folder named after the item's identifier, containing:

• manifest.json — the item itself, all serialized & dramatic. Every property OnSong knows about it, in the same shape the OnSong web API uses.
• Its file, if it has one. An attachment keeps its original filename, so a PDF or an MP3 inside a binder is literally just that PDF or MP3.
• Folders for its kids, named after what they are — songs, attachments — each holding more folders of exactly the same boring shape.

That structure repeats all the way down: a set contains songs, a song contains attachments, & each is a folder with its own manifest chillin' next to its own files. A binder holding a book of two hundred songs looks exactly the same as one holding a single chart. (Plot twist!)

Inside a manifest, references to kids are marked with a $binder. prefix, so a reader can totally tell the difference between a value that belongs to the item & one that's just pointing into a folder next to it.

What It's Packin'

• Songs — the chord chart & everything stuck to it.
• Sets — the songs in their order, with the set's own arrangement flexin'.
• Books — a whole collection, baby.
• Attachments — PDFs, images, audio, & whatever other file you've decided to tie to a song. You can cherry-pick to include only the attachments actually in use rather than every version ever added (SMART!).

Binder Or Archive?

Both will faithfully round-trip your library's content, so the choice is about what you're actually tryna get from the file:

• OnSong^® Archive is the old-timey format, & is what to use if you're stuck with earlier versions of OnSong & can't move on.
• OnSong^® Binder is the new hotness. Use it for sharing with newer versions of OnSong — & when you want a file you can crack open & actually see inside.

Importin' & Exportin'

Binders import like any other file does: open one from Files, Mail, AirDrop, or a cloud service & choose OnSong. Importing a binder that holds a set recreates the set & every song in it; importing one that holds a single song just adds that song.

To create one, use Share & pick OnSong Binder as the format.

Binders are also what OnSong Connect sends between devices when one device is like "hey gimme that song or set" — so the same format chillin' in your Files app is the one travelin' over the network.

Because a binder is a ZIP of plain JSON & ordinary media files, it's the right format to grab when you need to see what OnSong actually stored — or when something that ain't OnSong needs to read your content.