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