Score_cwn (BandM signal & music)

java.lang.Object
- eu.bandm.music.top.Score_cwn

```
public class Score_cwn
extends Object
```
This class realizes a first simple example instantiation of a tscore TimeScape for representing "common western notation" / "CWN" musical scores. One(1) instance of this class corresponds to one(1) "PART" in a tscore file.
It imposes the following properties:
- The TpTop top level time points are labeled mostly with *integral* numbers, in continuously increasing order. These can be seen as "measure numbers", but may be based anywhere. Every segment between two adjacent top level Tp labels is meant as one musical measure. Most measures are "complete", but there may be "incomplete" measures, eg. for upbeats and for to carry repetition bars.
- There is one dedicated global metric voice named "M". Its main parameter is the metrum. There must be at least ONE event at the beginning of the score, on the very first event, which specifies the metrum of the first bar.
- Metrum specifications are only allowed on the "beat one" of each measure, except in the very first measure.
- Metrum specifications are firstly only "names" for meter. At each first appearance, a second parameter track named "mtree" must give a definition according to the syntax defined in MetricTree.
- This global voice "M" may have a second parameter track, called "tempo", or further tracks for overall parameters like "general espression directives", etc.
- All further voices hold the data for some instrument taking part in the music. They use some pitch class with "running octave" as a their main parameter.
- They may have a second track "nota" containing notation specs, like clefs and keys, and/or a track "artik" for articulation etc. The very first event must have a nota-event specifying the key. ((FIXME schlagzeug?Horn?))
- "volume" (aka "loudness", "intensity", "dynamics") is STILL MISSING FIXME.

Field Summary

Fields
Modifier and Type	Field and Description
`static Function3<Comparator<? super BigDecimal>,BigDecimal,BigDecimal,String>`	`checkDistance` Checks that two consecutive time points are (a) strictly increasing, but (b) not more than "1.0" distant.
`(package private) String`	`clefPrefix` Prefix in the source text for a clef indication.
`SortedMap<BigDecimal,TpTop>`	`decimal2tpTop` Maps bar numbers / measure numbers to tscore top-leve time points.
`(package private) Map<Event,Artikulation>`	`event2artikulation` Artikulation parsed from the param track called `paramname_articulation`.
`Map<Event,ClefUsage>`	`event2clefUsage` Maps events of sounding voices to a clef change, from param track .
`(package private) Map<Event,Tp>`	`event2endtp` Maps events to their end time point.
`(package private) Map<Event,FunctionalKey>`	`event2key` Maps events of sounding voices to a key change, from param track .
`Map<Event,String>`	`event2lowerText` Additional text to be printed below the rendering of a note.
`(package private) Map<Event,Ornament>`	`event2ornamentation` Ornamentation parsed from the param track called `paramname_articulation`.
`Map<Event,PitchAndOctave<OctaveRegister,FunctionalPitchModOctave>>`	`event2pitch` Maps voice events to one nominal pitch.
`(package private) Map<Event,Tempo>`	`event2tempo` Maps events from the global "M" voice to a tempo indication.
`Map<Event,String>`	`event2upperText` Additional text to be printed above the rendering of a note.
`Map<Event,String>`	`event2verba` Maps events of a sounding voice to a lyric syllable.
`(package private) Map<Event,String>`	`eventHasCautionaryAccidental` Whether a cautionary accidental is requested explicitly by the tscore source, in the param track called `paramname_nota`.
`(package private) Map<Event,String>`	`eventHasFullAccidental` Whether an accidental is requested explicitly by the tscore source, in the param track called `paramname_nota`.
`TpTop`	`firstTp` The very first time point of the score.
`Map<Event,String>`	`holds` Marks voice events as being a "hold", which is an unaltered prolongation of the preceding event
`(package private) String`	`language` Human language in which the tscore input will be interpreted.
`TpTop`	`lastTp` The very last time point of the score.
`@Opt Rational`	`lastTpTop_rat` The rational time point of the very last top level tscore time point.
`(package private) Multimap<String,EventSet>`	`legatos` Event sets standing for legato arcs, parsed from the param track called `paramname_articulation`.
`MeasureCollector<MetrumName>`	`measures` Collector for the meter names and duration indications in the main metric voice "M".
`static Modifiers`	`modifiers` Modifiers controlling the parsing process.
`(package private) Multimap<String,EventSet>`	`motifs` Groups of events collected to represent "analytical brackets" for motifs, etc.
`(package private) SimpleMessage.Sender<XMLDocumentIdentifier>`	`msg` Only for conveniently construction messages and sending them to `msgr`
`(package private) MessageReceiver<SimpleMessage<XMLDocumentIdentifier>>`	`msgr` The drain for all messags.
`protected MTreeCollector<MetrumName>`	`mTreeCollector` Collector for the meter specifications in the main meter voice (mandatory) and in sounding voice (optional).
`static String`	`paramname_articulation` Name of the parameter track of a normal voice carrying articulation marks.
`static String`	`paramname_metric` Metric specifications are the main events in the global metric voice.
`static String`	`paramname_mtree` Name of the parameter track of the main metric voice with metric tree formulas.
`static String`	`paramname_nota` Name of the parameter track of a normal voice carrying notation (meta-) information.
`static String`	`paramname_verba` Name of the parameter track of a normal voice carrying "lyrics" / text syllables.
`static Translet.Parser<BigDecimal>`	`parse_barNumber` Parser for measure numbers accept a non-negative integer, and maybe a decimal point with a fractional part.
`Part`	`part` The score data as (in most cases) parsed by tscore.
`Map<Event,String>`	`pause` Marks voice events as being a pause.
`Multimap<Rational,Tp>`	`rat2tp` Inverse of `tp2rat`.
`Map<Tp,Rational>`	`tp2rat` Maps all tscore time points to rational numbers which correspond to the musical time relative to the start of the very first event.
`(package private) Map<TpTop,BigDecimal>`	`tpTop2decimal` Inverse of `decimal2tpTop`.
`Vox`	`voiceMetric` The global voice vor metric, tempo, and global expression information.
`static String`	`voicename_metric` The name of the mandatory global "metric" voice.

