Public Member Functions
Constructors and destructors
	Toolkit (bool initFont=true)
	Constructor. More...

virtual	~Toolkit ()

Utility methods
std::string	GetID ()
	Return the ID of the Toolkit instance. More...

std::string	GetResourcePath () const
	Get the resource path for the Toolkit instance. More...

bool	SetResourcePath (const std::string &path)
	Set the resource path for the Toolkit instance and any extra fonts. More...

std::string	GetLog ()
	Get the log content for the latest operation. More...

std::string	GetVersion () const
	Return the version number. More...

void	ResetXmlIdSeed (int seed)
	Reset the seed used to generate MEI @xml:id attribute values. More...

Loading methods
bool	LoadFile (const std::string &filename)
	Load a file from the file system. More...

bool	LoadData (const std::string &data)
	Load a string data with the type previously specified in the options. More...

bool	LoadZipDataBase64 (const std::string &data)
	Load a MusicXML compressed file passed as base64 encoded string. More...

bool	LoadZipDataBuffer (const unsigned char *data, int length)
	Load a MusicXML compressed file passed as a buffer of bytes. More...

std::string	ValidatePAEFile (const std::string &filename)
	Validate the Plaine & Easie code from a file. More...

std::string	ValidatePAE (const std::string &data)
	Validate the Plaine & Easie code passed in the string data. More...

int	GetPageCount ()
	Return the number of pages in the loaded document. More...

Getter and setter for options
std::string	GetOptions () const
	Return a dictionary of all the options with their current value. More...

std::string	GetDefaultOptions () const
	Return a dictionary of all the options with their default value. More...

std::string	GetAvailableOptions () const
	Return all available options grouped by category. More...

bool	SetOptions (const std::string &jsonOptions)
	Set option values. More...

void	ResetOptions ()
	Reset all options to default values.

void	PrintOptionUsage (const std::string &category, std::ostream &output) const
	Print formatted option usage for specific category (with max/min/default values) to output stream.

std::string	GetOptionUsageString () const
	Get all usage for all option categories as string.

bool	SetScale (int scale)
	Set the scale option. More...

int	GetScale ()
	Get the scale option. More...

bool	SetInputFrom (std::string const &inputFrom)
	Set the input from option. More...

bool	SetOutputTo (std::string const &outputTo)
	Set the output to option. More...

bool	Select (const std::string &selection)
	Set the value for a selection. More...

Experimental editor methods
bool	Edit (const std::string &editorAction)
	Edit the MEI data - experimental code not to rely on. More...

std::string	EditInfo ()
	Return the editor status - experimental code not to rely on. More...

Rendering methods
std::string	RenderData (const std::string &data, const std::string &jsonOptions)
	Render the first page of the data to SVG. More...

std::string	RenderToSVG (int pageNo=1, bool xmlDeclaration=false)
	Render a page to SVG. More...

bool	RenderToSVGFile (const std::string &filename, int pageNo=1)
	Render a page to SVG and save it to the file. More...

std::string	RenderToMIDI ()
	Render the document to MIDI. More...

bool	RenderToMIDIFile (const std::string &filename)
	Render a document to MIDI and save it to the file. More...

std::string	RenderToPAE ()
	Render a document to Plaine & Easie code. More...

bool	RenderToPAEFile (const std::string &filename)
	Render a document to Plaine & Easie code and save it to the file. More...

std::string	RenderToTimemap (const std::string &jsonOptions="")
	Render a document to a timemap. More...

std::string	RenderToExpansionMap ()
	Render a document's expansionMap, if existing. More...

bool	RenderToTimemapFile (const std::string &filename, const std::string &jsonOptions="")
	Render a document to timemap and save it to the file. More...

bool	RenderToExpansionMapFile (const std::string &filename)
	Render a document's expansionMap and save it to a file. More...

Humdrum related methods
std::string	GetHumdrum ()
	Get the humdrum buffer. More...

std::string	ConvertMEIToHumdrum (const std::string &meiData)
	Convert MEI data into Humdrum data. More...

std::string	ConvertHumdrumToHumdrum (const std::string &humdrumData)
	Filter Humdrum data. More...

std::string	ConvertHumdrumToMIDI (const std::string &humdrumData)
	Convert Humdrum data to MIDI. More...

bool	GetHumdrumFile (const std::string &filename)
	Write the humdrum buffer to the file. More...

MEI related methods
std::string	GetMEI (const std::string &jsonOptions="")
	Get the MEI as a string. More...

bool	SaveFile (const std::string &filename, const std::string &jsonOptions="")
	Get the MEI and save it to the file. More...

