OnSong^® Binder (a.k.a. Your Digital Sheet Music Panic Room)

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. Fancy, right?

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 Crammed in There

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, serialized. Every property OnSong knows about it, in the same shape the OnSong web API uses. It's basically a digital scrapbook.
• 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 holding 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 holding a book of two hundred songs is the same format as one holding a single chart. Consistency! We're so organized.

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. Groundbreaking stuff.

What It's Packin'

• Songs — the chord chart & literally everything attached to it.
• Sets — the songs in their order, with the set's own arrangement. Organized chaos!
• Books — a whole collection. Wow.
• Attachments — PDFs, images, audio, & any other file associated with a song. You can choose to include only the attachments that are actually in use rather than every version ever added. Revolutionary concept, we know.

Binder Or Archive? (The Thrilling Showdown)

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 cool kid on the block. Use it for sharing with newer versions of OnSong — & when you want a file you can open up & actually peek inside like a normal human.

Importin' & Exportin' (The Glamorous Part)

Binders import the way 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 adds that song. Shocking, we know.

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

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 travellin' over the network like a little digital courier pigeon.

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 something needs to read your content & isn't OnSong. No magic, just facts.