Constructor Summary

Constructors
Constructor and Description
`Score_cwn(Part part, String lang, MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr)` Service providing main factory method for converting a particular PART of a TimeScape.
`Score_cwn(TimeScape ts, String lang, MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr)` Process THE ONE AND ONLY part of the TimeScape.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addCompleteMeasure(int den, int nom, @Opt MTreeSpec mt)` Append at the end of all measure specifications a new measure with the given name (looking like "den/nom") and MTree specification.
`void`	`addCompleteMeasure(MetrumName name, @Opt MTreeSpec mt)` Append at the end of all measure specifications a new measure with the given name (looking like "den/nom") and MTree specification.
`void`	`dumpVoice(PrintStream ps, Vox voice)` Debugging print which prints only the time point and the pitch, if it is not the metric voice.
`Tp`	`makeTp(Rational when, Location<XMLDocumentIdentifier> origLoc)` Add a new time point at the given rational time value, if no such already exists.
`static Map<String,Score_cwn>`	`multipleParts(TimeScape ts, String lang, MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr)` Service providing main factory method for converting all "PART" sections in the given tscore input Timescape.
`int`	`normalizeEvents_midi_PPQ(Vox voice, boolean mergePauses, List<Event> events, List<QualifiedRational> evStarts, List<Boolean> repeats)` Execute `normalizeEvents(Vox,boolean,List,List,List)`, but return the lcm of all duration numerators in the form required for Midi "Parts per quarter".
`PrimeFactors`	`normalizeEvents(Vox voice, boolean mergePauses, List<Event> events, List<QualifiedRational> evStarts, List<Boolean> repeats)` Step through the voice, remove "hold" symbols by the prolongating the preceding (sounding) event, merge adjacent "pause" events, and calculate the required sub-division of a quarter for the midi realization of all.
`void`	`update()` Translate untyped tscore data into semantically sensible "common western notation", and verify that all constraints are met.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - msgr
```
final MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr
```
    The drain for all messags.
  - msg
```
final SimpleMessage.Sender<XMLDocumentIdentifier> msg
```
    Only for conveniently construction messages and sending them to msgr
  - part
```
public final Part part
```
    The score data as (in most cases) parsed by tscore. It is needed as public for all programs which synthesize scores.
  - language
```
final String language
```
    Human language in which the tscore input will be interpreted. Esp. the pitch classes and key names.
  - modifiers
```
public static final Modifiers modifiers
```
    Modifiers controlling the parsing process.
  - voicename_metric
```
public static final String voicename_metric
```
    The name of the mandatory global "metric" voice.
    
    See Also:
    
    Constant Field Values
  - paramname_metric
```
public static final String paramname_metric
```
    Metric specifications are the main events in the global metric voice. Therefore they have no explicit parameter name, but Event.main_parameter_name.
    
    See Also:
    
    Constant Field Values
  - paramname_mtree
```
public static final String paramname_mtree
```
    Name of the parameter track of the main metric voice with metric tree formulas.
    
    See Also:
    
    Constant Field Values
  - paramname_articulation
```
public static final String paramname_articulation
```
    Name of the parameter track of a normal voice carrying articulation marks.
    
    See Also:
    
    Constant Field Values
  - paramname_nota
```
public static final String paramname_nota
```
    Name of the parameter track of a normal voice carrying notation (meta-) information.
    
    See Also:
    
    Constant Field Values
  - paramname_verba
```
public static final String paramname_verba
```
    Name of the parameter track of a normal voice carrying "lyrics" / text syllables.
    
    See Also:
    
    Constant Field Values
  - parse_barNumber
```
public static final Translet.Parser<BigDecimal> parse_barNumber
```
    Parser for measure numbers accept a non-negative integer, and maybe a decimal point with a fractional part.
  - checkDistance
```
public static final Function3<Comparator<? super BigDecimal>,BigDecimal,BigDecimal,String> checkDistance
```
    Checks that two consecutive time points are (a) strictly increasing, but (b) not more than "1.0" distant.
  - voiceMetric
```
public Vox voiceMetric
```
    The global voice vor metric, tempo, and global expression information. Will be identified by its name voicename_metric.
  - decimal2tpTop
```
public final SortedMap<BigDecimal,TpTop> decimal2tpTop
```
    Maps bar numbers / measure numbers to tscore top-leve time points.
  - tpTop2decimal
```
final Map<TpTop,BigDecimal> tpTop2decimal
```
    Inverse of decimal2tpTop.
  - tp2rat
```
public final Map<Tp,Rational> tp2rat
```
    Maps all tscore time points to rational numbers which correspond to the musical time relative to the start of the very first event. This this time point notion is notrelated to the measure numbers.
  - firstTp
```
public TpTop firstTp
```
    The very first time point of the score. (Must be a toplevel time point due to the syntax of the general tscore format.)
  - lastTp
```
public TpTop lastTp
```
    The very last time point of the score. This must not carry an event but mark the end-time of the very last event in any voice. (Must be a toplevel time point due to the syntax of the general tscore format.)
  - lastTpTop_rat
```
@Opt
public @Opt Rational lastTpTop_rat
```
    The rational time point of the very last top level tscore time point. See tp2rat.
  - event2tempo
```
final Map<Event,Tempo> event2tempo
```
    Maps events from the global "M" voice to a tempo indication.
  - rat2tp
```
public final Multimap<Rational,Tp> rat2tp
```
    Inverse of tp2rat.
  - event2endtp
```
final Map<Event,Tp> event2endtp
```
    Maps events to their end time point.
  - pause
```
public final Map<Event,String> pause
```
    Marks voice events as being a pause.
  - holds
```
public final Map<Event,String> holds
```
    Marks voice events as being a "hold", which is an unaltered prolongation of the preceding event
  - event2pitch
```
public final Map<Event,PitchAndOctave<OctaveRegister,FunctionalPitchModOctave>> event2pitch
```
    Maps voice events to one nominal pitch. (FIXME: CHORDS with MORE THAN ONE pitch are currently not supported.
  - eventHasFullAccidental
```
final Map<Event,String> eventHasFullAccidental
```
    Whether an accidental is requested explicitly by the tscore source, in the param track called paramname_nota. The terminal symbol is fixed to "!", which is inspired by lilypond.
    FIXME should be for PITCH, not for EVENT!! Current solution ASSUMES each Event has only ONE(1) Pitch!!
  - eventHasCautionaryAccidental
```
final Map<Event,String> eventHasCautionaryAccidental
```
    Whether a cautionary accidental is requested explicitly by the tscore source, in the param track called paramname_nota. The terminal symbol is fixed to "?", which is inspired by lilypond.
    FIXME should be for PITCH, not for EVENT!! Current solution ASSUMES each Event has only ONE(1) Pitch!!
  - event2artikulation
```
final Map<Event,Artikulation> event2artikulation
```
    Artikulation parsed from the param track called paramname_articulation.
  - event2ornamentation
```
final Map<Event,Ornament> event2ornamentation
```
    Ornamentation parsed from the param track called paramname_articulation.
  - legatos
```
final Multimap<String,EventSet> legatos
```
    Event sets standing for legato arcs, parsed from the param track called paramname_articulation.
  - clefPrefix
```
final String clefPrefix
```
    Prefix in the source text for a clef indication.
    
    See Also:
    
    Constant Field Values
  - event2clefUsage
```
public final Map<Event,ClefUsage> event2clefUsage
```
    Maps events of sounding voices to a clef change, from param track .
  - event2key
```
final Map<Event,FunctionalKey> event2key
```
    Maps events of sounding voices to a key change, from param track .
  - motifs
```
final Multimap<String,EventSet> motifs
```
    Groups of events collected to represent "analytical brackets" for motifs, etc. From param track paramname_nota.
  - event2lowerText
```
public final Map<Event,String> event2lowerText
```
    Additional text to be printed below the rendering of a note.
  - event2upperText
```
public final Map<Event,String> event2upperText
```
    Additional text to be printed above the rendering of a note.
  - event2verba
```
public final Map<Event,String> event2verba
```
    Maps events of a sounding voice to a lyric syllable.
  - measures
```
public final MeasureCollector<MetrumName> measures
```
    Collector for the meter names and duration indications in the main metric voice "M".
  - mTreeCollector
```
protected MTreeCollector<MetrumName> mTreeCollector
```
    Collector for the meter specifications in the main meter voice (mandatory) and in sounding voice (optional).
- Constructor Detail
  - Score_cwn
```
public Score_cwn(Part part,
                 String lang,
                 MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr)
