melbundle¶

Introduction¶

melbundle is a command-line tool that help in correcting end editing Sonic Visualiser-project files for the Jazzomat Project. It reads one or more Sonic Visualiser projects files (extension .sv), and checks first if the correct number and sort of layers (Notes Layer, Phrase Layer, Beat/Form/Chord-Layer, Articulation Layer) are present. It parses the Beat/Chord/Form-Layer end checks for syntactical well-formedness of the annotations. Furthermore, it analyses the beats, tries to perform the metrical annotation, and checks for suspicious note events (too short event, doublets). Last but not least, melbundle writes a diagnostic CSV file that can be used in Sonic Visualiser to aid manual corrections.

Usage¶

Here is the basic call to melbundle:

melbundle [-h] [--version] [-d DIR] [-o OUTDIR] [-c CONFIG]
               [positional]

Options and arguments¶

-h, --help¶: Show a help message and exits.

--version¶: Shows program’s version number and exit

-d <DIR>, --dir <DIR>¶: Use <DIR> as working directory for reading the project files. Default is the current directory.

-o <OUTDIR>, --outdir <OUTDIR>¶: Write diagnostic file to <OUTDIR>. Default is the current directory. The file name of the diagnostic file will be the name of the corresponding SV file with an added “_diag” and the new extension .csv.

-c <CONFIG>, --config <CONFIG>¶: Use the configuration file <CONFIG>, see below. The arguments <DIR> and <OUTDIR> override the settings in the configuration file. but the positional argument is ignored while using the configuration file.

positional arguments¶: A list of SV project files (separated by blanks).

Configuration file¶

The configuration files use YAML syntax. Here is an example:

---
dir: /My/Data/SV
outdir: /My/Data/Diag

files:
  - WayneShorter_Footprints.sv
  - 'Miles*'

metrical annotation params:
    oddDivisionPenalty: 1.2
    mismatchPenalty: 1.1
    distPenalty: 7.3
    spreadPenalty: 10.2
    optimize: True
    rhythmThreshold: 0.05
    scaleFactor: .87
    tolerance: .015

Explanation¶

The parameters dir and outdir have the same meaning as the corresponding program options. Unter the section files a list of files must be given to work on. Wildcards for globbing can be used, as seen in the second line. Miles* will find any files starting with Miles (possibly even other than SV files!). The block for metrical annotation params is used by the metrical annotation algorithm and can be omitted, in which case reasonable default values will be used. However, sometimes different settings might help in achieving a successful annotation for critical cases.

Note

Even the default path separator is the backslash \, DOS uses the forward slash / as an alternative separator as well. Both can be used in path variables. Using the forward slash, though, allows easier writing of cross-platform configuration files.

Output¶

Here is a typical output:

****************************************
*     melbundle - SV diagnostics       *
****************************************
Reading file /My/Data/WayneShorter_Footprints_PREFINAL.sv
Parsing notes...
Parsing phrases...
Parsing chord and forms...
Assemble chord list...
Assemble form list...
Done parsing.

Beat statistics:
================
Mean: 440.92 ms, SD = 17.83 ms
Min: 392.61, max= 493.49, range: 100.88
Two-sig outlier onsets at: 0:00:09.248980|0:00:26.197551|0:00:26.674263|0:00:27.076349|0:00:27.562744|
0:00:38.578730|0:00:43.044898|0:00:45.306395|0:00:48.766848|0:00:50.624082|0:01:09.489229|0:01:09.893878|
0:01:12.502766|0:01:28.920590|0:01:51.211859|0:01:52.024490|0:01:54.235034|0:02:09.571406

Note diagnostics:
=================
Very short events at: 0:01:03.397732 (28.8ms)

Overlapping durations at: 0:00:13.728798 (54.9ms)|0:00:13.769410 (14.5ms)|0:00:30.989932 (31.9ms)|
0:00:37.208526 (32.3ms)|0:00:49.271429 (11.0ms)|0:00:50.338776 (12.2ms)|0:00:52.709297 (18.8ms)|
0:00:55.711224 (6.1ms)|0:01:35.866485 (43.5ms)|0:01:38.095601 (10.2ms)|0:01:38.634014 (8.7ms)|
0:01:41.886553 (36.5ms)|0:01:50.291995 (11.5ms)|0:02:08.052993 (13.8ms)

Doubles at: 0:01:42.762993 (63)|0:01:58.617007 (79)

Calculating metrical annotation with params:
  { 'spreadPenalty': 10.0,
    'scaleFactor': 0.85,
    'mismatchPenalty': 1.0,
    'rhythmThreshold': 0.04,
    'tolerance': 0.02,
    'oddDivisionPenalty': 1.0,
    'distPenalty': 7.0,
    'optimize': True}...
Annotating...
...done.
Normalizing...
...done.
Done bundling.
Successfully written /My/Data/diag/WayneShorter_Footprints_PREFINAL_diag.csv

The output is interpreted as follows: 1. First the Beat/Chord/Form-Layer is parsed. If any errors occur, they will be reported, but melbundle will continue operation.

Beats are analysed and statistical measures are displayed. Two-sigma outliers are reported, this are the spots where the beat tapping went too much off and might need correction. Beat outliers will also be marked in the diagnostice file.
Note diagnostic are given. These include:
- Very short events with duration <30 ms, which are indicator for possible errors in the note transcriptions (and sometimes problematic spots for the metrical annotation. Cf. 4. below).
- Overlapping durations, these are basically uncritical, but can not be correct for jazz solos on wind instruments.
- Doubles, which are tones on the same pitch with no gap in between. These sometimes occur during automated annotation and might be an indicator that a longer note accidentally got split into several parts.
Note events are reported with a time coordinate in the corresponding SV project file plus either duration or pitch in parentheses. Doubles are also reported in the diagnostic CSV file.

4. Finally, the metrical annotation algorithm is applied, and the employed parameters are reported. If the algorithm cannot find a reasonable metrical annotation for a sequence of notes in between two beats (mostly due to very short events), melbundle bails out and reports the offending events. This means, that the SV project has to be corrected first, before possible subsequent errors will be found. This behavior might change in the future.