Update documentation.
This commit is contained in:
kevin
parent
c69e0cee63
commit
1f9895a6c0
133
README.md
133
README.md
@ -1,86 +1,42 @@
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
fftw fftw-devel atlas atlas-devel alsa-lib alsa-lib-devel fltk fltk-devel
|
||||
libcm fftw fftw-devel atlas atlas-devel alsa-lib alsa-lib-devel
|
||||
|
||||
|
||||
About
|
||||
=====
|
||||
|
||||
In the 'template generation' mode the program generates a text file that contains information
|
||||
of interest from the MusicXML file. We refer to the text file as the as the 'decoration' file
|
||||
because it allows the score to be further decorated by adding additional information to the score.
|
||||
`cmtools` is a wrapper program for a collection of utility programs implemented by `libcm`.
|
||||
It is particullary useful for a variety of score processing tasks.
|
||||
|
||||
In the 'escore generation' mode the program outputs a data file in CSV format which contains
|
||||
the score in a format which is conveniently readable by a score matching program. The program
|
||||
also generates a MIDI file which allows the clarified score to be rendered with a sampler.
|
||||
An additional SVG (scalable vector graphics) file is generated which shows the score in
|
||||
piano roll form along with any problems that the program may have had during the conversion process.
|
||||
Electronic Score Generation and Merging
|
||||
=======================================
|
||||
|
||||
Parse a MusicXML file and generate a textual representation which can be augmented manually or programatically.
|
||||
The textual representation is referred to as a 'score edit file' or sometimes just 'edit file'.
|
||||
|
||||
This command will generate an edit file as long as the specified edit file does not already exist.
|
||||
|
||||
```
|
||||
cmtool --score_gen -x <xml_file> -d <dec_fn> {-c <csvOutFn>} {-m <midiOutFn>} {-s <svgOutFn>} {-r report} {-b begMeasNumb} {t begTempoBPM}
|
||||
cmtools --score_gen -x <xml_file> -d <edit_fn>
|
||||
```
|
||||
|
||||
The edit file generated by this command provides a way to link additional information
|
||||
to the score. [The details for editing the file are here.](https://gitea.larke.org/klarke/cmtools/src/branch/master/doc/xscore_gen.md).
|
||||
|
||||
Enumerated group: Action selector
|
||||
|
||||
-S --score_gen
|
||||
Run the score generation tool.
|
||||
|
||||
-T --timeline_gen
|
||||
Run the time line generation tool.
|
||||
|
||||
-M --meas
|
||||
Generate perfomance measurements.
|
||||
|
||||
-x --xml_fn <filename>
|
||||
Name of the input MusicXML file.
|
||||
|
||||
-d --dec_fn <filename>
|
||||
Name of a score decoration file.
|
||||
|
||||
-c --csv_fn <filename>
|
||||
Name of a CSV score file.
|
||||
|
||||
-p --pgm_rsrc_fn <filename>
|
||||
Name of program resource file.
|
||||
|
||||
-m --midi_out_fn <filename>
|
||||
Name of a MIDI file to generate as output.
|
||||
|
||||
-i --midi_in_fn <filename>
|
||||
Name of a MIDI file to generate as output.
|
||||
|
||||
-s --svg_fn <filename>
|
||||
Name of a HTML/SVG file to generate as output.
|
||||
|
||||
-t --timeline_fn <filename>
|
||||
Name of a timeline to generate as output.
|
||||
|
||||
-r --report_fn <filename>
|
||||
Name of a status file to generate as output.
|
||||
|
||||
-f --debug_fl (required)
|
||||
Print a report of the score following processing.
|
||||
|
||||
-b --beg_meas <int>
|
||||
The first measure the to be written to the output CSV, MIDI and SVG files.
|
||||
|
||||
-e --beg_bpm <int>
|
||||
Set to 0 to use the tempo from the score otherwise set to use the tempo at begMeasNumb.
|
||||
|
||||
-n --svg_stand_alone_fl
|
||||
Write the SVG output with an HTML wrapper.
|
||||
|
||||
-z --svg_pan_zoom_fl
|
||||
Include the SVG pan-zoom control (--svg_stand_alone must also be enabled)
|
||||
|
||||
-h --help
|
||||
Print this usage information.
|
||||
|
||||
-v --version
|
||||
Print version information.
|
||||
Once the edit file has been completed the MusicXML and edit file information can
|
||||
be merged to create an 'electronic score' in the form of a CSV file using the following command.
|
||||
|
||||
```
|
||||
cmtools --score_gen -x <xml_file> -d <edit_fn> {-c <csvOutFn>} {-m <midiOutFn>} {-s <svgOutFn>} {-r report} {-b begMeasNumb} {t begTempoBPM}
|
||||
```
|
||||
|
||||
Along with the CSV file this command can also generate an SVG (scalable vector graphics) file which shows the
|
||||
augmented score in piano roll form, and a MIDI file which can be used to render the score with a synthesizer.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Score Following and Timeline Marker Generator
|
||||
@ -90,7 +46,7 @@ Perform score following based tasks.
|
||||
Generate the time line marker information used by the performance program resource file.
|
||||
|
||||
```
|
||||
cmtool --score_follow -c <csv_score_fn> -i <midi_in_fn> -r <report_fn> -s <svg_out_fn> -m <midi_out_fn> -t <timeline_fn>
|
||||
cmtools --score_follow -c <csv_score_fn> -i <midi_in_fn> -r <report_fn> -s <svg_out_fn> -m <midi_out_fn> -t <timeline_fn>
|
||||
```
|
||||
|
||||
If `<midi_out_fn>` is given then the a copy of `<midi_in_fn>` will be created with
|
||||
@ -126,7 +82,7 @@ is used as a substitute for a real player.
|
||||
|
||||
|
||||
```
|
||||
cmtool --meas_gen -p <pgm_rsrc_fn> -r <report_fn>
|
||||
cmtools --meas_gen -p <pgm_rsrc_fn> -r <report_fn>
|
||||
```
|
||||
|
||||
|
||||
@ -147,7 +103,7 @@ Example `<pgm_rsrc_fn>`:
|
||||
Example call with output file snippet:
|
||||
|
||||
```
|
||||
cmtool --meas_gen -g ~/src/cmtools/examples/perf_meas/pgm_rsrc_round2.js -r ~/src/cmtools/examples/perf_meas/perf_meas_out.js
|
||||
cmtools --meas_gen -g ~/src/cmtools/examples/perf_meas/pgm_rsrc_round2.js -r ~/src/cmtools/examples/perf_meas/perf_meas_out.js
|
||||
|
||||
{
|
||||
meas :
|
||||
@ -187,7 +143,7 @@ Score Report
|
||||
Generate a human readable score report from a score CSV file.
|
||||
|
||||
```
|
||||
cmtool --score_report -c <csvScoreFn> -r <scoreRptFn>"
|
||||
cmtools --score_report -c <csvScoreFn> -r <scoreRptFn>"
|
||||
|
||||
```
|
||||
|
||||
@ -225,7 +181,7 @@ Score Merge
|
||||
Copy the manual edits from 'frag.txt' to the correct location, beginning with measure 284, in the blank edit file 'edit0.txt'.
|
||||
|
||||
```
|
||||
cmootls --merge_edit -d edit0.txt -b 284 -k frag.txt -o temp.txt
|
||||
cmtools --merge_edit -d edit0.txt -b 284 -k frag.txt -o temp.txt
|
||||
```
|
||||
|
||||
All the events in 'frag.txt' may not be able to be located in 'edit0.txt'. Warning messages will be generated for
|
||||
@ -250,7 +206,7 @@ MIDI File Reports
|
||||
|
||||
Generate a MIDI file report and optional SVG piano roll image."
|
||||
|
||||
cmtool --midi_report -i <midiInFn> -r <midiRptFn> {-s <svgOutFn> {--svg_stand_alone_fl} {--svg_pan_zoom_fl} }
|
||||
cmtools --midi_report -i <midiInFn> -r <midiRptFn> {-s <svgOutFn> {--svg_stand_alone_fl} {--svg_pan_zoom_fl} }
|
||||
|
||||
|
||||
Timeline Report
|
||||
@ -258,7 +214,7 @@ Timeline Report
|
||||
|
||||
Generate human readable report from a time line setup file.
|
||||
|
||||
cmtool --timeline_report -t <timelineInFn> -l <tlPrefix> -r <rptOutFn>
|
||||
cmtools --timeline_report -t <timelineInFn> -l <tlPrefix> -r <rptOutFn>
|
||||
|
||||
tlPrefix is the folder where data files for this timeline are stored.
|
||||
|
||||
@ -266,7 +222,7 @@ tlPrefix is the folder where data files for this timeline are stored.
|
||||
Score Follow Report
|
||||
===================
|
||||
|
||||
cmtool --score_follow -c round2.csv -i new_round2.mid -r report.txt -s report_svg.html
|
||||
cmtools --score_follow -c round2.csv -i new_round2.mid -r report.txt -s report_svg.html
|
||||
|
||||
|
||||
SVG Description
|
||||
@ -276,7 +232,8 @@ SVG Description
|
||||
- Red borders around MIDI events that did not match.
|
||||
- Line is drawn to MIDI events that matched to multiple score events. The lines
|
||||
are drawn to all score events after the first match.
|
||||
|
||||
|
||||
|
||||
|
||||
Audio Device Test
|
||||
=================
|
||||
@ -291,18 +248,18 @@ This test also excercises the real-time audio buffer which implements most of th
|
||||
```
|
||||
|
||||
```
|
||||
-s --srate <real> Audio system sample rate.
|
||||
-z --hz <real> Tone frequency in Hertz.
|
||||
-x --ch_index <uint> Index of first channel index.
|
||||
-c --ch_cnt <uint> Count of audio channels.
|
||||
-b --buf_cnt <uint> Count of audio buffers. (e.g. 2=double buffering, 3=triple buffering)
|
||||
-f --frames_per_buf <uint> Count of audio channels.
|
||||
-s --srate <real> Audio system sample rate.
|
||||
-z --hz <real> Tone frequency in Hertz.
|
||||
-x --ch_index <uint> Index of first channel index.
|
||||
-c --ch_cnt <uint> Count of audio channels.
|
||||
-b --buf_cnt <uint> Count of audio buffers. (e.g. 2=double buffering, 3=triple buffering)
|
||||
-f --frames_per_buf <uint> Count of audio channels.
|
||||
-i --in_dev_index <uint> Input device index as taken from the audio device report.
|
||||
-o --out_dev_index <uint> Output device index as taken from the audio device report.
|
||||
-r --report_flag Print a report of the score following processing.
|
||||
-h --help Print this usage information.
|
||||
-v --version Print version information.
|
||||
-p --parms Print the arguments.
|
||||
-o --out_dev_index <uint> Output device index as taken from the audio device report.
|
||||
-r --report_flag Print a report of the score following processing.
|
||||
-h --help Print this usage information.
|
||||
-v --version Print version information.
|
||||
-p --parms Print the arguments.
|
||||
```
|
||||
|
||||
MIDI Audio Sync (MAS)
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
xscore_gen
|
||||
score_gen
|
||||
==========
|
||||
|
||||
*xscore_gen* parses MusicXML score files and generates a text file
|
||||
The `cmtools` *score_gen* command parses MusicXML score files and generates a text file
|
||||
which allows the score to be clarified and additional information to
|
||||
be added. This is the first step in creating a 'machine readable
|
||||
score' based on the 'human readable score'.
|
||||
@ -25,15 +25,15 @@ text strings.
|
||||
|
||||
2. Generate the MusicXML file using the [Dolet 6 Sibelius
|
||||
plug-in](https://www.musicxml.com/). The resulting MusicXML file is
|
||||
run through *xscore_gen* and parsed to find any invalid structures
|
||||
run through *score_gen* and parsed to find any invalid structures
|
||||
such as damper up events not preceeded by damper down events, or tied
|
||||
notes with no ending note. These problems are cleared by careful
|
||||
re-editing of the score within Sibelius until all the problematic
|
||||
structures are fixed.
|
||||
|
||||
3. As a side effect of step 2 a template 'decoration' file is generated.
|
||||
3. As a side effect of step 2 a template 'edit' file is generated.
|
||||
This text file has all the relavant 'machine score' information
|
||||
from the XML score as a time tagged list. In this step *decoration* information is manually
|
||||
from the XML score as a time tagged list. In this step *edit* information is manually
|
||||
added by entering codes at the end of each line. The codes
|
||||
are cryptic but they are also succinct and allow for relatively
|
||||
painless editing.
|
||||
@ -50,7 +50,7 @@ cmtools --score_gen -x GUTIM_20200803_utf8.xml -d edit0.txt -c score.csv -m scor
|
||||
```
|
||||
|
||||
As with step 2 this step may need to be iterated several times
|
||||
to clear syntactic errors in the decoration data.
|
||||
to clear syntactic errors in the edit data.
|
||||
|
||||
5. Generate the time line marker information to be used with the performance program:
|
||||
|
||||
@ -78,15 +78,15 @@ There are currently three defined groups
|
||||
|
||||
### Score Coloring Chart:
|
||||
|
||||
Description Number Color
|
||||
------------------- -------- -------------------------
|
||||
Even #0000FF blue
|
||||
Tempo #00FF00 green
|
||||
Dyn #FF0000 red
|
||||
Tempo + Even #00FFFF green + blue (turquoise)
|
||||
Dyn + Even #FF00FF red + blue
|
||||
Dyn + Tempo #FF7F00 red + green (brown)
|
||||
Tempo + Even + Dyn #996633 purple
|
||||
Description | Number | Color
|
||||
------------------- | -------- | -------------------------
|
||||
Even | #0000FF | blue
|
||||
Tempo | #00FF00 | green
|
||||
Dyn | #FF0000 | red
|
||||
Tempo + Even | #00FFFF | green + blue (turquoise)
|
||||
Dyn + Even | #FF00FF | red + blue
|
||||
Dyn + Tempo | #FF7F00 | red + green (brown)
|
||||
Tempo + Even + Dyn | #996633 | purple
|
||||
|
||||
Decrement color by one (i.e. 0xFE) to indicate the last note in a group
|
||||
of measured notes. Note that a decremented color stops all active measures
|
||||
@ -134,14 +134,14 @@ this problem by editing the first line with `vi`.
|
||||
|
||||
|
||||
|
||||
Create the decoration file
|
||||
Create the edit file
|
||||
--------------------------
|
||||
|
||||
```
|
||||
cmtools --score_gen -x myscore.xml -d mydec.txt {--damper}
|
||||
cmtools --score_gen -x myscore.xml -d myedit.txt {--damper}
|
||||
```
|
||||
|
||||
Here's a snippet of a typical 'decoration' file.
|
||||
Here's a snippet of a typical 'edit' file.
|
||||
|
||||
```
|
||||
Part:P1
|
||||
@ -165,7 +165,7 @@ Part:P1
|
||||
14 5 0 3072 768 4.0 -R------------- 3840
|
||||
```
|
||||
|
||||
### Decoration file format
|
||||
### Edit file format
|
||||
|
||||
Column | Description
|
||||
-------|-----------------------------
|
||||
@ -179,7 +179,7 @@ flags | event attributes
|
||||
|
||||
### Event attribute flags:
|
||||
|
||||
Event attribute symbols used in the decoration file:
|
||||
Event attribute symbols used in the edit file:
|
||||
|
||||
Desc | Flag |
|
||||
----------|------|-----------------------------------------
|
||||
@ -204,7 +204,7 @@ Onset | * | note onset
|
||||
|
||||
|
||||
|
||||
Decoration Sytax:
|
||||
Edit Sytax:
|
||||
------------------
|
||||
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user