From 1f9895a6c0a67c144c45347a982165e905ecd18b Mon Sep 17 00:00:00 2001 From: kevin Date: Fri, 16 Oct 2020 15:11:12 -0400 Subject: [PATCH] Update documentation. --- README.md | 133 ++++++++++++++++------------------------------ doc/xscore_gen.md | 42 +++++++-------- 2 files changed, 66 insertions(+), 109 deletions(-) diff --git a/README.md b/README.md index 990d7d0..04abbd1 100644 --- a/README.md +++ b/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 -d {-c } {-m } {-s } {-r report} {-b begMeasNumb} {t begTempoBPM} +cmtools --score_gen -x -d +``` +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 - Name of the input MusicXML file. - --d --dec_fn - Name of a score decoration file. - --c --csv_fn - Name of a CSV score file. - --p --pgm_rsrc_fn - Name of program resource file. - --m --midi_out_fn - Name of a MIDI file to generate as output. - --i --midi_in_fn - Name of a MIDI file to generate as output. - --s --svg_fn - Name of a HTML/SVG file to generate as output. - --t --timeline_fn - Name of a timeline to generate as output. - --r --report_fn - Name of a status file to generate as output. - --f --debug_fl (required) - Print a report of the score following processing. - --b --beg_meas - The first measure the to be written to the output CSV, MIDI and SVG files. - --e --beg_bpm - 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 -d {-c } {-m } {-s } {-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 -i -r -s -m -t +cmtools --score_follow -c -i -r -s -m -t ``` If `` is given then the a copy of `` will be created with @@ -126,7 +82,7 @@ is used as a substitute for a real player. ``` -cmtool --meas_gen -p -r +cmtools --meas_gen -p -r ``` @@ -147,7 +103,7 @@ Example ``: 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 -r " +cmtools --score_report -c -r " ``` @@ -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 -r {-s {--svg_stand_alone_fl} {--svg_pan_zoom_fl} } + cmtools --midi_report -i -r {-s {--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 -l -r + cmtools --timeline_report -t -l -r 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. - + + ![Example SVG Image](doc/score_follow_0.png) Audio Device Test ================= @@ -291,18 +248,18 @@ This test also excercises the real-time audio buffer which implements most of th ``` ``` --s --srate Audio system sample rate. --z --hz Tone frequency in Hertz. --x --ch_index Index of first channel index. --c --ch_cnt Count of audio channels. --b --buf_cnt Count of audio buffers. (e.g. 2=double buffering, 3=triple buffering) --f --frames_per_buf Count of audio channels. +-s --srate Audio system sample rate. +-z --hz Tone frequency in Hertz. +-x --ch_index Index of first channel index. +-c --ch_cnt Count of audio channels. +-b --buf_cnt Count of audio buffers. (e.g. 2=double buffering, 3=triple buffering) +-f --frames_per_buf Count of audio channels. -i --in_dev_index Input device index as taken from the audio device report. --o --out_dev_index 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 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) diff --git a/doc/xscore_gen.md b/doc/xscore_gen.md index 1eb0b93..2e7cde2 100644 --- a/doc/xscore_gen.md +++ b/doc/xscore_gen.md @@ -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: ------------------ ```