OnSong^® Binder

Th' OnSong^® Binder file format be how OnSong moves a song, a set, or a whole book between libraries, savvy? Like th' OnSong^® Archive it carries everythin' needed t' rebuild th' content somewhere else — th' song text, attachments, styles, settin's, transposition and annotations — but where an archive be a single opaque blob, a binder be a folder o' ordinary files. That makes it readable, inspectable, and able t' carry th' media a song depends on alongside th' song itself in a platform-agnostic manner, Arrr!

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

What be Inside

A binder be a ZIP archive, matey. Unzip one and ye'll find a folder named after th' item's identifier, containin':

• manifest.json — th' item itself, serialized. Every property OnSong knows about it, in th' same shape th' 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 be just that PDF or MP3.
• Folders fer its children, named after what they be — songs, attachments — each holdin' more folders o' exactly th' same shape.

That structure repeats all th' way down: a set contains songs, a song contains attachments, and each be a folder with its own manifest beside its own files. A binder holdin' a book o' two hundred songs be th' same format as one holdin' a single chart.

Inside a manifest, references t' children be marked with a $binder. prefix, so a reader can tell th' difference between a value that belongs t' th' item and one that points into a folder next t' it.

What It Carries

• Songs — th' chord chart and everythin' attached t' it.
• Sets — th' songs in their order, with th' set's own arrangement.
• Books — a whole collection.
• Attachments — PDFs, images, audio, and any other file associated with a song. Ye can choose t' include only th' attachments that be actually in use rather than every version ever added.

Binder Or Archive?

Both round-trip a library's content faithfully, so th' choice be about what ye need from th' file, Blimey!

• OnSong^® Archive be th' older format, and be what t' use fer compatibility with earlier versions o' OnSong.
• OnSong^® Binder be th' current one. Use it fer sharin' with newer versions o' OnSong — and when ye want a file ye can open up and look inside.

Importin' And Exportin'

Binders import th' way any other file does: open one from Files, Mail, AirDrop, or a cloud service and choose OnSong. Importin' a binder that holds a set recreates th' set and every song in it; importin' one that holds a single song adds that song, savvy?

T' create one, use Share and pick OnSong Binder as th' format.

Binders be also what OnSong Connect sends between devices when one device asks another fer a song or a set, so th' same format that lives in yer Files app be th' one travelin' over th' network, Arrr!

Because a binder be a ZIP o' plain JSON and ordinary media files, it be th' right format t' reach fer when ye need t' see what OnSong actually stored — or when somethin' needs t' read yer content and ain't OnSong.