OnSong^® Binder (AKA Your Digital Sheet Music Pile)

The OnSong^® Binder file format is how OnSong yeetus a song, a set, or a whole book between libraries. Like the OnSong^® Archive it carries literally everything needed to rebuild the content somewhere else — the song text, attachments, styles, settings, transposition & annotations — but where an archive is a single opaque blob, a binder is a folder of ordinary files. That makes it readable, inspectable, & able to carry the media a song depends on alongside the song itself in a platform-agnostic manner. Srsly, it's actually useful.

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

What's Lurkin' Inside

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

• manifest.json — the item itself, serialized. Every property OnSong knows about it, in the same shape the OnSong web API uses. (We had to make it sound fancy or you'd think we just saved a bunch of text files. Spoiler: we kinda did.)
• Its file, if it has one. An attachment keeps its original filename, so a PDF or an MP3 inside a binder is just that PDF or MP3. Mind. Blown.
• Folders for its children, named after what they are — songs, attachments — each holdin' more folders of exactly the same shape. It's folders all the way down, baby.

That structure repeats all the way down: a set contains songs, a song contains attachments, & each is a folder with its own manifest beside its own files. A binder holdin' a book of two hundred songs is the same format as one holdin' a single chart. We're nothin' if not consistent.

Inside a manifest, references to children are marked with a $binder. prefix, so a reader can tell the difference between a value that belongs to the item & one that points into a folder next to it. Fancy, right?

What It Hauls Around

• Songs — the chord chart & literally everything stapled to it.
• Sets — the songs in their order, with the set's own arrangement. (We organized it for you. You're welcome.)
• Books — a whole collection. The whole shebang.
• Attachments — PDFs, images, audio, & any other file you threw at a song. You can choose to include only the attachments that are actually in use rather than every version ever added. (That's called bein' smart about storage.)

Binder Or Archive? The Eternal Question.

Both round-trip a library's content faithfully, so the choice is about what you need from the file:

• OnSong^® Archive is the older format, & is what to use if you're stuck in the past with earlier versions of OnSong. No judgment.
• OnSong^® Binder is the current one. Use it for sharin' with newer versions of OnSong — & when you want a file you can actually open up & peek inside like some kinda detective.

Importin' & Exportin' (The Exciting Part)

Binders import the way any other file does: open one from Files, Mail, AirDrop, or a cloud service & choose OnSong. Importin' a binder that holds a set recreates the set & every song in it; importin' one that holds a single song adds that song. Revolutionary stuff, we know.

To create one, use Share & pick OnSong Binder as the format. That's it. You're done. Go make art or whatever.

Binders are also what OnSong Connect sends between devices when one device asks another for a song or a set, so the same format that lives in your Files app is the one travelin' over the network like some kinda digital sneaker-net.

Because a binder is a ZIP of plain JSON & ordinary media files, it's the right format to reach for when you need to see what OnSong actually stored — or when somethin' needs to read your content & isn't OnSong. (We won't be offended. Probably.)