OnSong^® Binder (aka Your Digital Lifeline)

The OnSong^® Binder file format is how OnSong™ yeets 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. (Translation: it just works, lol.)

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

What's Inside (The Nerdy Bits)

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. Like, every single property OnSong knows about it, in the same shape the OnSong web API uses. It's like reading someone's diary but make it JSON.
• 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. Revolutionary, right?
• 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, bestie.

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 heard of it.

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. (Riveting stuff.)

What It Carries (The Good Stuff™)

• Songs — the chord chart & literally everything glued to it.
• Sets — the songs in their order, with the set's own arrangement. Your precious setlist, safely tucked in.
• Books — a whole collection. The dream, basically.
• Attachments — PDFs, images, audio, & any other file you decided to throw at a song. You can choose to include only the attachments that are actually in use rather than every version ever added. (Aka: spring cleaning for hoarders.)

Binder Or Archive? (The Plot Twist)

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 (jk, totes judging).
• OnSong^® Binder is the current hotness. Use it for sharing with newer versions of OnSong — & when you want a file you can open up & peek inside like the nosy gamer you are.

Importing & Exporting (It's Not Magic, But Close)

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. Boom. Content appears. You're welcome.

To create one, use Share & pick OnSong Binder as the format. See? You got this.

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 travelling over the network. It's the circle of life, but for chords.

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. Transparency? Shocking.