0
# Rendering Capabilities
1
2
This document covers rendering loaded music notation to various output formats including SVG, MIDI, Plaine & Easie Code, timemaps, and expansion maps.
3
4
## Capabilities
5
6
### SVG Rendering
7
8
Render music notation to scalable vector graphics (SVG) format.
9
10
```python { .api }
11
class toolkit:
12
def renderData(self, data: str, options: dict) -> str:
13
"""
14
Render the first page of data to SVG.
15
16
This is a convenience wrapper that sets options, loads data,
17
and renders the first page in one call. Returns empty string
18
if options cannot be set or data cannot be loaded.
19
20
Args:
21
data: Music notation data as string (MEI, MusicXML, etc.)
22
options: Dictionary with rendering options
23
24
Returns:
25
SVG for the first page as string, or empty string on error
26
"""
27
28
def renderToSVG(self, pageNo: int = 1, xmlDeclaration: bool = False) -> str:
29
"""
30
Render a page to SVG.
31
32
Args:
33
pageNo: Page number to render (1-based), defaults to 1
34
xmlDeclaration: Include XML declaration in SVG output, defaults to False
35
36
Returns:
37
SVG page as string
38
"""
39
40
def renderToSVGFile(self, filename: str, pageNo: int = 1) -> bool:
41
"""
42
Render a page to SVG and save to file.
43
44
Args:
45
filename: Output file path
46
pageNo: Page number to render (1-based), defaults to 1
47
48
Returns:
49
True if file was successfully written, False otherwise
50
"""
51
```
52
53
### MIDI Rendering
54
55
Render music notation to MIDI format for audio playback.
56
57
```python { .api }
58
class toolkit:
59
def renderToMIDI(self) -> str:
60
"""
61
Render the loaded document to MIDI.
62
63
Returns:
64
MIDI file as base64 encoded string
65
"""
66
67
def renderToMIDIFile(self, filename: str) -> bool:
68
"""
69
Render document to MIDI and save to file.
70
71
Args:
72
filename: Output file path
73
74
Returns:
75
True if file was successfully written, False otherwise
76
"""
77
```
78
79
### Plaine & Easie Code Export
80
81
Export music notation to Plaine & Easie Code format.
82
83
```python { .api }
84
class toolkit:
85
def renderToPAE(self) -> str:
86
"""
87
Render document to Plaine & Easie code.
88
89
Only the top staff/layer is exported.
90
91
Returns:
92
PAE data as string
93
"""
94
95
def renderToPAEFile(self, filename: str) -> bool:
96
"""
97
Render document to Plaine & Easie code and save to file.
98
99
Only the top staff/layer is exported.
100
101
Args:
102
filename: Output file path
103
104
Returns:
105
True if file was successfully written, False otherwise
106
"""
107
```
108
109
### Timemap Generation
110
111
Generate timemaps for synchronizing visual rendering with audio playback.
112
113
```python { .api }
114
class toolkit:
115
def renderToTimemap(self, options: dict | None = None) -> list:
116
"""
117
Render document to a timemap.
118
119
Timemaps provide temporal information for each musical event,
120
enabling synchronization between visual notation and audio playback.
121
122
Args:
123
options: Dictionary with timemap options, optional
124
125
Returns:
126
Timemap as list of event dictionaries
127
"""
128
129
def renderToTimemapFile(self, filename: str, options: dict | None = None) -> bool:
130
"""
131
Render document to timemap and save to file.
132
133
Args:
134
filename: Output file path
135
options: Dictionary with timemap options, optional
136
137
Returns:
138
True if file was successfully written, False otherwise
139
"""
140
```
141
142
### Expansion Map Generation
143
144
Generate expansion maps for documents with repeats and other expansions.
145
146
```python { .api }
147
class toolkit:
148
def renderToExpansionMap(self) -> list:
149
"""
150
Render document's expansion map, if existing.
151
152
Expansion maps show how notated elements map to their
153
expanded forms when repeats and other expansions are applied.
154
155
Returns:
156
Expansion map as list
157
"""
158
159
def renderToExpansionMapFile(self, filename: str) -> bool:
160
"""
161
Render document's expansion map and save to file.
162
163
Args:
164
filename: Output file path
165
166
Returns:
167
True if file was successfully written, False otherwise
168
"""
169
```
170
171
### Selection
172
173
Apply selection to limit what is rendered.
174
175
```python { .api }
176
class toolkit:
177
def select(self, selection: dict) -> bool:
178
"""
179
Set a selection to be applied to rendering.
180
181
The selection is applied when data is loaded or layout is redone.
182
Pass an empty dict to reset/cancel the selection.
183
Selection across multiple mdivs is not possible.
184
185
Args:
186
selection: Dictionary defining the selection
187
188
Returns:
189
True if selection was successfully parsed or reset, False otherwise
190
"""
191
```
192
193
## Usage Examples
194
195
### Basic SVG Rendering
196
197
```python
198
import verovio
199
200
tk = verovio.toolkit()
201
202
# Load file and render all pages
203
tk.loadFile("score.mei")
204
page_count = tk.getPageCount()
205
206
for page_num in range(1, page_count + 1):
207
svg = tk.renderToSVG(pageNo=page_num)
208
with open(f"page_{page_num}.svg", "w") as f:
209
f.write(svg)
210
```
211
212
### Quick Render with Options
213
214
```python
215
import verovio
216
217
tk = verovio.toolkit()
218
219
# Render data with custom options in one call
220
options = {
221
'pageHeight': 2970,
222
'pageWidth': 2100,
223
'scale': 40
224
}
225
226
with open("score.mei", "r") as f:
227
mei_data = f.read()
228
229
svg = tk.renderData(mei_data, options)
230
with open("output.svg", "w") as f:
231
f.write(svg)
232
```
233
234
### MIDI Export
235
236
```python
237
import verovio
238
import base64
239
240
tk = verovio.toolkit()
241
tk.loadFile("score.mei")
242
243
# Get MIDI as base64 string
244
midi_base64 = tk.renderToMIDI()
245
246
# Decode and save
247
midi_bytes = base64.b64decode(midi_base64)
248
with open("output.mid", "wb") as f:
249
f.write(midi_bytes)
250
251
# Or use the convenience method
252
tk.renderToMIDIFile("output.mid")
253
```
254
255
### Timemap for Playback Sync
256
257
```python
258
import verovio
259
import json
260
261
tk = verovio.toolkit()
262
tk.loadFile("score.mei")
263
264
# Generate timemap
265
timemap = tk.renderToTimemap()
266
267
# Save for use in playback application
268
with open("timemap.json", "w") as f:
269
json.dump(timemap, f, indent=2)
270
271
# Timemap entries contain information like:
272
# - Element IDs
273
# - Onset times
274
# - Offset times
275
# - Page numbers
276
```
277
278
### Working with Selections
279
280
```python
281
import verovio
282
283
tk = verovio.toolkit()
284
tk.loadFile("score.mei")
285
286
# Select specific measures to render
287
selection = {
288
"start": "measure-1",
289
"end": "measure-10"
290
}
291
tk.select(selection)
292
293
# Render only the selected measures
294
svg = tk.renderToSVG()
295
296
# Clear selection
297
tk.select({})
298
299
# Now renders full document
300
svg_full = tk.renderToSVG()
301
```
302
303
### Multiple Format Export
304
305
```python
306
import verovio
307
308
tk = verovio.toolkit()
309
tk.loadFile("score.mei")
310
311
# Export to multiple formats
312
tk.renderToSVGFile("output.svg", pageNo=1)
313
tk.renderToMIDIFile("output.mid")
314
tk.renderToPAEFile("output.pae")
315
tk.renderToTimemapFile("timemap.json")
316
317
# Check for expansion map
318
expansion_map = tk.renderToExpansionMap()
319
if expansion_map:
320
tk.renderToExpansionMapFile("expansion.json")
321
print("Document has expansions (repeats, etc.)")
322
```
323
324
### High-Resolution SVG
325
326
```python
327
import verovio
328
329
tk = verovio.toolkit()
330
331
# Set high scale for print quality
332
options = {
333
'scale': 100, # High resolution
334
'pageHeight': 2970,
335
'pageWidth': 2100
336
}
337
tk.setOptions(options)
338
339
tk.loadFile("score.mei")
340
tk.renderToSVGFile("high_res_output.svg")
341
```
342
343
### SVG with XML Declaration
344
345
```python
346
import verovio
347
348
tk = verovio.toolkit()
349
tk.loadFile("score.mei")
350
351
# Get SVG with XML declaration for standalone file
352
svg_with_declaration = tk.renderToSVG(pageNo=1, xmlDeclaration=True)
353
354
# Suitable for direct file output
355
with open("standalone.svg", "w") as f:
356
f.write(svg_with_declaration)
357
```
358
359
### Custom Timemap Options
360
361
```python
362
import verovio
363
364
tk = verovio.toolkit()
365
tk.loadFile("score.mei")
366
367
# Generate timemap with custom options
368
timemap_options = {
369
'includeRests': True,
370
'includeMeasures': True
371
}
372
timemap = tk.renderToTimemap(options=timemap_options)
373
374
# Process timemap for interactive playback
375
for event in timemap:
376
element_id = event.get('id')
377
onset_time = event.get('on')
378
offset_time = event.get('off')
379
print(f"Element {element_id}: {onset_time}ms - {offset_time}ms")
380
```
381