Data access methods
std::string	GetDescriptiveFeatures (const std::string &jsonOptions)
	Return descriptive features as a JSON string. More...

std::string	GetElementsAtTime (int millisec)
	Return array of IDs of elements being currently played. More...

int	GetPageWithElement (const std::string &xmlId)
	Return the page on which the element is the ID (@xml:id) is rendered. More...

std::string	GetElementAttr (const std::string &xmlId)
	Return element attributes as a JSON string. More...

std::string	GetNotatedIdForElement (const std::string &xmlId)
	Return the ID string of the notated (the original) element. More...

std::string	GetExpansionIdsForElement (const std::string &xmlId)
	Return a vector of ID strings of all elements (the notated and the expanded) for a given element. More...

int	GetTimeForElement (const std::string &xmlId)
	Return the time at which the element is the ID (@xml:id) is played. More...

std::string	GetMIDIValuesForElement (const std::string &xmlId)
	Return MIDI values of the element with the ID (@xml:id) More...

std::string	GetTimesForElement (const std::string &xmlId)
	Return a JSON object string with the following key values for a given note. More...

Layout related methods
void	RedoLayout (const std::string &jsonOptions="")
	Redo the layout of the loaded data. More...

void	RedoPagePitchPosLayout ()
	Redo the layout of the pitch postitions of the current drawing page. More...

Public methods that are not listed in the documentation
bool	RenderToDeviceContext (int pageNo, DeviceContext *deviceContext)
	Render the page to the deviceContext. More...

Options *	GetOptionsObj ()
	Return the Options object of the Toolkit instance.

void	SetCString (const std::string &data)
	Copy the data to the cstring internal buffer.

const char *	GetCString ()
	Return the content of the cstring internal buffer. More...

void	GetHumdrum (std::ostream &output)
	Write the Humdrum buffer to the outputstream.

void	SetHumdrumBuffer (const char *contents)
	Copy the data to the humdrum internal buffer.

const char *	GetHumdrumBuffer ()
	Return the content of the humdrum internal buffer. More...

void	ClearHumdrumBuffer ()
	Clear the Humdrum buffer of any contents.

void	SetInputFrom (FileFormat format)

int	GetInputFrom ()
	Get the input format. More...

int	GetOutputTo ()

void	SetLocale ()
	Setting the global locale.

void	ResetLocale ()


void	InitClock ()
	Measuring runtime.

void	ResetClock ()

double	GetRuntimeInSeconds () const

void	LogRuntime () const

Protected Member Functions
FileFormat	IdentifyInputFrom (const std::string &data)
	Identify the input file type for auto loading of input data.

void	PrintOptionUsageOutput (const vrv::Option *option, std::ostream &output) const
	Print formatted option usage for specific option to output stream.

void	ResetLogBuffer ()
	Resets the vrv::logBuffer.

void	LogRedirectStart ()
	Start capturing std::cerr from an external codebase for redirection to vrv::logBuffer. More...

void	LogRedirectStop ()
	End capturing std::cerr from an external codebase for redirection to vrv::logBuffer.

bool	LoadData (const std::string &data, bool resetLogBuffer)
	Load a string data with or without resetting the log buffer.

Constructor & Destructor Documentation

◆ Toolkit()

vrv::Toolkit::Toolkit ( bool initFont = true )

Constructor.

Parameters

initFont If set to false, resource path is not initialized and SetResourcePath will have to be called explicitely

Member Function Documentation

◆ ConvertHumdrumToHumdrum()

std::string vrv::Toolkit::ConvertHumdrumToHumdrum ( const std::string & humdrumData )

Filter Humdrum data.

Returns: The Humdrum data as a string

◆ ConvertHumdrumToMIDI()

std::string vrv::Toolkit::ConvertHumdrumToMIDI ( const std::string & humdrumData )

Convert Humdrum data to MIDI.

Returns: The MIDI file as a base64-encoded string

◆ ConvertMEIToHumdrum()

std::string vrv::Toolkit::ConvertMEIToHumdrum ( const std::string & meiData )

Convert MEI data into Humdrum data.

Returns: The Humdrum data as a string

◆ Edit()

bool vrv::Toolkit::Edit ( const std::string & editorAction )

Edit the MEI data - experimental code not to rely on.

Parameters

editorAction The editor actions as a stringified JSON object

Returns: True if the edit action was successfully applied

◆ EditInfo()

std::string vrv::Toolkit::EditInfo ( )

Return the editor status - experimental code not to rely on.

Returns: The editor status as a string

◆ GetAvailableOptions()

std::string vrv::Toolkit::GetAvailableOptions ( ) const

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: A stringified JSON object

