cml/cmtools
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update documentation.

Browse Source
This commit is contained in:
kevin 2020-10-16 15:11:12 -04:00
parent c69e0cee63
commit 1f9895a6c0
2 changed files with 66 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
README.md
View File

@ -1,86 +1,42 @@
Prerequisites 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 `cmtools` is a wrapper program for a collection of utility programs implemented by `libcm`.
of interest from the MusicXML file. We refer to the text file as the as the 'decoration' file It is particullary useful for a variety of score processing tasks.
because it allows the score to be further decorated by adding additional information to the score.
In the 'escore generation' mode the program outputs a data file in CSV format which contains Electronic Score Generation and Merging
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.
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 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.
-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.
``` ```
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 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. 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 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: 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 : meas :
@ -187,7 +143,7 @@ Score Report
Generate a human readable score report from a score CSV file. 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'. 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 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." 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 Timeline Report
@ -258,7 +214,7 @@ Timeline Report
Generate human readable report from a time line setup file. 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. 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 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 SVG Description
@ -277,6 +233,7 @@ SVG Description
- Line is drawn to MIDI events that matched to multiple score events. The lines - Line is drawn to MIDI events that matched to multiple score events. The lines
are drawn to all score events after the first match. are drawn to all score events after the first match.
![Example SVG Image](doc/score_follow_0.png)
Audio Device Test 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. -s --srate <real> Audio system sample rate.
-z --hz <real> Tone frequency in Hertz. -z --hz <real> Tone frequency in Hertz.
-x --ch_index <uint> Index of first channel index. -x --ch_index <uint> Index of first channel index.
-c --ch_cnt <uint> Count of audio channels. -c --ch_cnt <uint> Count of audio channels.
-b --buf_cnt <uint> Count of audio buffers. (e.g. 2=double buffering, 3=triple buffering) -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. -f --frames_per_buf <uint> Count of audio channels.
-i --in_dev_index <uint> Input device index as taken from the audio device report. -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. -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. -r --report_flag Print a report of the score following processing.
-h --help Print this usage information. -h --help Print this usage information.
-v --version Print version information. -v --version Print version information.
-p --parms Print the arguments. -p --parms Print the arguments.
``` ```
MIDI Audio Sync (MAS) MIDI Audio Sync (MAS)

42
doc/xscore_gen.md
View File

@ -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 which allows the score to be clarified and additional information to
be added. This is the first step in creating a 'machine readable be added. This is the first step in creating a 'machine readable
score' based on the 'human readable score'. score' based on the 'human readable score'.
@ -25,15 +25,15 @@ text strings.
2. Generate the MusicXML file using the [Dolet 6 Sibelius 2. Generate the MusicXML file using the [Dolet 6 Sibelius
plug-in](https://www.musicxml.com/). The resulting MusicXML file is 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 such as damper up events not preceeded by damper down events, or tied
notes with no ending note. These problems are cleared by careful notes with no ending note. These problems are cleared by careful
re-editing of the score within Sibelius until all the problematic re-editing of the score within Sibelius until all the problematic
structures are fixed. 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 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 added by entering codes at the end of each line. The codes
are cryptic but they are also succinct and allow for relatively are cryptic but they are also succinct and allow for relatively
painless editing. 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 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: 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: ### Score Coloring Chart:
Description Number Color Description | Number | Color
------------------- -------- ------------------------- ------------------- | -------- | -------------------------
Even #0000FF blue Even | #0000FF | blue
Tempo #00FF00 green Tempo | #00FF00 | green
Dyn #FF0000 red Dyn | #FF0000 | red
Tempo + Even #00FFFF green + blue (turquoise) Tempo + Even | #00FFFF | green + blue (turquoise)
Dyn + Even #FF00FF red + blue Dyn + Even | #FF00FF | red + blue
Dyn + Tempo #FF7F00 red + green (brown) Dyn + Tempo | #FF7F00 | red + green (brown)
Tempo + Even + Dyn #996633 purple Tempo + Even + Dyn | #996633 | purple
Decrement color by one (i.e. 0xFE) to indicate the last note in a group 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 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 Part:P1
@ -165,7 +165,7 @@ Part:P1
14 5 0 3072 768 4.0 -R------------- 3840 14 5 0 3072 768 4.0 -R------------- 3840
``` ```
### Decoration file format ### Edit file format
Column | Description Column | Description
-------|----------------------------- -------|-----------------------------
@ -179,7 +179,7 @@ flags | event attributes
### Event attribute flags: ### Event attribute flags:
Event attribute symbols used in the decoration file: Event attribute symbols used in the edit file:
Desc | Flag | Desc | Flag |
----------|------|----------------------------------------- ----------|------|-----------------------------------------
@ -204,7 +204,7 @@ Onset | * | note onset
Decoration Sytax: Edit Sytax:
------------------ ------------------
``` ```