tessl/pypi-verovio
A fast, portable and lightweight library for engraving Music Encoding Initiative (MEI) music scores into SVG
loading-config.mddocs/
Loading and Configuration
This document covers loading music notation files, managing resources, configuring rendering options, and validating input data.
Capabilities
Toolkit Initialization
Create and initialize toolkit instances for rendering music notation.
class toolkit:
"""
Main class for loading, rendering, and manipulating music notation.
"""
def __init__(self, initFont: bool = True) -> None:
"""
Create a new toolkit instance.
Args:
initFont: If True (default), initialize fonts and set default resource path.
If False, setResourcePath() must be called explicitly before use.
"""File and Data Loading
Load music notation from files or string data in various formats.
class toolkit:
def loadFile(self, filename: str) -> bool:
"""
Load a music notation file from the file system.
Supports MEI, MusicXML, Humdrum, PAE, ABC, and other formats.
File format is auto-detected. Handles UTF-16 conversion and
MusicXML compressed files automatically.
Args:
filename: Path to the file to load
Returns:
True if the file was successfully loaded, False otherwise
"""
def loadData(self, data: str) -> bool:
"""
Load music notation from a string.
File format is auto-detected by default, or can be specified
using setInputFrom() before calling this method.
Args:
data: Music notation data as a string (MEI, MusicXML, etc.)
Returns:
True if the data was successfully loaded, False otherwise
"""
def loadZipDataBase64(self, data: str) -> bool:
"""
Load a MusicXML compressed file from a base64 encoded string.
Args:
data: ZIP file encoded as base64 string
Returns:
True if the data was successfully loaded, False otherwise
"""
def loadZipDataBuffer(self, data: bytes, length: int) -> bool:
"""
Load a MusicXML compressed file from a byte buffer.
Args:
data: ZIP file as bytes
length: Size of the data buffer
Returns:
True if the data was successfully loaded, False otherwise
"""Input Validation
Validate Plaine & Easie Code before loading.
class toolkit:
def validatePAE(self, data: str | dict) -> dict:
"""
Validate Plaine & Easie code.
Returns errors in PAE pedantic mode. No data remains loaded
after validation. When reading succeeds, validation is grouped
by input keys.
Args:
data: PAE data as string or dict with PAE keys
Returns:
Dictionary with validation warnings or errors
"""
def validatePAEFile(self, filename: str) -> dict:
"""
Validate Plaine & Easie code from a file.
Args:
filename: Path to file containing PAE data
Returns:
Dictionary with validation warnings or errors
"""
def getPageCount(self) -> int:
"""
Return the number of pages in the loaded document.
The number of pages depends on page size and whether
encoded layout was taken into account.
Returns:
Number of pages in the loaded document
"""Options Management
Configure rendering options including page dimensions, scale, spacing, and appearance.
class toolkit:
def getOptions(self) -> dict:
"""
Get all current option values.
Returns:
Dictionary with all current option values
"""
def getDefaultOptions(self) -> dict:
"""
Get all default option values.
Returns:
Dictionary with all default option values
"""
def getAvailableOptions(self) -> dict:
"""
Get all available options grouped by category.
For each option, returns the type, default value, and
minimum and maximum values (when available).
Returns:
Dictionary with all available options and their metadata
"""
def setOptions(self, json_options: dict) -> bool:
"""
Set option values.
Common options include:
- pageHeight: Page height in MEI units
- pageWidth: Page width in MEI units
- scale: Scaling factor (percentage)
- adjustPageHeight: Auto-adjust page height
- breaks: Break handling ('auto', 'line', 'encoded', 'none')
- spacingStaff: Staff spacing multiplier
- header: Header display ('auto', 'encoded', 'none')
- footer: Footer display ('auto', 'encoded', 'none')
Args:
json_options: Dictionary with option names and values
Returns:
True if options were successfully set, False otherwise
"""
def resetOptions(self) -> None:
"""
Reset all options to their default values.
"""
def getOptionUsageString(self) -> str:
"""
Get formatted option usage information for all categories.
Returns:
String with usage information for all options
"""
def setScale(self, scale: int) -> bool:
"""
Set the scale option.
Args:
scale: Scale value as integer (percentage)
Returns:
True if successfully set, False otherwise
"""
def getScale(self) -> int:
"""
Get the current scale option.
Returns:
Current scale value as integer
"""Format Control
Set input and output format preferences.
class toolkit:
def setInputFrom(self, format: str) -> bool:
"""
Set the input format.
Overrides auto-detection. Use format constant names
like 'mei', 'musicxml', 'humdrum', 'pae', etc.
Args:
format: Input format as string
Returns:
True if successfully set, False otherwise
"""
def getInputFrom(self) -> int:
"""
Get the current input format setting.
Returns:
Input format enumeration value
"""
def setOutputTo(self, outputTo: str) -> bool:
"""
Set the output format preference.
Args:
outputTo: Output format as string
Returns:
True if successfully set, False otherwise
"""
def getOutputTo(self) -> int:
"""
Get the current output format setting.
Returns:
Output format enumeration value
"""Resource Management
Manage resource paths for fonts and data files.
class toolkit:
def getResourcePath(self) -> str:
"""
Get the resource path for this toolkit instance.
Returns:
Current resource path as string
"""
def setResourcePath(self, path: str) -> None:
"""
Set the resource path for this toolkit instance.
Must be called if the toolkit was initialized with initFont=False,
or to change the resource path.
Args:
path: Path to the resource directory containing fonts and data
"""
def getID(self) -> str:
"""
Get the unique ID of this toolkit instance.
Returns:
Instance ID as string
"""
def getVersion(self) -> str:
"""
Get the Verovio version number.
Returns:
Version string
"""XML ID Management
Control generation of MEI @xml:id attributes.
class toolkit:
def resetXmlIdSeed(self, seed: int) -> None:
"""
Reset the seed for generating MEI @xml:id attribute values.
Passing 0 uses a time-based random seed. This method has no
effect if the --xml-id-checksum option is set.
Args:
seed: Seed value for ID generation (0 for random seed)
"""Logging
Access log output from operations.
class toolkit:
def getLog(self) -> str:
"""
Get the log content from the latest operation.
Returns:
Log content as string
"""Usage Examples
Basic Loading and Configuration
import verovio
# Create toolkit with default initialization
tk = verovio.toolkit()
# Load an MEI file
if tk.loadFile("score.mei"):
print(f"Loaded successfully, {tk.getPageCount()} pages")
else:
print(f"Error loading file: {tk.getLog()}")
# Configure rendering options
options = {
'pageHeight': 2970,
'pageWidth': 2100,
'scale': 40,
'adjustPageHeight': True,
'breaks': 'auto'
}
tk.setOptions(options)Loading from String Data
import verovio
tk = verovio.toolkit()
# Load MEI data from string
mei_data = """<?xml version="1.0" encoding="UTF-8"?>
<mei xmlns="http://www.music-encoding.org/ns/mei">
<!-- MEI content here -->
</mei>"""
if tk.loadData(mei_data):
print("Data loaded successfully")Validating PAE Data
import verovio
tk = verovio.toolkit()
# Validate PAE data before loading
pae_data = "@clef:G-2@key:xFC@time:3/4@data:8ABCDEF"
validation_result = tk.validatePAE(pae_data)
if validation_result.get('errors'):
print(f"Validation errors: {validation_result['errors']}")
else:
print("PAE data is valid")Custom Resource Path
import verovio
# Initialize without default fonts
tk = verovio.toolkit(initFont=False)
# Set custom resource path
tk.setResourcePath("/custom/path/to/verovio/data")
# Now load and render as normal
tk.loadFile("score.mei")Exploring Available Options
import verovio
tk = verovio.toolkit()
# Get all available options
available = tk.getAvailableOptions()
# Print options by category
for category, options in available.items():
print(f"\n{category}:")
for opt_name, opt_info in options.items():
print(f" {opt_name}: {opt_info}")
# Get current values
current = tk.getOptions()
print(f"\nCurrent scale: {current['scale']}")
# Get defaults
defaults = tk.getDefaultOptions()
print(f"Default scale: {defaults['scale']}")Setting Input Format
import verovio
tk = verovio.toolkit()
# Force MusicXML interpretation
tk.setInputFrom('musicxml')
# Load data that might be ambiguous
tk.loadData(xml_string)Install with Tessl CLI
npx tessl i tessl/pypi-verovio