LibMusicXML 3.22
Building a MusicXML representations

Functions

EXP TFactory factoryOpen ()
 Creates a new MusicXML factory.
EXP void factoryClose (TFactory f)
 Close a MusicXML factory.
EXP void factoryPrint (TFactory f, std::ostream &out)
 Print the MusicXML representation to stream.
EXP void factoryHeader (TFactory f, const char *worknumber, const char *worktitle, const char *movementnumber, const char *movementtitle)
 Creates header information.
EXP void factoryCreator (TFactory f, const char *c, const char *type)
 Creates creator information.
EXP void factoryRights (TFactory f, const char *r, const char *type)
 Creates rights information.
EXP void factoryEncoding (TFactory f, const char *software)
 Creates encoding information.
EXP void factoryAddPart (TFactory f, TElement part)
 Adds a part.
EXP void factoryAddGroup (TFactory f, int number, const char *name, const char *abbrev, bool groupbarline, TElement *parts)
 Adds parts grouped in a 'part-group'.
EXP void factoryAddElement (TFactory f, TElement elt, TElement subelt)
 Adds an element to another element.
EXP void factoryAddElements (TFactory f, TElement elt, TElement *subelts)
 Adds a set of elements to another element.
EXP void factoryAddAttribute (TFactory f, TElement elt, TAttribute attr)
 Adds an attribute to an element.
EXP TElement factoryScorepart (TFactory f, const char *id, const char *name, const char *abbrev)
 Creates a 'score-part' element.
EXP TElement factoryPart (TFactory f, const char *id)
 Creates a 'part' element.
EXP TElement factoryMeasure (TFactory f, int number)
 Creates a 'measure' element.
EXP TElement factoryMeasureWithAttributes (TFactory f, int number, const char *time, const char *clef, int line, int key, int division)
 Creates a 'measure' element with a set of attributes.
EXP TElement factoryNote (TFactory f, const char *step, float alter, int octave, int duration, const char *type)
 Creates a note.
EXP TElement factoryDynamic (TFactory f, int type, const char *placement)
 Creates a dynamics element containing a dynamic type.
EXP TElement factoryBarline (TFactory f, const char *location, const char *barstyle, const char *repeat)
 Creates a barline element with the corresponding sub-elements.
EXP void factoryTuplet (TFactory f, int actual, int normal, TElement *notes)
 Makes a tuplet with notes.
EXP void factoryTie (TFactory f, TElement from, TElement to)
 Tie two notes.
EXP void factoryNotation (TFactory f, TElement elt, TElement notation)
 Add an element to a note notations element.
EXP void factoryArticulation (TFactory f, TElement elt, TElement articulation)
 Add an articulation to a note.
EXP TElement factoryRest (TFactory f, int duration, const char *type)
 Creates a rest.
EXP void factoryChord (TFactory f, TElement *notes)
 Makes a chord from the gievn notes.
EXP TElement factoryElement (TFactory f, int type)
 Creates an arbitrary MusicXML element.
EXP TElement factoryStrElement (TFactory f, int type, const char *value)
 Creates an arbitrary MusicXML element with a string value.
EXP TElement factoryIntElement (TFactory f, int type, int value)
 Creates an arbitrary MusicXML element with an integer value.
EXP TElement factoryFloatElement (TFactory f, int type, float value)
 Creates an arbitrary MusicXML element with a float value.
EXP TAttribute factoryStrAttribute (TFactory f, const char *name, const char *value)
 Creates an arbitrary attribute with a string value.
EXP TAttribute factoryIntAttribute (TFactory f, const char *name, int value)
 Creates an arbitrary attribute with an integer value.
EXP TAttribute factoryFloatAttribute (TFactory f, const char *name, float value)
 Creates an arbitrary attribute with a float value.
EXP void factoryFreeElement (TFactory f, TElement elt)
 Frees a previously allocated element.
EXP void factoryFreeAttribute (TFactory f, TAttribute attr)
 Frees a previously allocated attribute.

Detailed Description

The MusicXMl factory API.

The factory provides a high level API to build a MusicXML tree but gives also a low level access to the music representation. The idea is to make simple scores easy to build while complex scores accessible with a godd knowledge of the MusicXML format. The main feature of the factory is the automatic sort of the representation according to the dtd. Actually, only a small subset of the containers is not handled due to forms like (A, B)* where ordering should be specified at element construction. These containers are:

Note: for many elements (e.g. the measure element) the dtd do not impose an order. They have a form like ( A | B | C )* and thus any order is legal and the corresponding elements are not sorted. However, the elements semantic may require a given order, for example, the division attribute may be expected before a first duration element is encountered. It's the encoding application responsibility to build the elements with the appropriate order. These elements are:

Note concerning the memory management: all the elements or attributes allocated using the factory API (functions that return a TElement or a TAttribute) should be released using factoryFreeElement or factoryFreeAttribute unless they are added to the other elements (factoryAddElement or factoryAddAttribute) or to the music description (factoryAddPartlist)

