Belle, Bonne, Sage

The “Beautiful, Good, Wise” C++ Vector-Graphics Library for Music Notation

© 2007-2012 William Andrew Burnson


Thank you for trying out Belle, Bonne, Sage—the first C++ vector-graphics library dedicated solely to music notation! This document serves as a roadmap to learning more about what Belle, Bonne, Sage is and how to go about using it.


Thank you for trying out Belle, Bonne, Sage—the first C++ vector-graphics library dedicated solely to music notation! This document serves as a roadmap to learning more about what Belle Bonne is and how to go about using it.

This print-only version does not contain any of the illustrations or hyperlinks found in the HTML version of this document.

Update (January 4, 2012): The library is currently undergoing a massive overhaul and change of license (from LGPL to the more permissive Simplified BSD 2-clause) so many things are no longer in trunk. The original library is still in the tags/0.4 directory though under LGPL. I plan to be adding a basic modern music notation renderer this year with some MusicXML support. Stay tuned!

Quick Starts


Belle, Bonne, Sage is an abstract vector-graphics library which has neither predetermined inputs or outputs. Instead, it bridges some language of input to another language of output. Since music notation lends itself generally to vector-graphics representations, the only requirement for the output is that it be able to accept vector-graphics drawing commands.

Most importantly, Belle, Bonne, Sage does not assume a fixed model of representation. Instead, it provides processes to the engraver that are likely to be useful. For example, the ability to make a quarter note is a generally useful thing to be able to do, thus there is a special function that creates the vector path of a notehead based on the proportions and rotations of an ellipse, the thickness and roundness of its stem, etc. Crucially, the stem is not drawn separately, rather a single path is calculated for the entire graphic entity. This attention to detail provides exceptional results in print and on the screen.

PDF and Onward

The library comes with a powerful and fast PDF reference renderer, built from the ground up and based on the PDF/X specification. The reference engine currently supports the standard vector graphics routines as well as a custom-built font system in which glyph collections are described in an SVG format that is additionally viewable by web browsers. These SVG glyph collections, or vector fonts as they are named in the library, greatly simplify the task of accessing Unicode characters.

Apart from the reference renderer, a user desiring some other output medium simply needs to write a vector-graphics painter that can translate a few vector-graphics operations into the language of the destination medium. There is no requirement that this output be a file or that it have permanence; for example, it could be a display within a music notation editor. At its lowest-levels, the library knows nothing about whether it is drawing to a file or to the screen. The translation from input to output occurs during the process of rendering, not as a separate step. The library uses C++ virtual functions to facilitate this process.

Belle, Bonne, Sage represents the beginning of a second generation of music notation software that is concerned with controlling the quality of the engraved music while simultaneously maintaining a no-assumptions model that provides total flexibility in the underlying representation of the music.


I can think of no better rationale for this project than my experience in creating my first graphic score. Initially, I wondered if it might be possible to distort the output of a commercial music notation editor to such ends, but it quickly became apparent that was needed was something built entirely from scratch with no underlying assumptions. After a summer's worth of work, I had produced a prototype of Belle, Bonne, Sage in order to create the score to my solo piano piece Bike Ride which is shaped literally as a bicycle.

Bike Ride for solo piano. 18 X 32”. © 2007 William Andrew Burnson.

Clearly, this would be impossible to do in any current music notation software, and would be extraordinarily difficult to accomplish manually through the use of a vector-graphics editor. Thus, it is extremely important to create software that allows for new aesthetics to be tried while at the same time increasing the quality and standards of computer-based music notation. These are the two primary goals for the Belle, Bonne, Sage project.

It is also important to recognize that creativity in notation has a long history and can be identifiably traced back to the score to Baude Cordier's Belle, Bonne, Sage from which this project inherits its title. Hopefully, the library will some day be able to typeset this serendipitous blend of music and art as we strive to show that notational creativity is still just as important today as it was seven centuries ago.

Image of the 14th century score to
Baude Cordier's Belle, Bonne, Sage

The Belle, Bonne, Sage library is dedicated to Gardner Read (1913 - 2005) and his critical scholarship in the field of music notation. Read was a composer and the author of at least ten books on musical notation and orchestration.

“But what about...”