```
    Service providing main factory method for converting a particular PART of a TimeScape.
    
    Parameters:
    
    lang - the human language to interpret pitch classes etc.
  - Score_cwn
```
public Score_cwn(TimeScape ts,
                 String lang,
                 MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr)
```
    Process THE ONE AND ONLY part of the TimeScape.
- Method Detail
  - multipleParts
```
public static Map<String,Score_cwn> multipleParts(TimeScape ts,
                                                  String lang,
                                                  MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr)
```
    Service providing main factory method for converting all "PART" sections in the given tscore input Timescape. Returns a map of Score_cwns by the names of the tscore parts.
    
    Parameters:
    
    lang - the human language to interpret pitch classes etc.
  - update
```
public void update()
```
    Translate untyped tscore data into semantically sensible "common western notation", and verify that all constraints are met. This method READS the event lists contained in TimeScape->voices->bySourceOrder and WRITES to all the local Map and Set output data declared locally.
  - normalizeEvents
```
public PrimeFactors normalizeEvents(Vox voice,
                                    boolean mergePauses,
                                    List<Event> events,
                                    List<QualifiedRational> evStarts,
                                    List<Boolean> repeats)
```
    Step through the voice, remove "hold" symbols by the prolongating the preceding (sounding) event, merge adjacent "pause" events, and calculate the required sub-division of a quarter for the midi realization of all. Checks additionally that the very first symbol has a clef and is not a "hold". Results are returned in three lists which are indexed in sync.
    (currently 20180310 only used in Cwn_to_{lilypond,musicxml} !! FIXME make idempotent!
    FIXME merge pause only with preceding pause if not attributed (provide predicate as functional arg)
    
    Parameters:
    
    voice - the voice to process (the time points to step through the voice are in the global field rat2tp.
    
    mergePauses - whether adjacent pauses shall be merged.
    
    events - OUTPUT parameter: list of all filtered events
    
    evStarts - OUTPUT parameter: list of the starting time points of the filtered events
    
    repeats - OUTPUT parameter: whether the event has the same pitch as its predecessor
    
    repeats - shows whether the NEXT event has the same pitch. WIRD NICHT UNBEDINGT GEBRRAUCHT / WIEDER RAUS ??? FIXME
    
    Returns:
    
    the lowest common multiple of all occuring time divisions. (Needed e.g. to set the time granularity "ppq" for a midi encoding.)
  - normalizeEvents_midi_PPQ
```
public int normalizeEvents_midi_PPQ(Vox voice,
                                    boolean mergePauses,
                                    List<Event> events,
                                    List<QualifiedRational> evStarts,
                                    List<Boolean> repeats)
