OnSong^® Binder

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

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

What's Inside

A binder is a ZIP archive. Unzip one and 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.
• 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.
• Folders for its children, named after what they are — songs, attachments — each holding more folders of exactly the same shape.

That structure repeats all the way down: a set contains songs, a song contains attachments, and 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.

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 and one that points into a folder next to it.

What It Carries

• Songs — the chord chart and everything attached to it.
• Sets — the songs in their order, with the set's own arrangement.
• Books — a whole collection.
• Attachments — PDFs, images, audio, and 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.

Binder Or Archive?

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, and is what to use for compatibility with earlier versions of OnSong.
• OnSong^® Binder is the current one. Use it for sharing with newer versions of OnSong — and when you want a file you can open up and look inside.

Importing And Exporting

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

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

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.

Because a binder is a ZIP of plain JSON and 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 and isn't OnSong.