tune scale documentation

[VictorEijkhout]

I really can't figure out what the arguments to tune scale rank2 are. Can the documentation be extended a little?

Also the generation of tuning files for a synthesizer are unclear. I can not get tun to produce a file.

[Woyten]

Hi @VictorEijkhout. Thanks for your feedback!

Regarding your question

• You can list all parameters of the rank2 command with tune xxx rank2 --help or tune xxx help rank2. I will add this hint to the README.md documentation.
• The first parameter of the rank2 command is the "interesting" interval (first generator), let's say a just fifth, i.e. 1.5 or 3/2.
• The second parameter is the number of forward iterations of the interesting interval excluding the unison. So, if the second parameter is 3, you will add the intervals 3/2, 9/4=(3/2)^2 and 27/8=(3/2)^3 - all mod the period interval (an octave by default)
• The third parameter is optional and declares the number of backward iterations of the interesting interval, e.g. (2/3) = (3/2)^-1, (4/9)=(3/2)^-2 and so on
• If you do no want the octave to be the period (second generator) you can override this value via the -p my-interval option
• To create a Scala tuning file use the scl command. E.g. tune scl rank2 1.5 3 3 will print a rank2 tuning file to the terminal. If you want to conveniently write any tune output to a file use the --of my-file.scl option. In total: tune --of my-file.scl scl rank2 1.5 3 3.
• The scale command does not generate a tuning file but evaluates the provided scale expression for all MIDI numbers. To make this command work you need to specify a scale root and a reference pitch. tune scale --help or tune help scale will explain the parameters of the command.

To improve the documentation I would need to know why the current documentation does not work yet. Could you explain where you looked for help? Should the documentation be more in the README.md or in the --help part of the command line interface? Also, which tuning file format do you need? tune currently only has support for the Scala format. I did not evaluate the tun format yet since it appears to be proprietary and less flexible.

[VictorEijkhout]

Thanks for getting back to me. The --of option was not int he documentation that I found https://crates.io/crates/tune-cli.

I'm trying to generate "just intonation" tunings, and for that I think I understand the documentation.

In order to understand the rank2 tunings I think I'd better first understand how quarter-comma meantone and such precisely work.

[VictorEijkhout]

Your documentation gives a command

scl -n "Just intonation" steps 9/8 5/4 4/3 3/2 5/3 15/8 2

But this is incomplete. Please only give working examples.

[VictorEijkhout]

The obvious fix

tune scl -n "Just intonation" steps 9/8 5/4 4/3 3/2 5/3 15/8 2
Error: The command failed / error: Found argument '-n' which wasn't expected, or isn't valid in this context

[Woyten]

Your documentation gives a command

scl -n "Just intonation" steps 9/8 5/4 4/3 3/2 5/3 15/8 2

But this is incomplete. Please only give working examples.

Thanks for pointing that out! It should be scl --name "Just intonation" steps 9/8 5/4 4/3 3/2 5/3 15/8 2. I changed the parameter in the past. 😃

[VictorEijkhout]

Is scl a command by itself? I didn't get it from the cask install. After a bunch of experiments I found:

tune --of purec.scl scale 60 steps 9/8 5/4 4/3 3/2 5/3 15/8 2

[VictorEijkhout]

How can I give both a name and a reference tone?

[Woyten]

Is scl a command by itself? I didn't get it from the cask install. After a bunch of experiments I found:

scl is a subcommand to be used as tune scl .... scale is a different subcommand.

How can I give both a name and a reference tone?

You can't. Let me explain:

• tune scl creates an SCL file. SCL scales can have a name but they do not contain a reference note. I think the command you want is

  tune --of purec.scl scl --name "My cool scale" steps 9/8 5/4 4/3 3/2 5/3 15/8 2

  To define a reference note, you need to create a separate KBM file, e.g.

  tune --of purec.kbm kbm 60
  

  Usually uploading an SCL file to your synth is sufficient but if you don't specify a KBM file the synth will pick the reference note for you.
• tune scale is a different command. It will evaluate the pitches for all MIDI notes and write them as JSON s.t. they can be inspected. I don't know whether this is very good idea but it was the best I had so far. The idea is to pipe the JSON output using the pipe operator | to another call to tune, e.g. tune dump, tune diff or tune mts from-json. Providing a name at this location is not meaningful.

[Woyten]

@VictorEijkhout I created #31 to address your feedback. What do you think?