neoscore.core.neoscore

neoscore.core.neoscore.default_font: Font

The default font to be used in Text objects.

neoscore.core.neoscore.document: Document

The root document object.

neoscore.core.neoscore.registered_music_fonts: Dict[str, dict] = {}

A map from registered music font names to SMuFL metadata

neoscore.core.neoscore.registered_font_family_names: Set[str] = {}

A set of family names of all registered fonts, including music fonts

neoscore.core.neoscore.background_brush = <neoscore.core.brush.Brush object>

The brush used to draw the scene background.

Defaults to solid white. Set this using set_background_brush.

neoscore.core.neoscore.app_interface: AppInterface

The underlying application interface.

You generally shouldn’t directly interact with this.

neoscore.core.neoscore.setup(paper: Paper = A4)[source]

Initialize the application and set up the global state.

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

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

Parameters

paper – The paper to use in the document.

neoscore.core.neoscore.set_default_color(color: ColorDef)[source]

Set the default color used in unspecified pens and brushes.

This only affects objects created after this is called.

neoscore.core.neoscore.set_background_brush(brush: BrushDef)[source]

Set the brush used to paint the scene background.

See background_brush.

neoscore.core.neoscore.register_font(font_file_path: str | pathlib.Path) → List[str][source]

Register a font file with the application.

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

Parameters

font_file_path – A path to a font file. Only TrueType and OpenType fonts are supported.

Returns

A list of family names registered. Typically, this will have length 1.

Raises

FontRegistrationError – If the font could not be loaded. Typically, this is because the given path does not lead to a valid font file.

neoscore.core.neoscore.register_music_font(font_file_path: str | pathlib.Path, metadata_path: str | pathlib.Path)[source]

Register a music font with the application.

Parameters

  • font_file_path – A path to a font file.

  • metadata_path – 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.

Returns

A list of family names registered. Typically, this will have length 1.

Raises

FontRegistrationError – If the font could not be loaded. Typically, this is because the given path does not lead to a valid font file.

class neoscore.core.neoscore.RefreshFuncResult[source]

Bases: object

Results passed back to the neoscore runtime from refresh functions.

scene_render_needed: bool = True

If True, neoscore will clear the scene and re-render it.

Refresh functions can set this to false to tell neoscore that no changes to the scene were made during the refresh, and so re-rendering is not necessary. This is a helpful optimization in situations where the scene does not change in every frame.

__init__(scene_render_needed: bool = True) → None
neoscore.core.neoscore.RefreshFunc

A user-providable function for updating the scene every frame(ish).

The function should accept one argument - the current time in seconds.

Refresh functions can modify the scene, create new objects, and remove them, though not all objects respond well to mutability.

The function may optionally return a RefreshFuncResult to pass information back to the neoscore runtime. If this is omitted, a default RefreshFuncResult is automatically returned.

alias of Callable[[float], Optional[RefreshFuncResult]]

neoscore.core.neoscore.show(refresh_func: Optional[RefreshFunc] = None, display_page_geometry=True, auto_viewport_interaction_enabled=True, min_window_size: Optional[Tuple[int, int]] = None, max_window_size: Optional[Tuple[int, int]] = None, fullscreen: bool = False)[source]

Display the score in an interactive GUI window.

Parameters

  • refresh_func – A scene update function to run on a timer approximating the frame rate. This can also be set with set_refresh_func, which allows customizing the target frame rate.

  • display_page_geometry – Whether to include a preview of page geometry, including a page outline and a dotted outline of the page’s live area inside its margins. This should not be used in combination with a transparent background_brush.

  • auto_viewport_interaction_enabled – Whether mouse and scrollbar viewport interaction is enabled. If false, scrollbars do not appear, mousewheel zooming is disabled, and click-and-drag view movement is disabled.

  • min_window_size – An optional (width, height) minimum window size tuple.

  • max_window_size – An optional (width, height) maximum window size tuple.

  • fullscreen – Whether to show the window in fullscreen mode. This doesn’t mix well with max_window_size.

neoscore.core.neoscore.set_viewport_center_pos(document_pos: PointDef)[source]

Center the interactive viewport at a given document-space position.

If the given position is such that the requested view goes beyond the document’s bounding rect, the actual position used is adjusted to prevent that. This is caused by an internal limitation and may change in the future. To work around this issue, you can expand the document bounding rect by creating an arbitrarily large invisible path like so:

