musescore-microtonal-edo-plugin
musescore-microtonal-edo-plugin copied to clipboard
Microtonal MuseScore plugin to retune notes in any EDO. Deprecated, see musescore-xen-tuner (link below).
Microtonal plugin for Musescore 3.4+: Retune + Transpose in almost any EDO.
⚠️ This project is deprecated ⚠️
This project is no longer maintained. Please use euwbah/musescore-xen-tuner instead, which is a much more powerful and general solution for microtonality in MuseScore 3. Supports JI, EDOs, stretched tunings, non-octave tunings, NEJI, Bohlen-Pierce, negative staves, chromatic staves, custom/variable nominals, accidental ligatures (HEJI & Sagittal). MS 4 support is being worked on.
Features
- Retuning notes to match any supported edo of choice
- Special thanks to Flora Canou for providing the generalized method for evaluating cent offsets for any EDO.
- Support for key signatures via Key signature annotations
- Transposing individual notes/selections by 1 EDO step while automatically assigning accidentals
- Tuning, key signatures, and reference pitches can be changed mid score;
- Each staff can be assigned its own tunings, key signatures, and reference pitches independently.
- Based on Kite Giedraitis' ups and downs notation
Support me
Support this plugin + fund my xenharmonic music creation and research. Any amount would be greatly appreciated!
Quick start
Make sure you are using MuseScore 3.4 or newer. The plugin will not work in previous versions
1. Download the project and unzip into MuseScore's plugins directory
2. Enable the following plugins
-
tune n-edo
: Tunes the selected notes, or entire score if nothing selected. Notes are not automatically tuned as they are entered, so it is important to run this regularly for accurate playback. -
pitch up
&pitch down
: Transposes selected notes by 1 edostep, then updates their tuning. Equivalent to MuseScore's up/down arrow shortcuts. If you prefer arrow notation over semi/sesqui sharp/flat quartertone notation, usepitch up no dt
&pitch down no dt
instead.
3. Set up keyboard shortcuts for the plugins
(optional, highly recommended for the best experience)
- First, clear/change the default shortcuts that uses the up/down arrow keys.
You can find these in Edit -> Preferences -> Shortcuts. Search for the following shortcut names,
select them and click the Clear button.
- Pitch up or move text or articulation up
- Pitch down or move text or articulation down
- Select string above
- Select string below
- To define a shortcut for a plugin, go to: Plugins -> Plugin Manager -> Select plugin name in the list -> Define Shortcut.
- Set
tune n-edo
to useAlt-R
. - Set
pitch up
/pitch up no dt
to use the up arrow. This shortcut should only be assigned on either one of the plugins. - Set
pitch down
/pitch down no dt
to use the down arrow. This shortcut should only be assigned on either one of the plugins.
4. Select a tuning system
Create a System Text (Ctrl-Shift-T
) and type ___ edo
, fill in the blank with any
of the supported edo tunings. This will
affect all staves/parts from the bar where the text was placed onwards.
If you wish to only change the tuning of
one staff, but not the others, use Staff Text (Ctrl-T
) instead. You should not place a tuning system change
halfway through a bar.
If a tuning system has not been specified for a part, it defaults to 12 edo. The text is case-insensitive.
5. Annotate key signatures
For each key signature, create one System Text (Ctrl-Shift-T
) at the start of the same
bar as the key signature, then type .x.x.x.x.x.x.x
, where each 'x'
represents an accidental applied on the notes C, D, E, F, G, A, and B respectively.
If a note should have no accidental, you can leave it blank or put any other placeholder character.
For example, the key signature for D major can look like: .#...#...
representing C# and F#.
There should always be 7 dots (.
) in the key signature annotation. Refer to the
list of supported key signatures.
If there are staves which have a separate key signatures from the others,
as in local key signatures,
or transposing instruments, you can assign a key signature annotation for just that
staff using Staff Text (Ctrl-T
) instead of System Text.
:warning: Due to current technical limitations of MuseScore, all key signatures, even standard non-custom ones, must be accompanied by key signature annotations.
:warning: It is necessary to adjust the key signature annotations when toggling between concert and tranposing pitch display modes.
If a key signature annotation has not been specified, the plugin assumes that there are no accidentals in the key signature. The text is case-insensitive.
6. Annotate transposing instruments
If a part uses a transposing instrument, create a Staff Text (Ctrl-T
) at
the start of the first bar of the part, or at the start of the bar where an instrument change to
a transposing instrument of a different transposition is performed. In this staff text,
type t: Bb
for Bb instruments, t: Eb
for Eb instruments, etc. All fifth-based transpositions
are supported - meaning you can use the accidentals x
, #
, b
, bb
.
This step is required as MuseScore implements transpositions as offsets in 12-edo. Placing the transposition annotation will correct the offset into the current tuning system. Note that if Concert Pitch display mode is active, the transposition annotation will not take effect and all parts will be treated as C instruments.
If no transposition annotations were specified, the part is assumed to be a C instrument. The text is case-insensitive.
7. Select a reference pitch
This step is optional and reference pitch is defaulted to A4: 440 Hz
.
To change reference pitch for all parts, create a System Text (Ctrl-Shift-T
) and
type {note}: {f} Hz
:
-
{note}
represents any note A through G followed by its octave without spaces. Middle C is written asC4
. -
{f}
represents the frequency of the above reference note in Hertz - the 'Hz' is optional
To change reference pitch for only one part, use Staff Text (Ctrl-T
) instead.
The text is case-insensitive.
8. Done!
You can now use the up and down arrow keys to adjust a note according to the tuning system of choice! Here are some things to take note of:
- You can make the text annotations invisible by selecting them and pressing
V
. - Make sure each System/Staff Text only contains one modifier; don't combine tuning selection and key signature annotation in one Text element.
- Remember to run the
tune n-edo
plugin regularly to update the pitches of notes that are not yet tuned/transposed. - Recall that:
- System Text (
Ctrl-Shift-T
) = annotation applies to all staves - Staff Text (
Ctrl-T
) = annotation applies to current staff only.
- System Text (
Additional Settings
In a separate Staff/System Text annotation, type config: {showallaccidentals: true}
(verbatim)
to turn on courtesy accidentals for all notes (helpful for atonal pieces or scores without barlines).
Accidental Code
Accidental | Textual representation |
---|---|
bbv3 |
|
bbv2 |
|
bbv or bbv1 |
|
bb |
|
bb^ or bb^1 |
|
bb^2 |
|
bb^3 |
|
db or bd |
|
bv3 |
|
bv2 |
|
bv or bv1 |
|
b |
|
b^ or b^1 |
|
b^2 |
|
b^3 |
|
v3 |
|
v2 |
|
v or v1 |
|
d |
|
Leave blank / any other character | |
+ |
|
^ or ^1 |
|
^2 |
|
^3 |
|
#v3 |
|
#v2 |
|
#v or #v1 |
|
# |
|
#^ or #^1 |
|
#^2 |
|
#^3 |
|
#+ or +# |
|
xv3 |
|
xv2 |
|
xv or xv1 |
|
x |
|
x^ or x^1 |
|
x^2 |
|
x^3 |
Modification
原插件issue https://github.com/euwbah/musescore-microtonal-edo-plugin/issues/36 的权宜之计:使用10个Musescore内存在的变音号代替不存在的4箭头变音号,从而使得sharp-9、sharp-10律制可以使用。
新的变音号
变音号 | 名称 | 内部名称 | 选择原因 |
---|---|---|---|
v4 |
LOWER_ONE_SEPTIMAL_COMMA |
看起来像还原号的左半边 | |
^4 |
RAISE_ONE_SEPTIMAL_COMMA |
和上面那个符号相对应 | |
#v4 |
RAISE_ONE_TRIDECIMAL_QUARTERTONE |
升记号少一横,表示少升一点 | |
#^4 |
SHARP_SLASH2 |
同上,升记号多一横,表示多升一点 | |
bv4 |
THREE_TWELFTH_FLAT |
降记号上面加点东西表示比普通的降记号高 | |
b^4 |
FOUR_TWELFTH_FLAT |
降记号下面加点东西表示比普通的降记号低 | |
bbv4 |
NINE_TWELFTH_FLAT |
同上,额外加一个普通的降记号 | |
bb^4 |
TEN_TWELFTH_FLAT |
同上,额外加一个普通的降记号 | |
x^4 |
DOUBLE_SHARP_EQUAL_TEMPERED |
重升号上面加点东西表示比普通的重升号高 | |
xv4 |
SAGITTAL_SHARP25SD |
实在找不到合适的记号就随便找了个不会混淆的 |
English
A simple and straight-forward solution to issue https://github.com/euwbah/musescore-microtonal-edo-plugin/issues/36 : Include 10 extra accidentals supported by Musescore representing 4-arrow accidentals so that the plugin can tune sharp-9 & sharp-10 EDOs.
New accidental
Accidental | Text | Internal name | Reason |
---|---|---|---|
v4 |
LOWER_ONE_SEPTIMAL_COMMA |
It looks like the left half of the natural | |
^4 |
RAISE_ONE_SEPTIMAL_COMMA |
Pairing with the symbol above | |
#v4 |
RAISE_ONE_TRIDECIMAL_QUARTERTONE |
The sharp, but missing a bar, indicating less sharped | |
#^4 |
SHARP_SLASH2 |
The sharp, but having an extra bar, indicating more sharped | |
bv4 |
THREE_TWELFTH_FLAT |
The flat, but with bars above, indicating sharper than flat | |
b^4 |
FOUR_TWELFTH_FLAT |
The flat, but with signs below, indicating flatter than flat | |
bbv4 |
NINE_TWELFTH_FLAT |
As above, an extra flat is added | |
bb^4 |
TEN_TWELFTH_FLAT |
As above, an extra flat is added | |
x^4 |
DOUBLE_SHARP_EQUAL_TEMPERED |
The double sharp, but with signs above, indicating sharper than double sharp | |
xv4 |
SAGITTAL_SHARP25SD |
I cannot find an appropriate accidental, so I choose an arbitary one |
Notation system
The plugin follows notation standards as per Kite Giedraitis' ups and downs notation, which is a generalized system for notating any EDO.
Here is a brief summary of the contents of the document:
Tuning of nominals C D E F G A B
In this system, the nominals F C G D A E B are tuned according to a chain of best fifths,
which is the best representation of the perfect 3:2 just fifth that the EDO has to offer.
The exact pitches of the notes are calculated based on the frequency of the reference note, which is defined by the
reference frequency selector, or A4: 440 Hz by default.
How to calculate an EDO's best fifth?
The number of steps a fifth is in x-edo = round(x * log2(3/2))
3/2
represents the frequency ratio of a fifth in just intonation.
log2(3/2)
represents how many octaves are there in a fifth (approx 0.584962)
x * log2(3/2)
represents how many steps of x-edo are there in a fifth
round()
rounds it up/down to the nearest whole edostep.
E.g's:
- The best fifth in 12 edo is 7 steps. Thus, the distance between F-C, C-G, G-D, etc.. is 7 steps of 12 edo.
- The best fifth in 22 edo is 13 steps. Thus, the distance between C-G, etc.. is 13 steps of 22 edo.
Tuning of regular pythagorean accidentals
The standard accidentals Double Flat (bb
), Flat (b
), Sharp (#
), Double Sharp (x
) are based on
the circle of fifths.
To give an example in 12-edo, going 7 fifths up from C4 yields C4-G4-D5-A5-E6-B6-F#7-C#8.
A best fifth in 12-edo is 7 steps of 12 edo.
Going up 7 fifths in 12-edo yields a total of 7*7 = 49 steps (which brings C4 to C#8)
Going down 4 octaves to bring C#8 down to C#4 reduces the steps by 4 * 12 = 48 steps.
Thus, a sharp symbol in 12-edo is defined as going up 49 steps, then down 48 steps, yielding a +1 step difference.
The number of edosteps a sharp symbol raises the pitch by is known as an EDO's sharpness value,
also known as the size of the apotome.
Thus, the sharpness of 12-edo is 1, which classifies it as a sharp-1 EDO.
Consequently, a double sharp raises the pitch by 2 times of the sharpness value, thus 2 steps.
A flat lowers the pitch by the sharpness value, thus lowering it by 1 step.
A double flat lowers the pitch by 2 times of the sharpness value, thus lowering it by 2 steps.
To give another example in 23-edo:
A best fifth in 23-edo is 13 edosteps.
Going up 7 fifths (From C4 to C#8) = going up 7 * 13 = 91 steps.
Going down 4 octaves (From C#8 to C#4) = going down 4 * 23 = 92 steps.
Thus, a sharp symbol in 23-edo is defined as going up 91 steps and down 92 steps, yielding a -1 step difference.
A sharp symbol in 23-edo, surprisingly, lowers the pitch by 1 step, instead of raising it.
Consequently, the flat symbol raises the pitch by 1 step.
The apotome size of 23-edo is -1, which classifies it as a flat-1 EDO.
Note: in EDOs such as 7, 14 and 21, the sharp and flats do not raise nor lower the pitch, and thus they are known as perfect EDOs, i.e. Sharp-0.
Here is the full list of supported EDOs and their respective sharpness values.
The plugin only supports up to 2 flats and sharps. Triple flats and sharps and not supported as MuseScore does not provide these accidentals.
Tuning of up/down arrows
Arrows on the natural, sharp/flat, double sharp/flat accidentals offsets the pitch of the note by the same number of steps of the EDO as there are arrows on the accidental.
An upwards arrow always raises the pitch by 1 step, regardless of whether the sharp symbol raises or lowers the pitch of the note. Vice versa, a downwards arrow always lowers the pitch by 1 step.
Thus the interval between C and C^ is +1 step. And so is the interval between C# and C#^, Cbv and Cb, etc..
A maximum of 3 arrows are allowed on each accidental, as MuseScore currently does not provide accidentals with more than 3 arrows. Due to these limitations, and with the help of quartertone accidentals, the plugin can only handle EDOs with a sharpness rating of up to 8.
Here is the full list of supported EDOs and their respective sharpness values.
The up/down arrow accidentals this plugin uses are Helmholtz-Ellis Just Intonation accidentals.
Gould arrow quartertone symbols look very similar to the single up/down arrow Helmholtz-Ellis accidentals,
and may be used interchangeably, although the plugin defaults to Helmholtz-Ellis when transposing.
To differentiate the two, Gould arrow symbols appear slightly larger than the Helmholtz-Ellis ones.
Tuning of quartertone (semisharp/semiflat) accidentals
Stein-Zimmermann quartertone accidentals represent an offset of half or one-and-a-half times of the standard sharpness of the accidental. They only work when the EDO has an even-number sharpness rating which can be divided by 2 evenly.
For example, in 31-edo, where the sharpness rating is sharp-2:
- lowers the pitch by 1.5 x 2 = -3 steps
- lowers the pitch by 0.5 x 2 = -1 step
- raises the pitch by 0.5 x 2 = +1 step
- raises the pitch by 1.5 x 2 = +3 steps
Known issues:
-
Cross staff notation doesn't work properly, the accidentals in the staff that the notes are transferred to do not affect the notes that originally belonged in that staff that the notes were transferred to. Please refrain from using cross-staff notation, or submit a PR for this fix.
-
Accidentals of grace notes that comes after rather than before are handled as if they were before, and also not in the right order. This causes huge problems when transposing. Please refrain from using grace notes that attach after main notes, or submit a PR for this fix.
-
The plugin tries its best to handle chords with pairs of mirrored notes that share the same line (e.g. an F and F# on the same staff line) but due to plugin API limitations and the way MuseScore natively handles them, its behavior is somewhat janky. When dealing with them, ALWAYS use explicit accidentals on the mirrored notes to ensure the Accidentals are all registered correctly. This way it is clear to read and also for the plugin to read and understand which accidentals belong to which notes.
- The exact order the plugin reads and performs operations on its notes of each chord segment are as follows:
- grace notes (in similar fashion to step 2)
- For notes in the same chord, left to right, then bottom to top, as they appear in the score.
- The exact order the plugin reads and performs operations on its notes of each chord segment are as follows:
Appendix A: List of supported EDOs according to sharpness classification.
Sharpness (steps of an apotome) | EDOs |
---|---|
flat-2 | 4, 11 |
flat-1 | 2, 9, 16, 23 |
perfect | 7, 14, 21, 28, 35 |
sharp-1 | 5, 12, 19, 26, 33, 40, 47 |
sharp-2 | 3, 10, 17, 24, 31, 38, 45, 52 |
sharp-3 | 1, 8, 15, 22, 29, 36, 43, 50, 57, 64 |
sharp-4 | 6, 13, 20, 27, 34, 41, 48, 55, 62, 69, 76 |
sharp-5 | 18, 25, 32, 39, 46, 53, 60, 67, 74, 81, 88 |
sharp-6 | 30, 37, 44, 51, 58, 65, 72, 79, 86, 93, 100 |
sharp-7 | 42, 49, 56, 63, 70, 77, 84, 91, 98, 105 |
sharp-8 | 54, 61, 68, 75, 82, 89, 96, 103, 110, 117 |
Note to self / developers:
IMPORTANT basic info on undocumented Plugin API mechanics!
CURSOR REWIND MECHANICS ARE WEIRD!
- If rewinding to start of selection
cursor.rewind(1)
, setcursor.staffIdx
andcursor.voice
afterrewind(1)
. - If rewinding to start of score, IT IS STILL NECESSARY TO CALL
cursor.rewind(1)
, then setstaffIdx
andvoice
, THEN callcursor.rewind(0)
AFTERWARDS.
Apparently, based on the (add courtesy accidentals)[https://github.com/heuchi/courtesyAccidentals/blob/master/addCourtesyAccidentals.qml#L160] plugin,cursor.track
has to be set to 0 in order forcursor.rewind(0)
to work.
It is an invalid operation to set cursor voice/staffIdx without rewinding.
IMPORTANT! DO NOT USE ===
or !==
to compare equivalence of accidentalType to Accidental enum values.
When assigning Note.accidentalType
to variables or passing it into a function as a parameter,
ensure that the value read is in integer format to invoke the getter of the
integer enumeration instead of the stringified value of the accidental type.
noteData.explicitAccidental = note.accidentalType;
console.log(explicitAccidental); // NATURAL_ARROW_UP
noteData.explicitAccidental = 0 + note.accidentalType;
console.log(explicitAccidental); // 11 (enumerated value equivalent of NATURAL_ARROW_UP)
console.log(Accidental.NATURAL_ARROW_UP); // 11
console.log(note.accidentalType); // NATURAL_ARROW_UP
console.log(0 + note.accidentalType) // 11
There is a very specific method to update an existing note's accidental
such that there are minimal race/state errors. Refer to the ]
setAccidental()
function.
Note.accidental
and Note.accidentalType
properties of transposed notes that contain new accidental values of standardized
accidentals are not present in a new cursor instance. The plugin uses tpc as a workaround, but it makes it impossible to
determine if a prior note's accidental was implicit or explicit.
See this forum post here.
Important properties:
IMPORTANT Note.accidental
vs. Note.accidentalType
:
: accidental
represents the accidental Element object itself,
: whereas, accidentalType is a value of the Accidental enumeration!!
tpc
: Tonal pitch class. Circle of fifths starting from Fbb with value of -1.
: Cbb = 0, Gbb = 1, Dbb = 2, etc...
segment.annotations[idx].textStyleType
: 22 if Staff Text,
: 21 if System Text
segment.annotations[idx].text
: Contains given text
MuseScore.curScore.selection.elements
: An array of elements containing individual elements the user has selected
: with ctrl + click. Especially useful for applying an action to certain notes in particular.
Musescore Enums
Accidentals (used in project)
Accidental.NONE (no explicit accidental)
Accidental.DOUBLE_SHARP_ONE_ARROW_UP x^
Accidental.DOUBLE_SHARP_TWO_ARROWS_UP x^2
Accidental.DOUBLE_SHARP_THREE_ARROWS_UP x^3
Accidental.SHARP2 x
Accidental.DOUBLE_SHARP_ONE_ARROW_DOWN xv
Accidental.DOUBLE_SHARP_TWO_ARROWS_DOWN xv2
Accidental.DOUBLE_SHARP_THREE_ARROWS_DOWN xv3
Accidental.SHARP_SLASH4 #+
Accidental.SHARP_ONE_ARROW_UP #^
Accidental.SHARP_TWO_ARROWS_UP #^2
Accidental.SHARP_THREE_ARROWS_UP #^3
Accidental.SHARP #
Accidental.SHARP_ONE_ARROW_DOWN #v
Accidental.SHARP_TWO_ARROWS_DOWN #v2
Accidental.SHARP_THREE_ARROWS_DOWN #v3
Accidental.SHARP_SLASH +
Accidental.NATURAL_ONE_ARROW_UP ^
Accidental.NATURAL_TWO_ARROWS_UP ^2
Accidental.NATURAL_THREE_ARROWS_UP ^3
Accidental.NATURAL natural
Accidental.NATURAL_ONE_ARROW_DOWN v
Accidental.NATURAL_TWO_ARROWS_DOWN v2
Accidental.NATURAL_THREE_ARROWS_DOWN v3
Accidental.MIRRORED_FLAT d
Accidental.FLAT_ONE_ARROW_UP b^
Accidental.FLAT_TWO_ARROWS_UP b^2
Accidental.FLAT_THREE_ARROWS_UP b^3
Accidental.FLAT b
Accidental.FLAT_ONE_ARROW_DOWN bv
Accidental.FLAT_TWO_ARROWS_DOWN bv2
Accidental.FLAT_THREE_ARROWS_DOWN bv3
Accidental.MIRRORED_FLAT2 db
Accidental.DOUBLE_FLAT_ONE_ARROW_UP bb^
Accidental.DOUBLE_FLAT_TWO_ARROWS_UP bb^2
Accidental.DOUBLE_FLAT_THREE_ARROWS_UP bb^3
Accidental.FLAT2 bb
Accidental.DOUBLE_FLAT_ONE_ARROW_DOWN bbv
Accidental.DOUBLE_FLAT_TWO_ARROWS_DOWN bbv2
Accidental.DOUBLE_FLAT_THREE_ARROWS_DOWN bbv3
Custom object types in up/down step transposition plugins
Key signature object:
{
c: {steps: <number of diesis offset>, type: Accidental enum value}
d: ...
e: ...
etc...
}
Accidental object:
{
offset: number of diesis offset,
type: accidental type as Accidental enum value
}
Enharmonics object:
{
above: {baseNote: 'a' through 'g', offset: diesis offset}
below: {baseNote: 'a' through 'g', offset: diesis offset}
}
Note pitch data:
{
baseNote: a string from 'a' to 'g',
line: the note.line property referring to height of the note on the staff
tpc: the tonal pitch class of the note (as per note.tpc)
tick: the tick position of the note
explicitAccidental: Accidental enum of the explicit accidental attatched to this note (if any)
implicitAccidental: Accidental enum of the implicit accidental of this note (non null)
(if explicitAccidental exists, implicitAccidental = explicitAccidental)
diesisOffset: the number of edo steps offset from the base note this note is
}
Changelog
TODO:
- Handle cross-staff notation (ctrl + shift + up/down in connected staves, e.g. grand staff) where note appears to be in another staff other than the cursor's staffIdx. Currently, accidentals in the cross-staff do not work on the notes that came from another staff. See Add Courtesy Accidentals plugin for how to do this
- Implement toggling between enharmonic equivalences
- Make tune n-edo plugin use stateless accidental detection also.