Lilypond? Yes, GNU Lilypond is fantastic open-source engraving software, and undoubtedly maintains the highest merit among computer-based engraving software. However, Lilypond suffers intractable disadvantages compared to Belle, Bonne, Sage and commercial music editing software:

  • No graphical interface, nor is there any possibility to fork the project since its source files are essentially declarative programs that generate PostScript files. None of this can happen in real time. User interfaces also need a way to cache object placement information so that the user can edit the score and get instantaneous feedback. Music notation is very much a visual art, and an engraver needs to be able to see the score at all times. The Denemo project is the only current attempt to build a GUI for Lilypond; however, the GUI itself does not use Lilypond. Instead, the software provides a way to enter in music into the Lilypond declarative scripts.
  • The structure of the music representation is fixed—debatable in that Lilypond is built on a pluggable architecture. However, changing a fixed representation is tedious. For example, consider bendable staff lines; that puts a damper on a lot of pre-coded assumptions about note placement, beaming, and text. In such a model, one tries to account for all the possible notations in existence. This approach works for some pieces of music more than others. A better approach makes no assumptions about the types of notation required and brings instead an array of graphical tools to the fore to solve the problems of the individual engraver.
  • The fonts are difficult to change unless you want to recompile the METAFONTs. The procedure is currently undocumented. METAFONT is one of Donald Knuth's creations that was, unfortunately, never widely accepted outside the Linux community. Though its design is superior in many respects (and would be especially useful for music notation symbols), no physical printer will ever have native METAFONT support. The fonts have to be converted to PostScript or TrueType somewhere down the line, so there is little point in jumping over extra hurdles for the same end result.

Lilypond is, however, quite adept at typesetting many types of music and is capable of much more than the commercial music notation editors. Still, it is not an end-all solution to the problems of flexible music notation, which Belle, Bonne, Sage seeks to address.

Using the Library

It is very important to understand first of all that Belle, Bonne, Sage is not a standalone software program or an editor of any kind. It is best thought of as a library of C++ code governing interactions between an engraver (you) and some vector-graphics context (the display, a PDF file, etc.). Some of these interactions have already been defined in examples, but these are only examples, and do not imply any kind of limitation on the notational possibilities. There are a few ways to experiment with the library:

  • Easiest is to try out the online Lune scripting application that allows you to quickly prototype ideas in the Lua programming language.
  • For persons with basic C++ programming experience, you can get the most out of Belle, Bonne, Sage by creating your own applications through adding examples to your SVN checkout or by building the library and linking to it.

Previous Examples

Belle, Bonne, Sage is packaged with several examples that show how the library can be used. You can use these as a starting point for your own applications or utilities. In conjunction with the comprehensive library reference you should be able to navigate through the library effectively. Here is an overview of the examples:

Note: Some of these example are deprecated or are being reworked, but can still be found in the tags/0.4 repository directory

Windowed Examples

The source code to these examples is located in the subfolders of the tags/0.4examples directory. The applications make use of the JUCE library for the graphical user interfaces. JUCE is included with Belle, Bonne, Sage and is automatically linked to in windowed examples. For more information on how to use JUCE see its reference documentation.

choralecomposer contains the source code to the open source version of University of Illinois' Chorale Composer music theory software for four-part music editing, display, and analysis. The version does not include the automatic analysis engine, but can display, edit, playback, and save and open four-part chorales. The proprietary build is currently in beta, and the binaries can be freely downloaded at the project website.

blume is a geometric-series rhythmic accel. and decel. notating utility and the codebase is a pared down version of the interface for Chorale Composer. It would be a useful starting point for creating a new interface in that it can be easily modified to do something entirely else.

Console Examples

lune is a scripting application that binds the C++ Belle, Bonne, Sage device-abstractions into Lua. It is exactly the program behind the online server-side Lune. However, it can also be used offline by passing the name of a .lua file containing a Lune script thereby generating a PDF file of the same name. Several example scripts are located in the res/lune directory and are included with the prebuilt application zips.

flashdemo is an example of the Belle, Bonne, Sage to Flash binding that is possible using Adobe Lab's Alchemy environment and the GNU LLVM compiler. It allows the entire Belle, Bonne, Sage library to run in a Flash environment. The sandbox does not permit access to the operating system outside of Flash, but rather acts as a virtual machine environment in which to run C++ that has been compiled as optimized ActionScript 3.0 bytecode.

flashdemo example could not load. You may need to install Adobe Flash player (or equivalent).

Open Source Commitment

Belle, Bonne, Sage is now developed under the permissive Simplified BSD License (2-clause) in the hopes that such a library may find relevance in academic, open source, and commercial projects.