tessl/pypi-verovio

A fast, portable and lightweight library for engraving Music Encoding Initiative (MEI) music scores into SVG

Overview

Eval results

Files

Rendering Capabilities

Name: tessl/pypi-verovio
Author: tessl

This document covers rendering loaded music notation to various output formats including SVG, MIDI, Plaine & Easie Code, timemaps, and expansion maps.

Capabilities

SVG Rendering

Render music notation to scalable vector graphics (SVG) format.

class toolkit:
    def renderData(self, data: str, options: dict) -> str:
        """
        Render the first page of data to SVG.

        This is a convenience wrapper that sets options, loads data,
        and renders the first page in one call. Returns empty string
        if options cannot be set or data cannot be loaded.

        Args:
            data: Music notation data as string (MEI, MusicXML, etc.)
            options: Dictionary with rendering options

        Returns:
            SVG for the first page as string, or empty string on error
        """

    def renderToSVG(self, pageNo: int = 1, xmlDeclaration: bool = False) -> str:
        """
        Render a page to SVG.

        Args:
            pageNo: Page number to render (1-based), defaults to 1
            xmlDeclaration: Include XML declaration in SVG output, defaults to False

        Returns:
            SVG page as string
        """

    def renderToSVGFile(self, filename: str, pageNo: int = 1) -> bool:
        """
        Render a page to SVG and save to file.

        Args:
            filename: Output file path
            pageNo: Page number to render (1-based), defaults to 1

        Returns:
            True if file was successfully written, False otherwise
        """

MIDI Rendering

Render music notation to MIDI format for audio playback.

class toolkit:
    def renderToMIDI(self) -> str:
        """
        Render the loaded document to MIDI.

        Returns:
            MIDI file as base64 encoded string
        """

    def renderToMIDIFile(self, filename: str) -> bool:
        """
        Render document to MIDI and save to file.

        Args:
            filename: Output file path

        Returns:
            True if file was successfully written, False otherwise
        """

Plaine & Easie Code Export

Export music notation to Plaine & Easie Code format.

class toolkit:
    def renderToPAE(self) -> str:
        """
        Render document to Plaine & Easie code.

        Only the top staff/layer is exported.

        Returns:
            PAE data as string
        """

    def renderToPAEFile(self, filename: str) -> bool:
        """
        Render document to Plaine & Easie code and save to file.

        Only the top staff/layer is exported.

        Args:
            filename: Output file path

        Returns:
            True if file was successfully written, False otherwise
        """

Timemap Generation

Generate timemaps for synchronizing visual rendering with audio playback.

class toolkit:
    def renderToTimemap(self, options: dict | None = None) -> list:
        """
        Render document to a timemap.

        Timemaps provide temporal information for each musical event,
        enabling synchronization between visual notation and audio playback.

        Args:
            options: Dictionary with timemap options, optional

        Returns:
            Timemap as list of event dictionaries
        """

    def renderToTimemapFile(self, filename: str, options: dict | None = None) -> bool:
        """
        Render document to timemap and save to file.

        Args:
            filename: Output file path
            options: Dictionary with timemap options, optional

        Returns:
            True if file was successfully written, False otherwise
        """

Expansion Map Generation

Generate expansion maps for documents with repeats and other expansions.

class toolkit:
    def renderToExpansionMap(self) -> list:
        """
        Render document's expansion map, if existing.

        Expansion maps show how notated elements map to their
        expanded forms when repeats and other expansions are applied.

        Returns:
            Expansion map as list
        """

    def renderToExpansionMapFile(self, filename: str) -> bool:
        """
        Render document's expansion map and save to file.

        Args:
            filename: Output file path

        Returns:
            True if file was successfully written, False otherwise
        """

Selection

Apply selection to limit what is rendered.

