Developers
OnSong® Binder File Format
The OnSong® app has been pivotal in helping music teams move away from paper charts and sheet music. In the process, we’ve helped musicians to ditch the binder. No longer are you chained to 3-rings and a hole punch. But much like most technologically advances, this convenience creates another challenge. How can we transfer digital versions of charts, sets, and even books in an easy, cross-platform file format? Enter OnSong® Binder.
What is OnSong® Binder?
OnSong® Binder is a file format that uses the *.onsongbinder file extension and assumes the “application/onsong-binder” MIME type. It’s a simple ZIP file that contains a structured file hierarchy and files that let it transfer many types of information. This information can then be compressed and uncompressed as needed, it’s contents traversed, it’s objects serialized and deserialized, and data file included. Let’s take a look at some ways that an OnSong® Binder file can be constructed.
File System
Everything has to start somewhere so we will start at the root. These are the files or folders that are contained at the root of the data structure. These can be folders or files. Folders can represent individual objects or data, or collections of data. Here’s how to know the difference:
Objects
Objects are stored in a folder with the object’s identifier. In addition, the contents of that folder contain a “manifest.json” file. This is a JSON (Javascript Standard Object Notation) file containing information that can be deserialized into class-based objects on either end.
Collections
Collections contain folders which in turn contain object data by including a “manifest.json” file. When an object has children, those collections are stored in separate folders that reference the name of the collection. For instance, a set would have a “songs” folder which contains multiple folders, each folder representing individual song objects.
Taking that knowledge means that our OnSong® Binder file can contain a single root object, or could contain a collection of objects. For instance, if you are sending a set list of songs, you could include a “manifest.json” file at the root that contains information about the set. You could then include a “songs” folder that references objects contained in the setlist’s songs collection, and then each object would be a folder therein like this…
Manifest File
The manifest.json file is Javascript Standard Object Notation formatted file which allows it to work with a variety of platforms. This contains the information necessary to store data about the object and recreate the object in the implementation. In addition to name/value pairs in the JSON file, these specific binder-specific properties are also available:
$binder.ID
This is the unique identifier of the object and should match the name of the containing folder.
$binder.class
This is the name of the class of the object that has been serialized. Typically the binding process will normalize class names such that they omit any app-specific namespaces or prefixes. For instance, while the OnSong® app uses a class called “OSBook”, the class is simplified to simply “Book”. The classes supported by the OnSong® Binder file format include “Set”, “Book”, “Song”, and “SongAttachment”.
$binder.assembledOn
This is the date/time in IOS-8601 format that the object and the binder was assembled.
$binder.collectionName
Most of the time objects that are serialized can have other children or related objects that are associated to it. For instance, a Set has songs that must be listed in a specific order and a Song has attachments that can contain files used to display the song in different ways. The collection property would be the name of the collection such as “$binder.songs”.
The portion of the property name after the “$binder.” prefix directly relates to the name of the folder in which those objects reside. In this example, the Set folder would contain a “songs” folder that in turn contains individual files for each song. The collection property would contain a reference to related item as well as it’s class as an object with the following properties:
$binder.ref
This it a URI that references the object that includes the name of the container folder and the name of the object’s folder.
$binder.class
This would be the name of the object’s class.
For instance, if the Song object we are referencing has a unique identifier of SONG_IDENTIFIER_1, it would contain the following element in the collection:
{“$binder.ref” : ”songs/SONG_IDENTIFIER_1”, “$binder.class” : ”Song”}
When processing this file, you may opt to remove these keys before using is in our own class files if desired.
Files
The OnSong® Binder file format is designed to also store files. This may be used if you reference a binary or text-based file in your object. For instance, a Song can have multiple attachments which contain files that can be viewed. The OnSong® Binder is assembled to include these files when a specific property containing a reference to the file is encountered.
For instance, the SongAttachment object has a “filename” property that references a file. In addition, this object class points to the file within the main application. The binder assembly process copies the file that is referenced into the binding folder adjacent to the attachment’s “manifest.json” within the Song’s folder. We can then find the file for the individual attachment using the “filename” property.
Examples
While this could be a lot to comprehend, we feel the OnSong® Binder file format is quite simple to implement. The best way to learn about how the OnSong® Binder works is through the includes examples for multiple songs, single songs, a set, and book to see how OnSong handles each. You can uncompress these as ZIP files to inspect the contents:
