The global state of the application.


default_font: Font The default font to be used in Text objects. permalink view source

document: Document The global document root object. permalink view source


setup (initial_paper=None) permalink view source

Initialize the application and set up the global state.


initial_paper (Paper): The paper to use in the document. If None, this defaults to constants.DEFAULT_PAPER_TYPE



This initializes the global Document and a back-end AppInterface instance.

This should be called once at the beginning of every script using brown; calling this multiple times in one script will cause unexpected behavior.

register_font (font_file_path) permalink view source

Register a font file with the application.


font_file_path (str): A path to a font file. Currently only TrueType and OpenType fonts are supported.



If highly consistent typesetting is a concern for your score and you wish to use non-standard fonts (e.g. Times New Roman), it is recommended that you distribute your fonts with brown scripts whenever possible, and call this immediately after brown.setup().

If successful, this makes the font available for use in Font objects, to be referenced by the family name embedded in the font file.

register_music_font (font_name, font_file_path, metadata_path) permalink view source

Register a music font with the application.


font_name (str): The canonical name of this font. This is used as a dict key for the font metadata in brown.registered_music_fonts.

font_file_path (str): A path to a font file.

metadata_path (str): A path to a SMuFL metadata JSON file for this font. The standard SMuFL format for this file name will be {lowercase_font_name}_metadata.json.



show () permalink view source

Show a preview of the score in a GUI window.



The current implementation is pretty limited in features, but this could/should be extended in the future once the API/interface/Qt bindings are more stable.

render_pdf (path) permalink view source

Render the score as a pdf.


path (str): The output score path. If a relative path is provided, it will be relative to the current working directory.

render_image (rect, image_path, dpi=600, quality=-1, bg_color=None, autocrop=False) permalink view source

Render a section of the document to an image.


rect (Rect or arg tuple): The part of the document to render, in document coordinates.

image_path (str): The path to the output image. This must be a valid path relative to the current working directory.

dpi (int): The pixels per inch of the rendered image.

quality (int): The quality of the output image for compressed image formats. Must be either -1 (default compression) or between 0 (most compressed) and 100 (least compressed).

bg_color (Color or arg tuple): The background color for the image. Defaults to solid white. Use a Color with alpha=0 for a fully transparent background.

autocrop (bool): Whether or not to crop the output image to tightly fit the contents of the frame. If true, the image will be cropped such that all 4 edges have at least one pixel not of bg_color.



The following file extensions are supported:

  • .bmp
  • .jpg
  • .png
  • .pbm
  • .pgm
  • .ppm
  • .xbm
  • .xpm