```
    Execute normalizeEvents(Vox,boolean,List,List,List), but return the lcm of all duration numerators in the form required for Midi "Parts per quarter".
  - dumpVoice
```
public void dumpVoice(PrintStream ps,
                      Vox voice)
```
    Debugging print which prints only the time point and the pitch, if it is not the metric voice.
  - makeTp
```
public Tp makeTp(Rational when,
                 @Opt
                 Location<XMLDocumentIdentifier> origLoc)
```
    Add a new time point at the given rational time value, if no such already exists.
  - addCompleteMeasure
```
public void addCompleteMeasure(int den,
                               int nom,
                               @Opt
                               @Opt MTreeSpec mt)
```
    Append at the end of all measure specifications a new measure with the given name (looking like "den/nom") and MTree specification.
  - addCompleteMeasure
```
public void addCompleteMeasure(MetrumName name,
                               @Opt
                               @Opt MTreeSpec mt)
```
    Append at the end of all measure specifications a new measure with the given name (looking like "den/nom") and MTree specification. Iff the mtreespec !=null, then this measure will be treated as "explicit measure indication". FIXME, this seems rather arbitrary!?!
    FIXME there is a fixme in MeasureCollector.addCompleteMeasure(MetrumIndication).

Class Score_cwn

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

msgr

msg

part

language

modifiers

voicename_metric

paramname_metric

paramname_mtree

paramname_articulation

paramname_nota

paramname_verba

parse_barNumber

checkDistance

voiceMetric

decimal2tpTop

tpTop2decimal

tp2rat

firstTp

lastTp

lastTpTop_rat

event2tempo

rat2tp

event2endtp

pause

holds

event2pitch

eventHasFullAccidental

eventHasCautionaryAccidental

event2artikulation

event2ornamentation

legatos

clefPrefix

event2clefUsage

event2key

motifs

event2lowerText

event2upperText

event2verba

measures

mTreeCollector

Constructor Detail

Score_cwn

Score_cwn

Method Detail

multipleParts

update

normalizeEvents

normalizeEvents_midi_PPQ

dumpVoice

makeTp

addCompleteMeasure

addCompleteMeasure