◆ GetDefaultOptions()

std::string vrv::Toolkit::GetDefaultOptions ( ) const

Return a dictionary of all the options with their default value.

Returns: A stringified JSON object

◆ GetDescriptiveFeatures()

std::string vrv::Toolkit::GetDescriptiveFeatures ( const std::string & jsonOptions )

Return descriptive features as a JSON string.

The features are tailored for implementing incipit search.

Parameters

jsonOptions A stringified JSON object with the feature extraction options

Returns: A stringified JSON object with the requested features

◆ GetElementAttr()

std::string vrv::Toolkit::GetElementAttr ( const std::string & xmlId )

Return element attributes as a JSON string.

The attributes returned include the ones not supported by Verovio.

Parameters

xmlId the ID (@xml:id) of the element being looked for

Returns: A stringified JSON object with all attributes

◆ GetElementsAtTime()

std::string vrv::Toolkit::GetElementsAtTime ( int millisec )

Return array of IDs of elements being currently played.

Parameters

millisec The time in milliseconds

Returns: A stringified JSON object with the page and notes being played

◆ GetExpansionIdsForElement()

std::string vrv::Toolkit::GetExpansionIdsForElement ( const std::string & xmlId )

Return a vector of ID strings of all elements (the notated and the expanded) for a given element.

Parameters

xmlId the ID (@xml:id) of the element being looked for

Returns: A stringified JSON object with all IDs

◆ GetHumdrum()

std::string vrv::Toolkit::GetHumdrum ( )

Get the humdrum buffer.

Returns: The humdrum buffer as a string

◆ GetHumdrumFile()

bool vrv::Toolkit::GetHumdrumFile ( const std::string & filename )

Write the humdrum buffer to the file.

Remarks: nojs

Parameters

filename The output filename

Returns: True if the file was successfully written

◆ GetID()

std::string vrv::Toolkit::GetID ( )

inline

Return the ID of the Toolkit instance.

Remarks: nojs

Returns: The ID as as string

◆ GetLog()

std::string vrv::Toolkit::GetLog ( )

Get the log content for the latest operation.

Returns: The log content as a string

◆ GetMEI()

std::string vrv::Toolkit::GetMEI ( const std::string & jsonOptions = "" )

Get the MEI as a string.

Parameters

jsonOptions 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;

◆ GetMIDIValuesForElement()

std::string vrv::Toolkit::GetMIDIValuesForElement ( const std::string & xmlId )

Return MIDI values of the element with the ID (@xml:id)

RenderToMIDI() must be called prior to using this method.

Parameters

xmlId the ID (@xml:id) of the element being looked for

Returns: A stringified JSON object with the MIDI values

◆ GetNotatedIdForElement()

std::string vrv::Toolkit::GetNotatedIdForElement ( const std::string & xmlId )

Return the ID string of the notated (the original) element.

Parameters

xmlId the ID (@xml:id) of the element being looked for

Returns: An ID string

◆ GetOptions()

std::string vrv::Toolkit::GetOptions ( ) const

Return a dictionary of all the options with their current value.

Returns: A stringified JSON object

◆ GetPageCount()

int vrv::Toolkit::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: The number of pages

◆ GetPageWithElement()

int vrv::Toolkit::GetPageWithElement ( const std::string & xmlId )

Return the page on which the element is the ID (@xml:id) is rendered.

This takes into account the current layout options.

Parameters

xmlId the ID (@xml:id) of the element being looked for

Returns: the page number (1-based) where the element is (0 if not found)

◆ GetResourcePath()

std::string vrv::Toolkit::GetResourcePath ( ) const

Get the resource path for the Toolkit instance.

Remarks: nojs

Returns: A string with the resource path

◆ GetScale()

int vrv::Toolkit::GetScale ( )

inline

Get the scale option.

Remarks: nojs

Returns: the scale option as integer

◆ GetTimeForElement()

int vrv::Toolkit::GetTimeForElement ( const std::string & xmlId )

Return the time at which the element is the ID (@xml:id) is played.

RenderToMIDI() must be called prior to using this method.

Parameters

xmlId the ID (@xml:id) of the element being looked for

Returns: The time in milliseconds

◆ GetTimesForElement()

std::string vrv::Toolkit::GetTimesForElement ( const std::string & xmlId )

Return a JSON object string with the following key values for a given note.

Return scoreTimeOnset, scoreTimeOffset, scoreTimeTiedDuration, realTimeOnsetMilliseconds, realTimeOffsetMilliseconds, realTimeTiedDurationMilliseconds.

Parameters