Path.rect((Mm(-1000000), Mm(-1000000)), None, Mm(2000000), Mm(2000000),
      Brush.no_brush(), Pen.no_pen())

This is mostly recommended when not using automatic viewport interaction.

neoscore.core.neoscore.get_viewport_center_pos() → Point[source]

Return the interactive viewport’s center position in document-space.

This value may differ slightly from values set in set_viewport_center_pos.

neoscore.core.neoscore.set_viewport_scale(scale: float)[source]

Set the interactive viewport’s scale (zoom).

Values should be greater than 0, with 1 as the base zoom and larger numbers zooming in.

neoscore.core.neoscore.get_viewport_scale() → float[source]

Return the interactive viewport’s scale (zoom).

This value is always greater than 0, with 1 as the base zoom and larger numbers zooming in.

This value may differ slightly from values set in set_viewport_scale.

neoscore.core.neoscore.set_viewport_rotation(rotation: float)[source]

Set the interactive viewport’s rotation angle in degrees.

The viewport is rotated about its center.

neoscore.core.neoscore.get_viewport_rotation() → float[source]

Return the interactive viewport’s rotation angle in degrees.

neoscore.core.neoscore.render_pdf(pdf_path: str | pathlib.Path, dpi: int = 300)[source]

Render the score as a pdf.

Parameters

  • pdf_path – The output pdf path

  • dpi – Resolution to render at

neoscore.core.neoscore.render_image(rect: Optional[RectDef], dest: str | pathlib.Path | bytearray, dpi: int = 300, quality: int = - 1, autocrop: bool = False, preserve_alpha: bool = True, wait: bool = True) → PropagatingThread[source]

Render a section of the document to an image.

The following file extensions are supported:

  • .bmp

  • .jpg

  • .png

  • .pbm

  • .pgm

  • .ppm

  • .xbm

  • .xpm

If wait == False, this renders on the main thread but autocrops and saves the image on a spawned thread which is returned to allow efficient rendering of many images in parallel.

For a transparent background, use set_background_brush to set the background brush to any fully transparent color, for example neoscore.set_background_brush('#00000000'). You’ll also need to use an image format that supports transparency like PNG, and set preserve_alpha=True.

Parameters

  • rect – The part of the document to render, in document coordinates. If None, the entire scene will be rendered.

  • dest – An output file path or a bytearray to save to. If a bytearray is given, the output format will be PNG.

  • dpi – The pixels per inch of the rendered image. quality: The quality of the

  • compressed (output image for) – image formats. Must be either -1 (default compression) or between 0 (most compressed) and 100 (least compressed).

  • autocrop – Whether to crop the output image to tightly fit the contents of the frame.

  • preserve_alpha – Whether to preserve the alpha channel. This should be set false for export formats that don’t support alpha.

  • wait – Whether to block until the image is fully exported.

Raises
neoscore.core.neoscore.render_to_notebook(rect: Optional[RectDef] = None, dpi: int = 300, autocrop: bool = True, preserve_alpha: bool = False)[source]

Render an image to a Jupyter Notebook environment.

This works mostly like render_image, but instead of saving a file it sends the image to the active notebook environment. If there is no active environment, this may error or have no effect. For convenience, some default arguments differ from render_image to align with what you usually want in a notebook.

See the docs for more information.

This functionality is experimental and subject to change.

neoscore.core.neoscore.set_refresh_func(refresh_func: RefreshFunc, target_fps: int = 60)[source]

Update the global scene refresh function.

Parameters

  • refresh_func – The new refresh function

  • target_fps – The requested frame rate to run the function at.

neoscore.core.neoscore.set_mouse_event_handler(handler: Callable[[MouseEvent], None])[source]

Set the global mouse event handler function.

Mouse events are fired on mouse moves and button presses, releases, and double clicks.

Parameters

handler – A callback function which accepts a mouse event. See MouseEvent for what event data is provided.

neoscore.core.neoscore.set_key_event_handler(handler: Callable[[KeyEvent], None])[source]

Set the global key event handler function.

Key events are fired on key presses, releases, and auto-repeats from being held.

Parameters

handler – A callback function which accepts a key event. See KeyEvent for what event data is provided.

neoscore.core.neoscore.shutdown()[source]

Tear down the global state, including the document tree.

After running this, neoscore.setup can be called again to start a new document.