Overview of the format and API

A MusicXML partwise score structure is basically made of a header containing various information and a require parts list, followed by a list of parts, including measures, made of various 'music data'.

    'partwise score'  := 'opt. header' 'part-list' 'part'  ...  'part'
    'part'            := 'measure' ... 'measure'
    'measure'         := 'music-data' ... 'music-data'
  

The factory API reflects this structure:

Function Documentation

◆ factoryAddAttribute()

EXP void factoryAddAttribute ( TFactory f,
TElement elt,
TAttribute attr )
Parameters
fthe MusicXML factory
eltan element.
attrthe attribute to be added.
Note
once added to an element, an attribute is automatically released when the element is released.

◆ factoryAddElement()

EXP void factoryAddElement ( TFactory f,
TElement elt,
TElement subelt )
Parameters
fthe MusicXML factory
elta container element.
subeltthe element added to the container element.
Note
once added to an element, an element is automatically released when its container element is released.

◆ factoryAddElements()

EXP void factoryAddElements ( TFactory f,
TElement elt,
TElement * subelts )
Parameters
fthe MusicXML factory
eltthe destination container.
subeltsa null terminated array of elements.
Note
once added to an element, an element is automatically released when its container element is released.

◆ factoryAddGroup()

EXP void factoryAddGroup ( TFactory f,
int number,
const char * name,
const char * abbrev,
bool groupbarline,
TElement * parts )
Parameters
fthe MusicXML factory
numberthe group number
namethe group name
abbrevthe group abbreviated name
groupbarlinea boolean for group barlines
partsa null terminated array of parts to be grouped
Note
you should refer to the MusicXML dtd for more information about parts groups.

◆ factoryAddPart()

EXP void factoryAddPart ( TFactory f,
TElement part )
Parameters
fthe MusicXML factory
partactually a 'score-part' or a 'part' element. Pushed to the adequate location, depending on the element type.

◆ factoryArticulation()

EXP void factoryArticulation ( TFactory f,
TElement elt,
TElement articulation )
Parameters
fthe MusicXML factory
elta note element
articulationan articulation element

◆ factoryBarline()

EXP TElement factoryBarline ( TFactory f,
const char * location,
const char * barstyle,
const char * repeat )
Parameters
fthe MusicXML factory
locationthe barline location attribute. A null value prevents the attribute creation.
barstyleoptional optional bar-style element. Should be in regular, dotted, dashed, heavy, light-light, light-heavy, heavy-light, heavy-heavy, tick (a short stroke through the top line), short (a partial barline between the 2nd and 4th lines), and none. A null value prevents the barstyle creation.
repeatoptional repeat element with the corresponding required direction attribute. Should be in backward or forward. A null value prevents the repeat creation.

◆ factoryChord()

EXP void factoryChord ( TFactory f,
TElement * notes )
Parameters
fthe MusicXML factory
notesa null terminated list of notes. Actually, chords are denoted by a 'chord' element included to the note element, indicating that the note is an additional chord tone with the preceding note. For convenience, all the chord notes should be given to the function but the first one is skipped when adding the 'chord' element.

◆ factoryClose()

EXP void factoryClose ( TFactory f)
Parameters
fthe MusicXML factory

◆ factoryCreator()

EXP void factoryCreator ( TFactory f,
const char * c,
const char * type )
Parameters
fthe MusicXML factory
cthe creator name (should not be null or empty)
typethe creator type, corresponds to the 'type' attribute. A null pointer prevents the attribute creation.

◆ factoryDynamic()

EXP TElement factoryDynamic ( TFactory f,
int type,
const char * placement )
Parameters
fthe MusicXML factory
typethe dynamic type
placementoptional placement dynamics attribute. Should be in "above" or "below". A null value prevents the attribute creation.

◆ factoryElement()

EXP TElement factoryElement ( TFactory f,
int type )
Parameters
fthe MusicXML factory
typethe element type.

◆ factoryEncoding()

EXP void factoryEncoding ( TFactory f,
const char * software )
Parameters
fthe MusicXML factory
softwarecorresponds to the 'software' encoding element. Uses the default when null.
Note
The encoding element is automatically created with the current 'encoding-date'.

◆ factoryFloatAttribute()

EXP TAttribute factoryFloatAttribute ( TFactory f,
const char * name,
float value )
Parameters
fthe MusicXML factory
namethe attribute name.
valuethe attribute value.

◆ factoryFloatElement()

EXP TElement factoryFloatElement ( TFactory f,
int type,
float value )
Parameters
fthe MusicXML factory
typethe element type.
valuethe element value.

◆ factoryFreeAttribute()

EXP void factoryFreeAttribute ( TFactory f,
TAttribute attr )
Parameters
fthe MusicXML factory
attran attribute.
Note
you must not free an attribute that has been added to an element.
See also
factoryAddAttribute

◆ factoryFreeElement()

