0
# Verovio
1
2
Verovio is a fast, portable and lightweight library for engraving Music Encoding Initiative (MEI) digital scores into SVG images. It provides on-the-fly converters to render multiple music notation formats including Plaine & Easie Code, Humdrum, Musedata, MusicXML, EsAC, and ABC.
3
4
The library is written in C++20 and provides Python bindings via SWIG, enabling professional-quality music notation rendering in Python applications.
5
6
## Package Information
7
8
- **Package Name**: verovio
9
- **Package Type**: pypi
10
- **Language**: Python (C++ core with Python bindings)
11
- **Installation**: `pip install verovio`
12
- **Version**: 5.6.0
13
- **License**: LGPL-3.0-or-later
14
15
## Core Imports
16
17
```python
18
import verovio
19
20
# Create a toolkit instance
21
tk = verovio.toolkit()
22
23
# Access constants
24
mei_format = verovio.MEI
25
log_warning = verovio.LOG_WARNING
26
```
27
28
## Basic Usage
29
30
```python
31
import verovio
32
33
# Create toolkit instance with default font initialization
34
tk = verovio.toolkit()
35
36
# Load MEI file
37
tk.loadFile("score.mei")
38
39
# Get number of pages
40
page_count = tk.getPageCount()
41
print(f"Document has {page_count} pages")
42
43
# Render first page to SVG
44
svg_output = tk.renderToSVG(pageNo=1)
45
46
# Save SVG to file
47
with open("output.svg", "w") as f:
48
f.write(svg_output)
49
50
# Render to MIDI
51
midi_base64 = tk.renderToMIDI()
52
53
# Save MIDI to file
54
tk.renderToMIDIFile("output.mid")
55
```
56
57
## Architecture
58
59
Verovio uses a toolkit-based architecture where each `toolkit` instance maintains:
60
61
- **Document State**: Loaded music notation data (MEI or converted format)
62
- **Rendering Options**: Page size, scale, spacing, fonts, and layout parameters
63
- **Resource Path**: Location of music fonts (Bravura, Leipzig, Leland, etc.) and other resources
64
65
The library supports multiple music notation fonts compliant with the Standard Music Font Layout (SMuFL) specification, allowing for customized visual output.
66
67
## Capabilities
68
69
### Loading and Configuration
70
71
Load music notation files, configure rendering options, validate input data, and manage the toolkit's resource paths and settings.
72
73
```python { .api }
74
class toolkit:
75
def __init__(self, initFont: bool = True) -> None: ...
76
def loadFile(self, filename: str) -> bool: ...
77
def loadData(self, data: str) -> bool: ...
78
def setOptions(self, json_options: dict) -> bool: ...
79
def getOptions(self) -> dict: ...
80
def setResourcePath(self, path: str) -> None: ...
81
```
82
83
[Loading and Configuration](./loading-config.md)
84
85
### Rendering
86
87
Render loaded music notation to various output formats including SVG, MIDI, Plaine & Easie Code, timemaps, and expansion maps.
88
89
```python { .api }
90
class toolkit:
91
def renderToSVG(self, pageNo: int = 1, xmlDeclaration: bool = False) -> str: ...
92
def renderToSVGFile(self, filename: str, pageNo: int = 1) -> bool: ...
93
def renderToMIDI(self) -> str: ...
94
def renderToMIDIFile(self, filename: str) -> bool: ...
95
def renderToTimemap(self, options: dict | None = None) -> list: ...
96
```
97
98
[Rendering Capabilities](./rendering.md)
99
100
### Data Query and Access
101
102
Query element attributes, timing information, MIDI values, and page locations within the loaded music notation document.
103
104
```python { .api }
105
class toolkit:
106
def getPageCount(self) -> int: ...
107
def getElementAttr(self, xmlId: str) -> dict: ...
108
def getElementsAtTime(self, millisec: int) -> dict: ...
109
def getPageWithElement(self, xmlId: str) -> int: ...
110
def getTimesForElement(self, xmlId: str) -> dict: ...
111
def getMIDIValuesForElement(self, xmlId: str) -> dict: ...
112
```
113
114
[Data Query and Access](./data-access.md)
115
116
### Format Conversion
117
118
Convert between music notation formats including MEI, Humdrum, MIDI, and Plaine & Easie Code.
119
120
```python { .api }
121
class toolkit:
122
def convertMEIToHumdrum(self, meiData: str) -> str: ...
123
def convertHumdrumToHumdrum(self, humdrumData: str) -> str: ...
124
def convertHumdrumToMIDI(self, humdrumData: str) -> str: ...
125
def getMEI(self, options: dict | None = None) -> str: ...
126
def renderToPAE(self) -> str: ...
127
```
128
129
[Format Conversion](./format-conversion.md)
130
131
### Advanced Features
132
133
Advanced functionality including experimental editor features, layout redoing, locale management, runtime measurement, and Humdrum buffer operations.
134
135
```python { .api }
136
class toolkit:
137
def edit(self, editor_action: dict) -> bool: ...
138
def editInfo(self) -> dict: ...
139
def redoLayout(self, options: dict | None = None) -> None: ...
140
def getDescriptiveFeatures(self, options: dict | None = None) -> dict: ...
141
```
142
143
[Advanced Features](./advanced.md)
144
145
## Module-Level Functions
146
147
```python { .api }
148
def setDefaultResourcePath(path: str) -> None:
149
"""
150
Set the default resource path for all toolkit instances.
151
152
Args:
153
path: Path to the resource directory containing fonts and data
154
"""
155
156
def enableLog(level: int) -> None:
157
"""
158
Enable logging at the specified level.
159
160
Args:
161
level: Log level (LOG_OFF, LOG_ERROR, LOG_WARNING, LOG_INFO, LOG_DEBUG)
162
"""
163
```
164
165
## Constants
166
167
### File Format Constants
168
169
```python { .api }
170
UNKNOWN: int # Unknown file format
171
AUTO: int # Auto-detect file format
172
MEI: int # Music Encoding Initiative format
173
HUMDRUM: int # Humdrum format
174
HUMMEI: int # Humdrum to MEI conversion
175
HUMMIDI: int # Humdrum to MIDI conversion
176
PAE: int # Plaine & Easie Code format
177
ABC: int # ABC notation format
178
CMME: int # CMME format
179
DARMS: int # DARMS format
180
VOLPIANO: int # Volpiano format
181
MUSICXML: int # MusicXML format
182
MUSICXMLHUM: int # MusicXML via Humdrum
183
MEIHUM: int # MEI via Humdrum
184
MUSEDATAHUM: int # Musedata via Humdrum
185
ESAC: int # EsAC format
186
MIDI: int # MIDI format
187
TIMEMAP: int # Timemap format
188
EXPANSIONMAP: int # Expansion map format
189
SERIALIZATION: int # Serialization format
190
```
191
192
### Log Level Constants
193
194
```python { .api }
195
LOG_OFF: int # Logging disabled
196
LOG_ERROR: int # Error level logging
197
LOG_WARNING: int # Warning level logging
198
LOG_INFO: int # Info level logging
199
LOG_DEBUG: int # Debug level logging
200
```
201
202
## Common Patterns
203
204
### Setting Rendering Options
205
206
```python
207
import verovio
208
209
tk = verovio.toolkit()
210
211
# Configure page dimensions and appearance
212
options = {
213
'pageHeight': 2970,
214
'pageWidth': 2100,
215
'scale': 40,
216
'adjustPageHeight': True,
217
'breaks': 'auto',
218
'spacingStaff': 4
219
}
220
221
tk.setOptions(options)
222
tk.loadFile("score.mei")
223
svg = tk.renderToSVG()
224
```
225
226
### Working with Element Timing
227
228
```python
229
import verovio
230
231
tk = verovio.toolkit()
232
tk.loadFile("score.mei")
233
234
# Render to MIDI first (required for timing queries)
235
tk.renderToMIDI()
236
237
# Get timing information for a specific element
238
element_id = "note-123"
239
times = tk.getTimesForElement(element_id)
240
241
print(f"Score time onset: {times['scoreTimeOnset']}")
242
print(f"Real time onset: {times['realTimeOnsetMilliseconds']} ms")
243
```
244
245
### Multiple Output Formats
246
247
```python
248
import verovio
249
250
tk = verovio.toolkit()
251
tk.loadFile("score.mei")
252
253
# Render to SVG
254
svg = tk.renderToSVG()
255
with open("score.svg", "w") as f:
256
f.write(svg)
257
258
# Render to MIDI
259
tk.renderToMIDIFile("score.mid")
260
261
# Export to Plaine & Easie Code
262
pae = tk.renderToPAE()
263
with open("score.pae", "w") as f:
264
f.write(pae)
265
266
# Generate timemap for playback synchronization
267
timemap = tk.renderToTimemap()
268
```
269