class toolkit:
    def select(self, selection: dict) -> bool:
        """
        Set a selection to be applied to rendering.

        The selection is applied when data is loaded or layout is redone.
        Pass an empty dict to reset/cancel the selection.
        Selection across multiple mdivs is not possible.

        Args:
            selection: Dictionary defining the selection

        Returns:
            True if selection was successfully parsed or reset, False otherwise
        """

Usage Examples

Basic SVG Rendering

import verovio

tk = verovio.toolkit()

# Load file and render all pages
tk.loadFile("score.mei")
page_count = tk.getPageCount()

for page_num in range(1, page_count + 1):
    svg = tk.renderToSVG(pageNo=page_num)
    with open(f"page_{page_num}.svg", "w") as f:
        f.write(svg)

Quick Render with Options

import verovio

tk = verovio.toolkit()

# Render data with custom options in one call
options = {
    'pageHeight': 2970,
    'pageWidth': 2100,
    'scale': 40
}

with open("score.mei", "r") as f:
    mei_data = f.read()

svg = tk.renderData(mei_data, options)
with open("output.svg", "w") as f:
    f.write(svg)

MIDI Export

import verovio
import base64

tk = verovio.toolkit()
tk.loadFile("score.mei")

# Get MIDI as base64 string
midi_base64 = tk.renderToMIDI()

# Decode and save
midi_bytes = base64.b64decode(midi_base64)
with open("output.mid", "wb") as f:
    f.write(midi_bytes)

# Or use the convenience method
tk.renderToMIDIFile("output.mid")

Timemap for Playback Sync

import verovio
import json

tk = verovio.toolkit()
tk.loadFile("score.mei")

# Generate timemap
timemap = tk.renderToTimemap()

# Save for use in playback application
with open("timemap.json", "w") as f:
    json.dump(timemap, f, indent=2)

# Timemap entries contain information like:
# - Element IDs
# - Onset times
# - Offset times
# - Page numbers

Working with Selections

import verovio

tk = verovio.toolkit()
tk.loadFile("score.mei")

# Select specific measures to render
selection = {
    "start": "measure-1",
    "end": "measure-10"
}
tk.select(selection)

# Render only the selected measures
svg = tk.renderToSVG()

# Clear selection
tk.select({})

# Now renders full document
svg_full = tk.renderToSVG()

Multiple Format Export

import verovio

tk = verovio.toolkit()
tk.loadFile("score.mei")

# Export to multiple formats
tk.renderToSVGFile("output.svg", pageNo=1)
tk.renderToMIDIFile("output.mid")
tk.renderToPAEFile("output.pae")
tk.renderToTimemapFile("timemap.json")

# Check for expansion map
expansion_map = tk.renderToExpansionMap()
if expansion_map:
    tk.renderToExpansionMapFile("expansion.json")
    print("Document has expansions (repeats, etc.)")

High-Resolution SVG

import verovio

tk = verovio.toolkit()

# Set high scale for print quality
options = {
    'scale': 100,  # High resolution
    'pageHeight': 2970,
    'pageWidth': 2100
}
tk.setOptions(options)

tk.loadFile("score.mei")
tk.renderToSVGFile("high_res_output.svg")

SVG with XML Declaration

import verovio

tk = verovio.toolkit()
tk.loadFile("score.mei")

# Get SVG with XML declaration for standalone file
svg_with_declaration = tk.renderToSVG(pageNo=1, xmlDeclaration=True)

# Suitable for direct file output
with open("standalone.svg", "w") as f:
    f.write(svg_with_declaration)

Custom Timemap Options

import verovio

tk = verovio.toolkit()
tk.loadFile("score.mei")

# Generate timemap with custom options
timemap_options = {
    'includeRests': True,
    'includeMeasures': True
}
timemap = tk.renderToTimemap(options=timemap_options)

# Process timemap for interactive playback
for event in timemap:
    element_id = event.get('id')
    onset_time = event.get('on')
    offset_time = event.get('off')
    print(f"Element {element_id}: {onset_time}ms - {offset_time}ms")

Install with Tessl CLI