EXP void factoryFreeElement ( TFactory f,
TElement elt )
Parameters
fthe MusicXML factory
eltan element.
Note
you must not free an element that has been added to an element.
See also
factoryAddElement

◆ factoryHeader()

EXP void factoryHeader ( TFactory f,
const char * worknumber,
const char * worktitle,
const char * movementnumber,
const char * movementtitle )
Parameters
fthe MusicXML factory
worknumbercorresponds to the 'work-number' element
worktitlecorresponds to the 'work-titel' element
movementnumbercorresponds to the 'movement-number' element
movementtitlecorresponds to the 'movement-title' element

A null pointer prevents the corresponding element creation.

◆ factoryIntAttribute()

EXP TAttribute factoryIntAttribute ( TFactory f,
const char * name,
int value )
Parameters
fthe MusicXML factory
namethe attribute name.
valuethe attribute value.

◆ factoryIntElement()

EXP TElement factoryIntElement ( TFactory f,
int type,
int value )
Parameters
fthe MusicXML factory
typethe element type.
valuethe element value.

◆ factoryMeasure()

EXP TElement factoryMeasure ( TFactory f,
int number )
Parameters
fthe MusicXML factory
numberthe required 'number' attribute

◆ factoryMeasureWithAttributes()

EXP TElement factoryMeasureWithAttributes ( TFactory f,
int number,
const char * time,
const char * clef,
int line,
int key,
int division )
Parameters
fthe MusicXML factory
numberthe required 'number' attribute
timethe time signature encoded as a string with the form "n/n". A null pointer prevents the 'time' element creation.
clefthe clef in "G", "F", "C", "percussion", "TAB" or "none"
linean optional clef line (0 prevents the line element creation)
keyan optional key signature (0 prevents the key element creation)
divisionan optional divisions element (0 prevents the divisions element creation)

◆ factoryNotation()

EXP void factoryNotation ( TFactory f,
TElement elt,
TElement notation )
Parameters
fthe MusicXML factory
elta note element
notationan element to add to the note notations

◆ factoryNote()

EXP TElement factoryNote ( TFactory f,
const char * step,
float alter,
int octave,
int duration,
const char * type )
Parameters
fthe MusicXML factory
stepthe pitch step using letters A through G
alterchromatic alteration in number of semitones (0 prevents the alter element creation)
octavea number in 0 to 9, where 4 indicates the octave started by middle C.
durationthe sounding duration (in divisions count) (0 prevents the duration element creation)
typethe graphic note type; in 256th, 128th, 64th, 32nd, 16th, eighth, quarter, half, whole, breve or long

◆ factoryOpen()

EXP TFactory factoryOpen ( )
Returns
an opaque reference to the factory.

◆ factoryPart()

EXP TElement factoryPart ( TFactory f,
const char * id )
Parameters
fthe MusicXML factory
idthe required 'id' attribute

◆ factoryPrint()

EXP void factoryPrint ( TFactory f,
std::ostream & out )
Parameters
fthe MusicXML factory
outthe output stream

◆ factoryRest()

EXP TElement factoryRest ( TFactory f,
int duration,
const char * type )
Parameters
fthe MusicXML factory
durationthe sounding duration (in divisions count) (0 prevents the duration element creation)
typethe graphic note type; in 256th, 128th, 64th, 32nd, 16th, eighth, quarter, half, whole, breve or long

◆ factoryRights()

EXP void factoryRights ( TFactory f,
const char * r,
const char * type )
Parameters
fthe MusicXML factory
rthe rights string (should not be null or empty)
typethe rights type, corresponds to the 'type' attribute. A null pointer prevents the attribute creation.

◆ factoryScorepart()

EXP TElement factoryScorepart ( TFactory f,
const char * id,
const char * name,
const char * abbrev )
Parameters
fthe MusicXML factory
idthe required 'id' attribute
namethe part name
abbrevthe part abbreviated named

◆ factoryStrAttribute()

EXP TAttribute factoryStrAttribute ( TFactory f,
const char * name,
const char * value )
Parameters
fthe MusicXML factory
namethe attribute name.
valuethe attribute value.

◆ factoryStrElement()

EXP TElement factoryStrElement ( TFactory f,
int type,
const char * value )
Parameters
fthe MusicXML factory
typethe element type.
valuethe element value.

◆ factoryTie()

EXP void factoryTie ( TFactory f,
TElement from,
TElement to )
Parameters
fthe MusicXML factory
fromthe tie start note
tothe tie end note
Note
: factoryTie creates the corresponding tie and tied elements.

◆ factoryTuplet()

EXP void factoryTuplet ( TFactory f,
int actual,
int normal,
TElement * notes )
Parameters
fthe MusicXML factory
actualthe actual notes count
normalthe normal notes count
notesa null terminated list of notes.
Note
: factoryTuplet creates the corresponding time-modification element for each note and the tuplet elements for the first and last notes of the list.