模块 lib.musicutil
Music utility module.
用于处理音符、音阶和和弦的实用方法。 norns 脚本参考 中提供了该模块的示例。
信息：
- 发布版本：v1.1.2
- 作者：Mark Eats
函数
函数
- generate_scale (root_num, scale_type[, octaves])
-
从根音生成音阶。
参数:
- root_num integer 音阶起始的 MIDI 音符编号 (0-127)。
- scale_type string 定义音阶类型的字符串（如 "major"（大调）、"aeolian"（自然小调）或 "neapolitan major"（那不勒斯大调）），完整列表请参见类定义。
- octaves integer 要返回的八度数量，默认为 1。 (可选)
返回:
-
{integer...}
MIDI 音符编号数组。
- generate_scale_of_length (root_num, scale_type, length)
-
从根音生成指定数量的音阶音符。
参数:
- root_num integer 音阶起始的 MIDI 音符编号 (0-127)。
- scale_type integer 定义音阶类型的字符串（如 "major"（大调）、"aeolian"（自然小调）或 "neapolitan major"（那不勒斯大调）），完整列表请参见类定义。
- length integer 要返回的音符数量，默认为 8。
返回:
-
{integer...}
MIDI 音符编号数组。
- generate_chord (root_num, chord_type[, inversion])
-
从根音生成和弦。
参数:
- root_num integer 和弦的 MIDI 音符编号 (0-127)。
- chord_type string 定义和弦类型的字符串（如 "major"（大三和弦）、"minor 7"（小七和弦）或 "sus4"（挂四和弦）），完整列表请参见类定义。
- inversion integer 和弦转位数。 (可选)
返回:
-
{integer...}
MIDI 音符编号数组。
- generate_chord_roman (root_num, scale_type, roman_chord_type)
-
使用罗马数字和弦记号为给定的根音和音阶生成和弦。
此函数可能返回音阶外的音符，且不会尝试根据上下文解决模糊的记号。
如果你想将和弦限制在音阶内的音高，请参见 chord_types_for_note 或 generate_chord_scale_degree。
支持的音阶类型请参见 MusicUtil.SCALES，可返回的和弦请参见 MusicUtil.CHORDS。
参数:
- root_num integer 定义调性的 MIDI 音符编号 (0-127)。
- scale_type string 定义音阶类型的字符串（如 "Major"（大调）、"Dorian"（多利亚调式））。
- roman_chord_type string 使用罗马数字风格的字符串定义和弦类型（如 "V"、"iv7" 或 "III+"）， 包括有限的低音音符（如 "iv6-9"）和小写字母转位记号（如 "IIb" 表示第一转位）。
返回:
-
{integer...}
MIDI 音符编号数组。
- generate_chord_scale_degree (root_num, scale_type, degree[, seventh])
-
使用欧洲传统和声时期的调性和声系统，根据音阶级数为给定的根音和调性生成和弦。
每个级数对应的具体和弦请参见 MusicUtil.SCALECHORDDEGREES。
参数:
- root_num integer 定义调性的 MIDI 音符编号 (0-127)。
- scale_type string 定义音阶类型的字符串。并非所有音阶都支持；有效值包括 "Major"（大调或 "Ionian"（爱奥尼亚调式））、"Natural Minor"（自然小调或 "Minor" 或 "Aeolian"（爱奥利亚调式））、"Harmonic Minor"（和声小调）、 "Melodic Minor"（旋律小调）、"Dorian"（多利亚调式）、"Phrygian"（弗里几亚调式）、"Lydian"（利底亚调式）、"Mixolydian"（混合利底亚调式）或 "Locrian"（洛克里亚调式）。
- degree integer 选择和弦级数的 1-7 之间的数字。
- seventh boolean 如果设为 true，则返回七和弦（可选） (可选)
返回:
-
{integer...}
MIDI 音符编号数组。
- chord_types_for_note (note_num, key_root, key_type)
-
列出给定根音和调性的和弦类型。
参数:
- note_num integer 和弦根音的 MIDI 音符编号 (0-127)。
- key_root integer 调性根音的 MIDI 音符编号 (0-127)。
- key_type string 定义调性类型的字符串（如 "major"（大调）、"aeolian"（自然小调）或 "neapolitan major"（那不勒斯大调）），完整列表请参见类定义。
返回:
-
{string...}
符合条件的和弦类型字符串数组。
- snap_note_to_array (note_num, snap_array)
-
将 MIDI 音符编号对齐到数组中最近的音符编号。
参数:
- note_num integer 输入的 MIDI 音符编号 (0-127)。
- snap_array {integer...} 用于对齐的 MIDI 音符编号数组，必须按从低到高排序。
返回:
-
integer
调整后的音符编号。
- snap_notes_to_array (note_nums_array, snap_array)
-
将 MIDI 音符编号数组对齐到音符编号数组。
参数:
- note_nums_array {integer...} 输入的 MIDI 音符编号数组。
- snap_array {integer...} 用于对齐的 MIDI 音符编号数组，必须按从低到高排序。
返回:
-
{integer...}
调整后的音符编号数组。
- note_num_to_name (note_num[, include_octave])
-
返回 MIDI 音符编号对应的音名。
参数:
- note_num integer MIDI 音符编号 (0-127)。
- include_octave boolean 如果设为 true，返回字符串中包含八度编号。 (可选)
返回:
-
string
音名字符串（如 "C#3"）。
- note_nums_to_names (note_nums_array[, include_octave])
-
返回 MIDI 音符编号数组对应的音名数组。
参数:
- note_nums_array {integer...} MIDI 音符编号数组。
- include_octave boolean 如果设为 true，返回字符串中包含八度编号。 (可选)
返回:
-
{string...}
音名字符串数组。
- note_num_to_freq (note_num)
-
返回 MIDI 音符编号对应的频率。
参数:
- note_num integer MIDI 音符编号 (0-127)。
返回:
-
float
频率值（赫兹）。
- note_nums_to_freqs (note_nums_array)
-
返回 MIDI 音符编号数组对应的频率数组。
参数:
- note_nums_array {integer...} MIDI 音符编号数组。
返回:
-
{float...}
频率值数组（赫兹）。
- freq_to_note_num (freq)
-
返回频率最接近的 MIDI 音符编号。
参数:
- freq float 频率值（赫兹）。
返回:
-
integer
MIDI 音符编号 (0-127)。
- freqs_to_note_nums (freqs_array)
-
返回频率数组最接近的 MIDI 音符编号数组。
参数:
- freqs_array {float...} 频率值数组（赫兹）。
返回:
-
{integer...}
MIDI 音符编号数组。
- interval_to_ratio (interval)
-
返回音程的比率。
参数:
- interval float 以半音为单位的音程。
返回:
-
float
比率值。
- intervals_to_ratios (intervals_array)
-
返回音程数组的比率数组。
参数:
- intervals_array {float...} 以半音为单位的音程数组。
返回:
-
{float...}
比率值数组。
- ratio_to_interval (ratio)
-
返回比率对应的音程。
参数:
- ratio float 比率值。
返回:
-
float
以半音为单位的音程。
- ratios_to_intervals (ratios_array)
-
返回比率数组对应的音程数组。
参数:
- ratios_array {float...} 比率值数组。
返回:
-
{float...}
以半音为单位的音程数组。