OnSong^® Binder (aka Your Digital Crutch)

The OnSong^® Binder file format is basically how OnSong moves a song, a set, or like, your whole bleepin' book between libraries. Kind of like the OnSong^® Archive, except it's got ALL the stuff you need to rebuild everything somewhere else — the lyrics, the attachments, the styles, settings, transposition, AND your chicken-scratch annotations — but here's the thing: while an archive is just one big mystery blob, a binder's actually a folder of normal files. Which means you can like, actually OPEN it, poke around inside, & carry all the media your song depends on alongside it in a way that works everywhere. Fancy, amirite?

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

What's Actually In There

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

• manifest.json — the actual item, all laid out. Like, EVERY property OnSong knows about it, in the exact same shape the OnSong web API uses. No secrets.
• Its file, if it's got one. An attachment keeps its original filename, so a PDF or an MP3 sittin' inside a binder is literally just that PDF or MP3. Revolutionary, we know.
• Folders for its babies, named after what they are — songs, attachments — each one holdin' more folders of the exact same shape.

That structure keeps repeatin' all the way down: a set contains songs, a song contains attachments, & each one's a folder with its own manifest chillin' next to its own files. A binder holdin' a book of two hundred songs? Same format as one holdin' a single chart. ZOMG right?

Inside a manifest, references to baby items get marked with a $binder. prefix, so a reader can tell which values belong to the item & which ones are pointin' into a folder next to it.

What It Actually Carries

• Songs — the chord chart & literally everything tacked onto it.
• Sets — the songs in their order, with the set's own special arrangement.
• Books — your whole dang collection.
• Attachments — PDFs, images, audio, & any other file that got attached to a song. You can pick to include only the attachments you're actually usin' instead of every wonky version you ever threw at it.

Binder Or Archive? The Plot Thickens.

Both of 'em faithfully round-trip your library's content, so it really comes down to what you're tryna get outta the file:

• OnSong^® Archive is the old-school format, & it's what you should use if you wanna play nice with older versions of OnSong.
• OnSong^® Binder is the new hotness. Use it for sharin' with newer versions of OnSong — & especially when you want a file you can actually crack open & peek inside.

Importin' & Exportin' Like a Boss

Binders import just like any other file: open one from Files, Mail, AirDrop, or whatever cloud service you're into & pick OnSong. Importin' a binder that's holdin' a set? Boom — recreates the set & every song in it. Importin' one with a single song? That song just shows up in your library.

To make one, hit Share & pick OnSong Binder as your format.

Binders are also what OnSong Connect sends between devices when one device is like "hey can I get that song or set?" — so the exact same format chillin' in your Files app is the one travelin' over the network. Plot twist!

Because a binder is literally just a ZIP of plain JSON & ordinary media files, it's the PERFECT format to grab when you actually wanna see what OnSong stored — or when somethin' else needs to read your content & it ain't OnSong.