xmlId the ID (@xml:id) of the element being looked for

Returns: A stringified JSON object with the values

◆ GetVersion()

std::string vrv::Toolkit::GetVersion ( ) const

Return the version number.

Returns: the version number as a string

◆ LoadData()

bool vrv::Toolkit::LoadData ( const std::string & data )

Load a string data with the type previously specified in the options.

By default, the methods try to auto-detect the type.

Parameters

data	A string with the data (e.g., MEI data) to be loaded

Returns: True if the data was successfully loaded

◆ LoadFile()

bool vrv::Toolkit::LoadFile ( const std::string & filename )

Load a file from the file system.

Previously convert UTF16 files to UTF8 or extract files from MusicXML compressed files.

Remarks: nojs

Parameters

filename The filename to be loaded

Returns: True if the file was successfully loaded

◆ LoadZipDataBase64()

bool vrv::Toolkit::LoadZipDataBase64 ( const std::string & data )

Load a MusicXML compressed file passed as base64 encoded string.

Parameters

data	A ZIP file as a base64 encoded string

Returns: True if the data was successfully loaded

◆ LoadZipDataBuffer()

bool vrv::Toolkit::LoadZipDataBuffer	(	const unsigned char *	data,
		int	length
	)

Load a MusicXML compressed file passed as a buffer of bytes.

Parameters

data	A ZIP file as a buffer of bytes
length	The size of the data buffer

Returns: True if the data was successfully loaded

◆ LogRedirectStart()

void vrv::Toolkit::LogRedirectStart ( )

protected

Start capturing std::cerr from an external codebase for redirection to vrv::logBuffer.

Only one capture should be active at a given time. Finish by calling LogRedirectStop.

◆ RedoLayout()

void vrv::Toolkit::RedoLayout ( const std::string & jsonOptions = "" )

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.

Parameters

jsonOptions A stringified JSON object with the action options resetCache: true or false; true by default;

◆ RedoPagePitchPosLayout()

void vrv::Toolkit::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.

◆ RenderData()

std::string vrv::Toolkit::RenderData	(	const std::string &	data,
		const std::string &	jsonOptions
	)

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.

Parameters

data	A string with the data (e.g., MEI data) to be loaded
jsonOptions	A stringified JSON objects with the output options

Returns: The SVG first page as a string

◆ RenderToExpansionMap()

std::string vrv::Toolkit::RenderToExpansionMap ( )

Render a document's expansionMap, if existing.

Returns: The expansionMap as a string

◆ RenderToExpansionMapFile()

bool vrv::Toolkit::RenderToExpansionMapFile ( const std::string & filename )

Render a document's expansionMap and save it to a file.

Remarks: nojs

Parameters

filename The output filename

◆ RenderToMIDI()

std::string vrv::Toolkit::RenderToMIDI ( )

Render the document to MIDI.

Returns: A MIDI file as a base64 encoded string

◆ RenderToMIDIFile()

bool vrv::Toolkit::RenderToMIDIFile ( const std::string & filename )

Render a document to MIDI and save it to the file.

Remarks: nojs

Parameters

filename The output filename

Returns: True if the file was successfully written

◆ RenderToPAE()

std::string vrv::Toolkit::RenderToPAE ( )

Render a document to Plaine & Easie code.

Only the top staff / layer is exported.

Returns: The PAE as a string

◆ RenderToPAEFile()

bool vrv::Toolkit::RenderToPAEFile ( const std::string & filename )

Render a document to Plaine & Easie code and save it to the file.

Only the top staff / layer is exported.

Remarks: nojs

Parameters

filename The output filename

Returns: True if the file was successfully written

◆ RenderToSVG()

std::string vrv::Toolkit::RenderToSVG	(	int	pageNo = `1`,
		bool	xmlDeclaration = `false`
	)

Render a page to SVG.

Parameters

pageNo	The page to render (1-based)
xmlDeclaration	True for including the xml declaration in the SVG output

Returns: The SVG page as a string

◆ RenderToSVGFile()

bool vrv::Toolkit::RenderToSVGFile	(	const std::string &	filename,
		int	pageNo = `1`
	)

Render a page to SVG and save it to the file.

Remarks: nojs

Parameters

filename	The output filename
pageNo	The page to render (1-based)

Returns: True if the file was successfully written

◆ RenderToTimemap()

std::string vrv::Toolkit::RenderToTimemap ( const std::string & jsonOptions = "" )

Render a document to a timemap.

Parameters

jsonOptions A stringified JSON objects with the timemap options

Returns: The timemap as a string

◆ RenderToTimemapFile()

