0
# Loading and Configuration
1
2
This document covers loading music notation files, managing resources, configuring rendering options, and validating input data.
3
4
## Capabilities
5
6
### Toolkit Initialization
7
8
Create and initialize toolkit instances for rendering music notation.
9
10
```python { .api }
11
class toolkit:
12
"""
13
Main class for loading, rendering, and manipulating music notation.
14
"""
15
def __init__(self, initFont: bool = True) -> None:
16
"""
17
Create a new toolkit instance.
18
19
Args:
20
initFont: If True (default), initialize fonts and set default resource path.
21
If False, setResourcePath() must be called explicitly before use.
22
"""
23
```
24
25
### File and Data Loading
26
27
Load music notation from files or string data in various formats.
28
29
```python { .api }
30
class toolkit:
31
def loadFile(self, filename: str) -> bool:
32
"""
33
Load a music notation file from the file system.
34
35
Supports MEI, MusicXML, Humdrum, PAE, ABC, and other formats.
36
File format is auto-detected. Handles UTF-16 conversion and
37
MusicXML compressed files automatically.
38
39
Args:
40
filename: Path to the file to load
41
42
Returns:
43
True if the file was successfully loaded, False otherwise
44
"""
45
46
def loadData(self, data: str) -> bool:
47
"""
48
Load music notation from a string.
49
50
File format is auto-detected by default, or can be specified
51
using setInputFrom() before calling this method.
52
53
Args:
54
data: Music notation data as a string (MEI, MusicXML, etc.)
55
56
Returns:
57
True if the data was successfully loaded, False otherwise
58
"""
59
60
def loadZipDataBase64(self, data: str) -> bool:
61
"""
62
Load a MusicXML compressed file from a base64 encoded string.
63
64
Args:
65
data: ZIP file encoded as base64 string
66
67
Returns:
68
True if the data was successfully loaded, False otherwise
69
"""
70
71
def loadZipDataBuffer(self, data: bytes, length: int) -> bool:
72
"""
73
Load a MusicXML compressed file from a byte buffer.
74
75
Args:
76
data: ZIP file as bytes
77
length: Size of the data buffer
78
79
Returns:
80
True if the data was successfully loaded, False otherwise
81
"""
82
```
83
84
### Input Validation
85
86
Validate Plaine & Easie Code before loading.
87
88
```python { .api }
89
class toolkit:
90
def validatePAE(self, data: str | dict) -> dict:
91
"""
92
Validate Plaine & Easie code.
93
94
Returns errors in PAE pedantic mode. No data remains loaded
95
after validation. When reading succeeds, validation is grouped
96
by input keys.
97
98
Args:
99
data: PAE data as string or dict with PAE keys
100
101
Returns:
102
Dictionary with validation warnings or errors
103
"""
104
105
def validatePAEFile(self, filename: str) -> dict:
106
"""
107
Validate Plaine & Easie code from a file.
108
109
Args:
110
filename: Path to file containing PAE data
111
112
Returns:
113
Dictionary with validation warnings or errors
114
"""
115
116
def getPageCount(self) -> int:
117
"""
118
Return the number of pages in the loaded document.
119
120
The number of pages depends on page size and whether
121
encoded layout was taken into account.
122
123
Returns:
124
Number of pages in the loaded document
125
"""
126
```
127
128
### Options Management
129
130
Configure rendering options including page dimensions, scale, spacing, and appearance.
131
132
```python { .api }
133
class toolkit:
134
def getOptions(self) -> dict:
135
"""
136
Get all current option values.
137
138
Returns:
139
Dictionary with all current option values
140
"""
141
142
def getDefaultOptions(self) -> dict:
143
"""
144
Get all default option values.
145
146
Returns:
147
Dictionary with all default option values
148
"""
149
150
def getAvailableOptions(self) -> dict:
151
"""
152
Get all available options grouped by category.
153
154
For each option, returns the type, default value, and
155
minimum and maximum values (when available).
156
157
Returns:
158
Dictionary with all available options and their metadata
159
"""
160
161
def setOptions(self, json_options: dict) -> bool:
162
"""
163
Set option values.
164
165
Common options include:
166
- pageHeight: Page height in MEI units
167
- pageWidth: Page width in MEI units
168
- scale: Scaling factor (percentage)
169
- adjustPageHeight: Auto-adjust page height
170
- breaks: Break handling ('auto', 'line', 'encoded', 'none')
171
- spacingStaff: Staff spacing multiplier
172
- header: Header display ('auto', 'encoded', 'none')
173
- footer: Footer display ('auto', 'encoded', 'none')
174
175
Args:
176
json_options: Dictionary with option names and values
177
178
Returns:
179
True if options were successfully set, False otherwise
180
"""
181
182
def resetOptions(self) -> None:
183
"""
184
Reset all options to their default values.
185
"""
186
187
def getOptionUsageString(self) -> str:
188
"""
189
Get formatted option usage information for all categories.
190
191
Returns:
192
String with usage information for all options
193
"""
194
195
def setScale(self, scale: int) -> bool:
196
"""
197
Set the scale option.
198
199
Args:
200
scale: Scale value as integer (percentage)
201
202
Returns:
203
True if successfully set, False otherwise
204
"""
205
206
def getScale(self) -> int:
207
"""
208
Get the current scale option.
209
210
Returns:
211
Current scale value as integer
212
"""
213
```
214
215
### Format Control
216
217
Set input and output format preferences.
218
219
```python { .api }
220
class toolkit:
221
def setInputFrom(self, format: str) -> bool:
222
"""
223
Set the input format.
224
225
Overrides auto-detection. Use format constant names
226
like 'mei', 'musicxml', 'humdrum', 'pae', etc.
227
228
Args:
229
format: Input format as string
230
231
Returns:
232
True if successfully set, False otherwise
233
"""
234
235
def getInputFrom(self) -> int:
236
"""
237
Get the current input format setting.
238
239
Returns:
240
Input format enumeration value
241
"""
242
243
def setOutputTo(self, outputTo: str) -> bool:
244
"""
245
Set the output format preference.
246
247
Args:
248
outputTo: Output format as string
249
250
Returns:
251
True if successfully set, False otherwise
252
"""
253
254
def getOutputTo(self) -> int:
255
"""
256
Get the current output format setting.
257
258
Returns:
259
Output format enumeration value
260
"""
261
```
262
263
### Resource Management
264
265
Manage resource paths for fonts and data files.
266
267
```python { .api }
268
class toolkit:
269
def getResourcePath(self) -> str:
270
"""
271
Get the resource path for this toolkit instance.
272
273
Returns:
274
Current resource path as string
275
"""
276
277
def setResourcePath(self, path: str) -> None:
278
"""
279
Set the resource path for this toolkit instance.
280
281
Must be called if the toolkit was initialized with initFont=False,
282
or to change the resource path.
283
284
Args:
285
path: Path to the resource directory containing fonts and data
286
"""
287
288
def getID(self) -> str:
289
"""
290
Get the unique ID of this toolkit instance.
291
292
Returns:
293
Instance ID as string
294
"""
295
296
def getVersion(self) -> str:
297
"""
298
Get the Verovio version number.
299
300
Returns:
301
Version string
302
"""
303
```
304
305
### XML ID Management
306
307
Control generation of MEI @xml:id attributes.
308
309
```python { .api }
310
class toolkit:
311
def resetXmlIdSeed(self, seed: int) -> None:
312
"""
313
Reset the seed for generating MEI @xml:id attribute values.
314
315
Passing 0 uses a time-based random seed. This method has no
316
effect if the --xml-id-checksum option is set.
317
318
Args:
319
seed: Seed value for ID generation (0 for random seed)
320
"""
321
```
322
323
### Logging
324
325
Access log output from operations.
326
327
```python { .api }
328
class toolkit:
329
def getLog(self) -> str:
330
"""
331
Get the log content from the latest operation.
332
333
Returns:
334
Log content as string
335
"""
336
```
337
338
## Usage Examples
339
340
### Basic Loading and Configuration
341
342
```python
343
import verovio
344
345
# Create toolkit with default initialization
346
tk = verovio.toolkit()
347
348
# Load an MEI file
349
if tk.loadFile("score.mei"):
350
print(f"Loaded successfully, {tk.getPageCount()} pages")
351
else:
352
print(f"Error loading file: {tk.getLog()}")
353
354
# Configure rendering options
355
options = {
356
'pageHeight': 2970,
357
'pageWidth': 2100,
358
'scale': 40,
359
'adjustPageHeight': True,
360
'breaks': 'auto'
361
}
362
tk.setOptions(options)
363
```
364
365
### Loading from String Data
366
367
```python
368
import verovio
369
370
tk = verovio.toolkit()
371
372
# Load MEI data from string
373
mei_data = """<?xml version="1.0" encoding="UTF-8"?>
374
<mei xmlns="http://www.music-encoding.org/ns/mei">
375
<!-- MEI content here -->
376
</mei>"""
377
378
if tk.loadData(mei_data):
379
print("Data loaded successfully")
380
```
381
382
### Validating PAE Data
383
384
```python
385
import verovio
386
387
tk = verovio.toolkit()
388
389
# Validate PAE data before loading
390
pae_data = "@clef:G-2@key:xFC@time:3/4@data:8ABCDEF"
391
validation_result = tk.validatePAE(pae_data)
392
393
if validation_result.get('errors'):
394
print(f"Validation errors: {validation_result['errors']}")
395
else:
396
print("PAE data is valid")
397
```
398
399
### Custom Resource Path
400
401
```python
402
import verovio
403
404
# Initialize without default fonts
405
tk = verovio.toolkit(initFont=False)
406
407
# Set custom resource path
408
tk.setResourcePath("/custom/path/to/verovio/data")
409
410
# Now load and render as normal
411
tk.loadFile("score.mei")
412
```
413
414
### Exploring Available Options
415
416
```python
417
import verovio
418
419
tk = verovio.toolkit()
420
421
# Get all available options
422
available = tk.getAvailableOptions()
423
424
# Print options by category
425
for category, options in available.items():
426
print(f"\n{category}:")
427
for opt_name, opt_info in options.items():
428
print(f" {opt_name}: {opt_info}")
429
430
# Get current values
431
current = tk.getOptions()
432
print(f"\nCurrent scale: {current['scale']}")
433
434
# Get defaults
435
defaults = tk.getDefaultOptions()
436
print(f"Default scale: {defaults['scale']}")
437
```
438
439
### Setting Input Format
440
441
```python
442
import verovio
443
444
tk = verovio.toolkit()
445
446
# Force MusicXML interpretation
447
tk.setInputFrom('musicxml')
448
449
# Load data that might be ambiguous
450
tk.loadData(xml_string)
451
```
452