SMApplyToAllSelectedSymbols(Score score, function processFunc, boolean excludeSpecials)

Apply a function to all selected symbols, individually selected or continous selection.

MSLibrary's ApplyToAllSelectedSymbols(...) function doesn't handle individually selected symbols, and browse from last to first, which is safe for symbol deletion. This customized browse selected notes on all staves from first to last, not convenient for deletion. It can skips ghost rests and special symbols, handles individual and continuous (range) selection.

Return

int: Number of processed symbols

Error

if score is not a Score or processFunc is not a function.

See

SMApplyToAllSymbols

SMApplyToAllSymbols(Score score, staves, int firstBar, int lastBar, function processFunc, boolean excludeSpecials)

Apply a function to all symbols in the score, or staff, or in a range of bars.

Return

int: Number of processed symbols

Error

if arguments have wrong types.

See

SMApplyToAllSelectedSymbols

PlayNote(Symbol symbol)

Plays a note, shortcut and fix for Staff.PlayNotes().

Play only one note (the symbol parameter), in its context (tempo at its Time position), duration, velocity and pitch. Fix the no-sound bug when pitch==0 on grid drum staves.

SMPitchToString(int pitch, int preferredAccidental, int compatible, string preferredNote)

Extension and bugfix for builtin PitchToString function.

• Allow pitches out of 0..127 bounds, but keep in mind that HA can't handle them!
• PitchToString(11) gives 11, SMPitchToString(11) returns B-1

Does not handle microtonal accidentals.

Returns

string: Anglo-saxon note name followed by octave, e.g. "Ab5".

int: Accidental for the note, one of MSDefine NATURAL,FLAT,SHARP,DOUBLE_FLAT,DOUBLE_SHARP constants.

SMStringToPitch(string name)

Extension and bugfix for builtin StringToPitch function.

Does not handle microtonal accidentals.

