Toolkit methods
This section documents the methods available from the Verovio toolkit. The methods are public methods of the C++ vrv::Toolkit class. They are all available in the Python and JavaScript bindings, unless specified otherwise. For examples, all the methods reading a file or writing to a file are not available in the JavaScript version of the toolkit.
The names of the methods is also indentical across the different versions of the toolkit except for the capitalisation. The original C++ method names are UpperCamelCased in C++ but lowerCamelCased in the Python and JavaScript bindings. This is only to make the bindings follow more idiomatic capitalisation.
For the methods taking parameters as stringified JSON objects (or returning one), the objects are not stringified in the JavaScript version of the toolkit. That is, a JSON object is passed or returned as is. The same applied for the Python toolkit where the object is passed or returned as a Python dictionary.
ConvertHumdrumToHumdrum
Filter Humdrum data.
Returns
std::string – The Humdrum data as a string
Parameters
| Name | Type | Default | Description |
humdrumData |
const std::string & |
∅ |
Original header
std::string vrv::Toolkit::ConvertHumdrumToHumdrum(const std::string &humdrumData)
Example call
result = toolkit.convertHumdrumToHumdrum(humdrumData)
ConvertHumdrumToMIDI
Convert Humdrum data to MIDI.
Returns
std::string – The MIDI file as a base64-encoded string
Parameters
| Name | Type | Default | Description |
humdrumData |
const std::string & |
∅ |
Original header
std::string vrv::Toolkit::ConvertHumdrumToMIDI(const std::string &humdrumData)
Example call
result = toolkit.convertHumdrumToMIDI(humdrumData)
ConvertMEIToHumdrum
Convert MEI data into Humdrum data.
Returns
std::string – The Humdrum data as a string
Parameters
| Name | Type | Default | Description |
meiData |
const std::string & |
∅ |
Original header
std::string vrv::Toolkit::ConvertMEIToHumdrum(const std::string &meiData)
Example call
result = toolkit.convertMEIToHumdrum(meiData)
Edit
Edit the MEI data - experimental code not to rely on.
Returns
bool – True if the edit action was successfully applied
Parameters
| Name | Type | Default | Description |
editorAction |
const std::string & |
∅ | The editor actions as a stringified JSON object |
Original header
bool vrv::Toolkit::Edit(const std::string &editorAction)
Example call
result = toolkit.edit(editorAction)
EditInfo
Return the editor status - experimental code not to rely on.
Returns
std::string – The editor status as a string
Original header
std::string vrv::Toolkit::EditInfo()
Example call
result = toolkit.editInfo()
GetAvailableOptions
Return all available options grouped by category.
For each option, returns the type, the default value, and the minimum and maximum value (when available).
Returns
std::string – A stringified JSON object
Original header
std::string vrv::Toolkit::GetAvailableOptions() const
Example call
result = toolkit.getAvailableOptions()
More info here
Example how to extended the documentation for a method
GetDefaultOptions
Return a dictionary of all the options with their default value.
Returns
std::string – A stringified JSON object
Original header
std::string vrv::Toolkit::GetDefaultOptions() const
Example call
result = toolkit.getDefaultOptions()
GetDescriptiveFeatures
Return descriptive features as a JSON string.
The features are tailored for implementing incipit search.
Returns
std::string – A stringified JSON object with the requested features
Parameters
| Name | Type | Default | Description |
jsonOptions |
const std::string & |
∅ | A stringified JSON object with the feature extraction options |
Original header
std::string vrv::Toolkit::GetDescriptiveFeatures(const std::string &jsonOptions)
Example call
result = toolkit.getDescriptiveFeatures(jsonOptions)
GetElementAttr
Return element attributes as a JSON string.
The attributes returned include the ones not supported by Verovio.
Returns
std::string – A stringified JSON object with all attributes
Parameters
| Name | Type | Default | Description |
xmlId |
const std::string & |
∅ | the ID (@xml:id) of the element being looked for |
Original header
std::string vrv::Toolkit::GetElementAttr(const std::string &xmlId)
Example call
result = toolkit.getElementAttr(xmlId)
The method performs a lookup in the loaded MEI tree and will return all attributes for the retrieved element. This includes attributes currently not supported by Verovio. Looking in the MEI tree means that looking for elements added dynamically for the rendering by Verovio will no be found. This is the case for system elements when loading score-based MEI, or meterSig or clef elements displayed at the beginning of a system.
GetElementsAtTime
Return array of IDs of elements being currently played.
Returns
std::string – A stringified JSON object with the page and notes being played
Parameters
| Name | Type | Default | Description |
millisec |
int |
∅ | The time in milliseconds |
Original header
std::string vrv::Toolkit::GetElementsAtTime(int millisec)
Example call
result = toolkit.getElementsAtTime(millisec)
GetExpansionIdsForElement
Return a vector of ID strings of all elements (the notated and the expanded) for a given element.
Returns
std::string – A stringified JSON object with all IDs
Parameters
| Name | Type | Default | Description |
xmlId |
const std::string & |
∅ | the ID (@xml:id) of the element being looked for |
Original header
std::string vrv::Toolkit::GetExpansionIdsForElement(const std::string &xmlId)
Example call
result = toolkit.getExpansionIdsForElement(xmlId)
GetHumdrum
Get the humdrum buffer.
Returns
std::string – The humdrum buffer as a string
Original header
std::string vrv::Toolkit::GetHumdrum()
Example call
result = toolkit.getHumdrum()
GetHumdrumFile
Write the humdrum buffer to the file.
Returns
bool – True if the file was successfully written
Parameters
| Name | Type | Default | Description |
filename |
const std::string & |
∅ | The output filename |
Original header
bool vrv::Toolkit::GetHumdrumFile(const std::string &filename)
Example call
result = toolkit.getHumdrumFile(filename)
GetID
Return the ID of the Toolkit instance.
Returns
std::string – The ID as as string
Original header
std::string vrv::Toolkit::GetID()
Example call
result = toolkit.getID()
GetLog
Get the log content for the latest operation.
Returns
std::string – The log content as a string
Original header
std::string vrv::Toolkit::GetLog()
Example call
result = toolkit.getLog()
GetMEI
Get the MEI as a string.
Returns
std::string
Parameters
| Name | Type | Default | Description |
jsonOptions |
const std::string & |
"" |
A stringified JSON object with the output options; pageNo: integer; (1-based), all pages if none (or 0) specified; scoreBased: true or false; true by default; basic: true or false; false by default; removeIds: true or false; false by default - remove all @xml:id not used in the data; |
Original header
std::string vrv::Toolkit::GetMEI(const std::string &jsonOptions="")
Example call
result = toolkit.getMEI(jsonOptions)
GetMIDIValuesForElement
Return MIDI values of the element with the ID (@xml:id)
RenderToMIDI() must be called prior to using this method.
Returns
std::string – A stringified JSON object with the MIDI values
Parameters
| Name | Type | Default | Description |
xmlId |
const std::string & |
∅ | the ID (@xml:id) of the element being looked for |
Original header
std::string vrv::Toolkit::GetMIDIValuesForElement(const std::string &xmlId)
Example call
result = toolkit.getMIDIValuesForElement(xmlId)
GetNotatedIdForElement
Return the ID string of the notated (the original) element.
Returns
std::string – An ID string
Parameters
| Name | Type | Default | Description |
xmlId |
const std::string & |
∅ | the ID (@xml:id) of the element being looked for |
Original header
std::string vrv::Toolkit::GetNotatedIdForElement(const std::string &xmlId)
Example call
result = toolkit.getNotatedIdForElement(xmlId)
GetOptionUsageString
Get all usage for all option categories as string.
Returns
std::string
Original header
std::string vrv::Toolkit::GetOptionUsageString() const
Example call
result = toolkit.getOptionUsageString()
GetOptions
Return a dictionary of all the options with their current value.
Returns
std::string – A stringified JSON object
Original header
std::string vrv::Toolkit::GetOptions() const
Example call
result = toolkit.getOptions()
GetPageCount
Return the number of pages in the loaded document.
The number of pages depends one the page size and if encoded layout was taken into account or not.
Returns
int – The number of pages
Original header
int vrv::Toolkit::GetPageCount()
Example call
result = toolkit.getPageCount()
GetPageWithElement
Return the page on which the element is the ID (@xml:id) is rendered.
This takes into account the current layout options.
Returns
int – the page number (1-based) where the element is (0 if not found)
Parameters
| Name | Type | Default | Description |
xmlId |
const std::string & |
∅ | the ID (@xml:id) of the element being looked for |
Original header
int vrv::Toolkit::GetPageWithElement(const std::string &xmlId)
Example call
result = toolkit.getPageWithElement(xmlId)
GetResourcePath
Get the resource path for the Toolkit instance.
Returns
std::string – A string with the resource path
Original header
std::string vrv::Toolkit::GetResourcePath() const
Example call
result = toolkit.getResourcePath()
GetScale
Get the scale option.
Returns
int – the scale option as integer
Original header
int vrv::Toolkit::GetScale()
Example call
result = toolkit.getScale()
GetTimeForElement
Return the time at which the element is the ID (@xml:id) is played.
RenderToMIDI() must be called prior to using this method.
Returns
int – The time in milliseconds
Parameters
| Name | Type | Default | Description |
xmlId |
const std::string & |
∅ | the ID (@xml:id) of the element being looked for |
Original header
int vrv::Toolkit::GetTimeForElement(const std::string &xmlId)
Example call
result = toolkit.getTimeForElement(xmlId)
GetTimesForElement
Return a JSON object string with the following key values for a given note.
Return scoreTimeOnset, scoreTimeOffset, scoreTimeTiedDuration, realTimeOnsetMilliseconds, realTimeOffsetMilliseconds, realTimeTiedDurationMilliseconds.
Returns
std::string – A stringified JSON object with the values
Parameters
| Name | Type | Default | Description |
xmlId |
const std::string & |
∅ | the ID (@xml:id) of the element being looked for |
Original header
std::string vrv::Toolkit::GetTimesForElement(const std::string &xmlId)
Example call
result = toolkit.getTimesForElement(xmlId)
GetVersion
Return the version number.
Returns
std::string – the version number as a string
Original header
std::string vrv::Toolkit::GetVersion() const
Example call
result = toolkit.getVersion()
LoadData
Load a string data with the type previously specified in the options.
By default, the methods try to auto-detect the type.
Returns
bool – True if the data was successfully loaded
Parameters
| Name | Type | Default | Description |
data |
const std::string & |
∅ | A string with the data (e.g., MEI data) to be loaded |
Original header
bool vrv::Toolkit::LoadData(const std::string &data)
Example call
result = toolkit.loadData(data)
LoadFile
Load a file from the file system.
Previously convert UTF16 files to UTF8 or extract files from MusicXML compressed files.
Returns
bool – True if the file was successfully loaded
Parameters
| Name | Type | Default | Description |
filename |
const std::string & |
∅ | The filename to be loaded |
Original header
bool vrv::Toolkit::LoadFile(const std::string &filename)
Example call
result = toolkit.loadFile(filename)
LoadZipDataBase64
Load a MusicXML compressed file passed as base64 encoded string.
Returns
bool – True if the data was successfully loaded
Parameters
| Name | Type | Default | Description |
data |
const std::string & |
∅ | A ZIP file as a base64 encoded string |
Original header
bool vrv::Toolkit::LoadZipDataBase64(const std::string &data)
Example call
result = toolkit.loadZipDataBase64(data)
LoadZipDataBuffer
Load a MusicXML compressed file passed as a buffer of bytes.
Returns
bool – True if the data was successfully loaded
Parameters
| Name | Type | Default | Description |
data |
const unsigned char * |
∅ | A ZIP file as a buffer of bytes |
length |
int |
∅ | The size of the data buffer |
Original header
bool vrv::Toolkit::LoadZipDataBuffer(const unsigned char *data, int length)
Example call
result = toolkit.loadZipDataBuffer(data, length)
PrintOptionUsage
Print formatted option usage for specific category (with max/min/default values) to output stream.
Returns
void
Parameters
| Name | Type | Default | Description |
category |
const std::string & |
∅ | |
output |
std::ostream & |
∅ |
Original header
void vrv::Toolkit::PrintOptionUsage(const std::string &category, std::ostream &output) const
Example call
toolkit.printOptionUsage(category, output)
RedoLayout
Redo the layout of the loaded data.
This can be called once the rendering option were changed, for example with a new page (sceen) height or a new zoom level.
Returns
void
Parameters
| Name | Type | Default | Description |
jsonOptions |
const std::string & |
"" |
A stringified JSON object with the action options resetCache: true or false; true by default; |
Original header
void vrv::Toolkit::RedoLayout(const std::string &jsonOptions="")
Example call
toolkit.redoLayout(jsonOptions)
RedoPagePitchPosLayout
Redo the layout of the pitch postitions of the current drawing page.
Only the note vertical positions are recalculated with this method. RedoLayout() needs to be called for a full recalculation.
Returns
void
Original header
void vrv::Toolkit::RedoPagePitchPosLayout()
Example call
toolkit.redoPagePitchPosLayout()
RenderData
Render the first page of the data to SVG.
This method is a wrapper for setting options, loading data and rendering the first page. It will return an empty string if the options cannot be set or the data cannot be loaded.
Returns
std::string – The SVG first page as a string
Parameters
| Name | Type | Default | Description |
data |
const std::string & |
∅ | A string with the data (e.g., MEI data) to be loaded |
jsonOptions |
const std::string & |
∅ | A stringified JSON objects with the output options |
Original header
std::string vrv::Toolkit::RenderData(const std::string &data, const std::string &jsonOptions)
Example call
result = toolkit.renderData(data, jsonOptions)
RenderToExpansionMap
Render a document’s expansionMap, if existing.
Returns
std::string – The expansionMap as a string
Original header
std::string vrv::Toolkit::RenderToExpansionMap()
Example call
result = toolkit.renderToExpansionMap()
RenderToExpansionMapFile
Render a document’s expansionMap and save it to a file.
Returns
bool
Parameters
| Name | Type | Default | Description |
filename |
const std::string & |
∅ | The output filename |
Original header
bool vrv::Toolkit::RenderToExpansionMapFile(const std::string &filename)
Example call
result = toolkit.renderToExpansionMapFile(filename)
RenderToMIDI
Render the document to MIDI.
Returns
std::string – A MIDI file as a base64 encoded string
Original header
std::string vrv::Toolkit::RenderToMIDI()
Example call
result = toolkit.renderToMIDI()
RenderToMIDIFile
Render a document to MIDI and save it to the file.
Returns
bool – True if the file was successfully written
Parameters
| Name | Type | Default | Description |
filename |
const std::string & |
∅ | The output filename |
Original header
bool vrv::Toolkit::RenderToMIDIFile(const std::string &filename)
Example call
result = toolkit.renderToMIDIFile(filename)
RenderToPAE
Render a document to Plaine & Easie code.
Only the top staff / layer is exported.
Returns
std::string – The PAE as a string
Original header
std::string vrv::Toolkit::RenderToPAE()
Example call
result = toolkit.renderToPAE()
RenderToPAEFile
Render a document to Plaine & Easie code and save it to the file.
Only the top staff / layer is exported.
Returns
bool – True if the file was successfully written
Parameters
| Name | Type | Default | Description |
filename |
const std::string & |
∅ | The output filename |
Original header
bool vrv::Toolkit::RenderToPAEFile(const std::string &filename)
Example call
result = toolkit.renderToPAEFile(filename)
RenderToSVG
Render a page to SVG.
Returns
std::string – The SVG page as a string
Parameters
| Name | Type | Default | Description |
pageNo |
int |
1 |
The page to render (1-based) |
xmlDeclaration |
bool |
false |
True for including the xml declaration in the SVG output |
Original header
std::string vrv::Toolkit::RenderToSVG(int pageNo=1, bool xmlDeclaration=false)
Example call
result = toolkit.renderToSVG(pageNo, xmlDeclaration)
RenderToSVGFile
Render a page to SVG and save it to the file.
Returns
bool – True if the file was successfully written
Parameters
| Name | Type | Default | Description |
filename |
const std::string & |
∅ | The output filename |
pageNo |
int |
1 |
The page to render (1-based) |
Original header
bool vrv::Toolkit::RenderToSVGFile(const std::string &filename, int pageNo=1)
Example call
result = toolkit.renderToSVGFile(filename, pageNo)
RenderToTimemap
Render a document to a timemap.
Returns
std::string – The timemap as a string
Parameters
| Name | Type | Default | Description |
jsonOptions |
const std::string & |
"" |
A stringified JSON objects with the timemap options |
Original header
std::string vrv::Toolkit::RenderToTimemap(const std::string &jsonOptions="")
Example call
result = toolkit.renderToTimemap(jsonOptions)
JSON Options
"includeMeasures": <boolean> |
Include measures in the timemap (false by default) |
"includeRests": <boolean> |
Include rests in the timemap (false by default) |
Examples:
std::string jsonOptions = "{'includeMeasures': 'true'}";
jsonOptions = {'includeMeasures': True}
RenderToTimemapFile
Render a document to timemap and save it to the file.
Returns
bool – True if the file was successfully written
Parameters
| Name | Type | Default | Description |
filename |
const std::string & |
∅ | The output filename |
jsonOptions |
const std::string & |
"" |
A stringified JSON objects with the timemap options |
Original header
bool vrv::Toolkit::RenderToTimemapFile(const std::string &filename, const std::string &jsonOptions="")
Example call
result = toolkit.renderToTimemapFile(filename, jsonOptions)
ResetOptions
Reset all options to default values.
Returns
void
Original header
void vrv::Toolkit::ResetOptions()
Example call
toolkit.resetOptions()
ResetXmlIdSeed
Reset the seed used to generate MEI @xml:id attribute values.
Passing 0 will seed the @xml:id generator with a random (time-based) seed value. This method will have no effect if the xml-id-checksum option is set.
Returns
void
Parameters
| Name | Type | Default | Description |
seed |
int |
∅ | The seed value for generating the @xml:id values (0 for a time-based random seed) |
Original header
void vrv::Toolkit::ResetXmlIdSeed(int seed)
Example call
toolkit.resetXmlIdSeed(seed)
SaveFile
Get the MEI and save it to the file.
Returns
bool – True if the file was successfully written
Parameters
| Name | Type | Default | Description |
filename |
const std::string & |
∅ | The output filename |
jsonOptions |
const std::string & |
"" |
A stringified JSON object with the output options |
Original header
bool vrv::Toolkit::SaveFile(const std::string &filename, const std::string &jsonOptions="")
Example call
result = toolkit.saveFile(filename, jsonOptions)
Select
Set the value for a selection.
The selection will be applied only when some data is loaded or the layout is redone. The selection can be reset (cancelled) by passing an empty string or an empty JSON object. A selection across multiple mdivs is not possible.
Returns
bool – True if the selection was successfully parsed or reset
Parameters
| Name | Type | Default | Description |
selection |
const std::string & |
∅ | The selection as a stringified JSON object |
Original header
bool vrv::Toolkit::Select(const std::string &selection)
Example call
result = toolkit.select(selection)
Examples for selection parameter
{ "measureRange": "2-3" }
{ "measureRange": "82-end" }
{ "measureRange": "38" }
{ "start": "measure-L337", "end": "measure-L355" }
{}
SetInputFrom
Set the input from option.
Returns
bool – True if the option was successfully set
Parameters
| Name | Type | Default | Description |
inputFrom |
std::string const & |
∅ | the input from value as string |
Original header
bool vrv::Toolkit::SetInputFrom(std::string const &inputFrom)
Example call
result = toolkit.setInputFrom(inputFrom)
SetOptions
Set option values.
The name of each option to be set is to be given as JSON key.
Returns
bool – True if the options were successfully set
Parameters
| Name | Type | Default | Description |
jsonOptions |
const std::string & |
∅ | A stringified JSON objects with the output options |
Original header
bool vrv::Toolkit::SetOptions(const std::string &jsonOptions)
Example call
result = toolkit.setOptions(jsonOptions)
SetOutputTo
Set the output to option.
Returns
bool – True if the option was successfully set
Parameters
| Name | Type | Default | Description |
outputTo |
std::string const & |
∅ | the value to output as string |
Original header
bool vrv::Toolkit::SetOutputTo(std::string const &outputTo)
Example call
result = toolkit.setOutputTo(outputTo)
SetResourcePath
Set the resource path for the Toolkit instance and any extra fonts.
This method needs to be called if the constructor had initFont=false or if the resource path needs to be changed.
Returns
bool – True if the resources was successfully loaded
Parameters
| Name | Type | Default | Description |
path |
const std::string & |
∅ | The path to the resource directory |
Original header
bool vrv::Toolkit::SetResourcePath(const std::string &path)
Example call
result = toolkit.setResourcePath(path)
SetScale
Set the scale option.
Returns
bool – True if the option was successfully set
Parameters
| Name | Type | Default | Description |
scale |
int |
∅ | the scale value as integer |
Original header
bool vrv::Toolkit::SetScale(int scale)
Example call
result = toolkit.setScale(scale)
See also: Scaling
Toolkit
Constructor.
Parameters
| Name | Type | Default | Description |
initFont |
bool |
true |
If set to false, resource path is not initialized and SetResourcePath will have to be called explicitely |
Original header
vrv::Toolkit::Toolkit(bool initFont=true)
Example call
result = toolkit.toolkit(initFont)
ValidatePAE
Validate the Plaine & Easie code passed in the string data.
A single JSON object is returned when there is a global input error. When reading the input succeeds, validation is grouped by input keys. The methods always returns errors in PAE pedantic mode. No data remains loaded after the validation.
Returns
std::string – A stringified JSON object with the validation warnings or errors
Parameters
| Name | Type | Default | Description |
data |
const std::string & |
∅ | A string with the data in JSON or with PAE @ keys |
Original header
std::string vrv::Toolkit::ValidatePAE(const std::string &data)
Example call
result = toolkit.validatePAE(data)
See also: Plaine and Easie
ValidatePAEFile
Validate the Plaine & Easie code from a file.
The method calls Toolkit::ValidatePAE.
Returns
std::string – A stringified JSON object with the validation warnings or errors
Parameters
| Name | Type | Default | Description |
filename |
const std::string & |
∅ | The filename to be validated |
Original header
std::string vrv::Toolkit::ValidatePAEFile(const std::string &filename)
Example call
result = toolkit.validatePAEFile(filename)
See also: Plaine and Easie