bool vrv::Toolkit::RenderToTimemapFile	(	const std::string &	filename,
		const std::string &	jsonOptions = `""`
	)

Render a document to timemap and save it to the file.

Remarks: nojs

Parameters

filename	The output filename
jsonOptions	A stringified JSON objects with the timemap options

Returns: True if the file was successfully written

◆ ResetXmlIdSeed()

void vrv::Toolkit::ResetXmlIdSeed ( int seed )

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.

Parameters

seed	The seed value for generating the @xml:id values (0 for a time-based random seed)

◆ SaveFile()

bool vrv::Toolkit::SaveFile	(	const std::string &	filename,
		const std::string &	jsonOptions = `""`
	)

Get the MEI and save it to the file.

Remarks: nojs

Parameters

filename	The output filename
jsonOptions	A stringified JSON object with the output options

Returns: True if the file was successfully written

◆ Select()

bool vrv::Toolkit::Select ( const std::string & selection )

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.

Parameters

selection The selection as a stringified JSON object

Returns: True if the selection was successfully parsed or reset

◆ SetInputFrom()

bool vrv::Toolkit::SetInputFrom ( std::string const & inputFrom )

Set the input from option.

Remarks: nojs

Parameters

inputFrom the input from value as string

Returns: True if the option was successfully set

◆ SetOptions()

bool vrv::Toolkit::SetOptions ( const std::string & jsonOptions )

Set option values.

The name of each option to be set is to be given as JSON key.

Parameters

jsonOptions A stringified JSON objects with the output options

Returns: True if the options were successfully set

◆ SetOutputTo()

bool vrv::Toolkit::SetOutputTo ( std::string const & outputTo )

Set the output to option.

Remarks: nojs

Parameters

outputTo the value to output as string

Returns: True if the option was successfully set

◆ SetResourcePath()

bool vrv::Toolkit::SetResourcePath ( const std::string & path )

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.

Remarks: nojs

Parameters

path	The path to the resource directory

Returns: True if the resources was successfully loaded

◆ SetScale()

bool vrv::Toolkit::SetScale ( int scale )

Set the scale option.

Remarks: nojs

Parameters

scale the scale value as integer

Returns: True if the option was successfully set

◆ ValidatePAE()

std::string vrv::Toolkit::ValidatePAE ( const std::string & data )

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.

Parameters

data	A string with the data in JSON or with PAE `@` keys

Returns: A stringified JSON object with the validation warnings or errors

◆ ValidatePAEFile()

std::string vrv::Toolkit::ValidatePAEFile ( const std::string & filename )

Validate the Plaine & Easie code from a file.

The method calls Toolkit::ValidatePAE.

Remarks: nojs

Parameters

filename The filename to be validated

Returns: A stringified JSON object with the validation warnings or errors

The documentation for this class was generated from the following file:

toolkit.h

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ Toolkit()

Member Function Documentation

◆ ConvertHumdrumToHumdrum()

◆ ConvertHumdrumToMIDI()

◆ ConvertMEIToHumdrum()

◆ Edit()

◆ EditInfo()

◆ GetAvailableOptions()

◆ GetDefaultOptions()

◆ GetDescriptiveFeatures()

◆ GetElementAttr()

◆ GetElementsAtTime()

◆ GetExpansionIdsForElement()

◆ GetHumdrum()

◆ GetHumdrumFile()

◆ GetID()

◆ GetLog()

◆ GetMEI()

◆ GetMIDIValuesForElement()

◆ GetNotatedIdForElement()

◆ GetOptions()

◆ GetPageCount()

◆ GetPageWithElement()

◆ GetResourcePath()

◆ GetScale()

◆ GetTimeForElement()

◆ GetTimesForElement()

◆ GetVersion()

◆ LoadData()

◆ LoadFile()

◆ LoadZipDataBase64()

◆ LoadZipDataBuffer()

◆ LogRedirectStart()

◆ RedoLayout()

◆ RedoPagePitchPosLayout()

◆ RenderData()

◆ RenderToExpansionMap()

◆ RenderToExpansionMapFile()

◆ RenderToMIDI()

◆ RenderToMIDIFile()

◆ RenderToPAE()

◆ RenderToPAEFile()

◆ RenderToSVG()

◆ RenderToSVGFile()

◆ RenderToTimemap()

◆ RenderToTimemapFile()

◆ ResetXmlIdSeed()

◆ SaveFile()

◆ Select()

◆ SetInputFrom()

◆ SetOptions()

◆ SetOutputTo()

◆ SetResourcePath()

◆ SetScale()

◆ ValidatePAE()

◆ ValidatePAEFile()