• Allow pitches out of 0..127 bounds
• StringToPitch("B-1") gives the strange 71 result, SMStringToPitch("B-1") returns 11
• Handles double-sharp (## or x) and double-flat (bb)

Returns

int: May be out of 0..127 range.

int: Preferred accidental, one of AUTO, SHARP, FLAT... constants from MSDefine

CopyOrnaments(Symbol from, Symbol to)

Copy all ornaments from a Symbol to another one.

Returns

int: Number of copied ornaments

int: Number of copy errors

SetGhostRestDisplayMode(Score score, int grdm)

Set the ghost rest display mode for all staves in all views.

SearchNextSymbol(Score score, staves, from, function matcher)

Search next symbol with custom matcher function, in whole score or a list of staves, at a time position or after a symbol.

Returns

Symbol: First matching symbol at time from or after from symbol, nil if not found (end of music is reached)

Staff: The staff containing the returned symbol, or nil if not found

Example

 local m = function(sym) return sym.IsRest; end
 local rest, staff = SearchNextSymbol(FrontScore(), nil, 0, m)
 local cpt = 0
 while rest do
   cpt = cpt + 1
   print("#"..cpt, "staff #"..staff.Index, "time="..rest.Time)
   rest, staff = SearchNextSymbol(FrontScore(), nil, rest, m)
 end

SearchPreviousSymbol(Score score, staves, from, function matcher)

Search previous symbol with custom matcher function, in whole score or a list of staves, at a time position or before a symbol.

Returns

Symbol: First matching symbol at time from or before from symbol, nil if not found (start of music is reached)

Staff: The staff containing the returned symbol, or nil if not found

Example

 local m = function(sym) return sym.IsRest; end
 local rest, staff = SearchPreviousSymbol(FrontScore(), nil, nil, m)
 local cpt = 0
 while rest do
   cpt = cpt + 1
   print("#"..cpt, "staff #"..staff.Index, "time="..rest.Time)
   rest, staff = SearchPreviousSymbol(FrontScore(), nil, rest, m)
 end

SymbolGetAccidental(Symbol sym)

Return accidental data for a Symbol, handles microtonals.

Return nil if sym is not a note.

Returns

int: Accidental constant from MSDefine (except AUTO). If the value is greater or equal than 1000, it is a microtonal accidental, see ORNAMENT_MA_* constants.

int: Accidental value in 100th of semitone.

boolean: true if accidental is visible, false if invisible

boolean: true if accidental is cautionary, false if essential. This may be true even if invisible, meaning that deleting this accidental will not change the note pitch.

string: Source of the accidental: "note", "bar" (previous note in the bar), "key" (key signature).

SymbolSetAccidentalVisibility(Symbol sym, boolean visible)

Change the accidental visibility of a Symbol.

Handles microtonal accidentals.

Return

boolean: true if changes were applied, false if not, nil if sym is not a note.

SymbolIsMicrotonalAccidental(Symbol sym)

Is the note played with a microtonal accidental?

Return

boolean: true if sym or a previous note in the same bar has one Ornament of a microtonal accidental, or if the last specify a microtonal accidental for that note.

SymbolIsTieVisible(Symbol note)

Is the note tied?

A tie is a kind of "slur" joining two notes head. In Harmony, it is considered as a single note with a split duration.
Two rests may be "tied", without curve, this function ignore rests.

Return

boolean: true if note is tied with next note.

See

Symbol Symbol.GetTiedElements(...)

SymbolsAreContiguous(Symbol a, Symbol b)

Tell if two Symbols are contiguous.

Both can be in chord, this can produce a.Next ~= b.
If both are quarters, and while a is played, 2 eights are also played, then b is considered as contiguous. If both have same pitch, a and b can be tied..
Another way to say: a.Time + a.Duration == b.Time and both are on the same staff.

Return

boolean: true if a and b are contiguous

See

SymbolsCanBeTied

SymbolsCanBeTied(Symbol ...)

Symbols can be tied if they are all contiguous and have same played and displayed pitch.

Return

boolean: true if a tie can join ALL notes in argument

SetSlurDirection(Symbol note, boolean isUp)

Set slur direction up or down.

The slur is set to be adjusted automatically.

Return

boolean: true if the slur has been modified

SymbolIsDotted(Symbol sym)

Tell if the Symbol is displayed with dot(s).

If sym is tied (sym.SplitDuration ~= 0), then returns true if at least one of the tied notes is dotted.
-- If sym has a slur instead of a tie, only sym is checked, as the slur target is another Symbol.

Return

boolean: true if sym requires dot(s) to display its duration on the score.

GetSymbolsInChord(Symbol sym)

Return all symbols in chord with sym (included), in its staff and merged ones.

Symbols are sorted by staff index, then their internal order (generally from higher to lower). This is not guaranteed that symbols are all ordered from higher to lower. Rests are included.

Returns

table: Table of Symbol in chord with sym

int: Index of sym in the table.

See

GetOverlappingSymbols

GetOverlappingSymbols(Symbol sym)

Get all symbols (notes and rests) from merged staves, which begin time is before sym end time, and end time is after sym begin time.

This means: if sym is a "drone" note in first merged staff, this will return the drone + the melody in the second merged staff.

If the drone is a serie of notes linked by a slur, then the function must be called for each note of the serie.
If all notes of the drone are tied, it's considered as only one note.

This function may help analysis algorithm, as well as for ties/slurs/stems direction calculation.

There is no guarantee of sorted results: it will be mostly sorted by staff index, time, higher to lower in chord.

Returns

table: Table of Symbol which playing time and duration overlap sym playing time.

int: Index of sym in the table.

See

GetSymbolsInChord

CompareSymbolsByPitch(Symbol a, Symbol b)

Compare two Symbols by pitch, then displayed height.

Return

int:

• Negative number if a is lower than b,
• Positive if a is higher than b,
• Zero if a and b have same pitch and displayed height.

TheoryStemsDirection(string case, table notes)

Get the stem direction a group of beamed notes, or a chord, would have in normal conditions.

Stem direction is determinated by the note that is far than the middle line. In case of equal distance between the far top and far bottom, chord has stems up, beamed notes have stems down.

Return

int: STEM_UP or STEM_DOWN, nil if no symbol args are notes.