附录B：TunePad编程参考

本附录提供了完整TunePad函数集的参考。

基本函数

playNote(note, beats = 1.0, velocity = 100, sustain = 0)

播放音高值大于0的音符。您也可以使用同时播放的音符列表调用playNote。可选参数beats设置音符将持续多长时间，可选参数velocity设置音符的声音有多响。velocity可以是0到100之间的任何数字。可选sustain参数允许音符响起的时间超过beats参数给定的值。参数的值是音符应该以节拍为单位持续的节拍数。

playNote(32)
playNote(55, beats = 0.5, velocity = 20)
playNote(0, beats = 2, velocity = 80)
playNote([36, 40, 43])
playNote([36, 40, 43], beats = 2)
playNote(48, beats = 0, sustain = 4)

playSound(sound, beats = 1.0, pitch = 0, velocity = 100, sustain = 0)

使用其ID编号播放自定义声音。您也可以使用同时播放的声音列表调用playSound。可选参数beats设置音符将持续多长时间，可选参数velocity设置音符的声音有多响。velocity可以是0到100之间的任何数字。可选pitch参数按给定的半音数更改声音的音高。例如，pitch值为3.0将等同于钢琴键盘上从C到D#的差异。可选sustain参数允许音符响起的时间超过beats参数给定的值。参数的值是音符应该以节拍为单位持续的节拍数。

playSound(1203)
playSound(1203, beats = 0.5, velocity = 20)
playSound(1203, beats = 2, pitch = 3, velocity = 80)
playSound([1203, 559, 43])

rest(beats = 1)

在音符之间添加暂停。可以使用可选beats参数设置暂停的长度。

rest()
rest(2)
rest(beats = 1.5)

播放头控制函数

moveTo(time)

将播放头向前或向后移动到任意位置。在TunePad中，播放头标记当前时间。例如，调用playNote(32, beats = 2)后，播放头将前进两个节拍。time参数以经过的节拍给出，并指定播放头将被放置的位置。例如，值为0将把播放头移动到轨道的开头（零个经过的节拍）。值为2将把播放头移动到第三个节拍的开头（两个经过的节拍）。

moveTo(0)
moveTo(4)
moveTo(0.5)

rewind(beats)

将播放头向后移动相对于其当前位置的时间量。这可能是同时播放多个音符的有用方式。beats参数指定要移动播放头的节拍数。beats的负值将播放头向前移动。

rewind(1)
rewind(-2)
rewind(0.5)

fastForward(beats)

将播放头向前移动相对于其当前位置的时间量。这可能是同时播放多个音符的有用方式。beats参数指定要移动播放头的节拍数。beats的负值将播放头向后移动。

fastForward(1.5)
fastForward(-2)

getPlayhead()

将播放头的当前值作为浮点数返回。返回的值是经过的节拍数。因此，如果播放头在非常开头，结果将为零而不是一。

getPlayhead() # 返回 0.0
playNote(0, beats = 1)
getPlayhead() # 返回 1.0

getMeasure()

将当前小节作为整数值返回。注意getMeasure返回经过的小节数。因此，如果播放头在轨道开头或第一小节结束之前的任何位置，函数将返回0。如果播放头大于或等于第二小节的开头，getMeasure将返回1，依此类推。

getMeasure() # 返回 0
playNote(0, beats = 4)
getMeasure() # 返回 1

getBeat()

将当前小节内经过的节拍数作为十进制数返回。例如，如果播放头在小节内前进了四分之一节拍，getBeat将返回0.25。getBeat返回的值将始终小于一小节中的总节拍数。

getBeat() # 返回 0
playNote(0, beats = 2)
getBeat() # 返回 2
playNote(0, beats = 1)
getBeat() # 返回 3
playNote(0, beats = 1)
getMeasure() # 返回 0

效果函数

with bend(cents = 0, beats = -1, start = 0)

添加音高弯音效果，随时间更改音符的值。cents参数表示音高的总变化。一音分等于半音的1/100（两个相邻音符之间的距离）。对cents参数使用值500将以五半音弯音音符（等同于钢琴键盘上从C到F的距离）。beats参数指定音符弯音需要多长时间。如果您不提供beats参数，效果将是恒定的。可选start参数指定在开始效果之前等待多长时间（以节拍为单位）。您还可以为cents参数提供值列表而不是单个数字。这些值表示随时间变化的音分。每个数字将均匀分布在效果的持续时间内。

# 应用恒定的音高弯音
with bend(cents = 100):
    playNote(36)

# 在一个节拍内将音符从48弯音到53
with bend(cents = 500, beats = 1):
    playNote(48)

# 弹性弹簧效果
with bend(cents = [0, 500, -500, 500, -500, 500, 0], beats = 1):
    playNote(42, beats = 2)

with gain(value = 0, beats = 1, start = 0)

更改音符的音量。value参数表示音量的变化（例如，值为0.5会将音量降低大约一半）。如果提供单个数字，将应用恒定的音量变化——不会随时间变化。您还可以传递数字列表以创建随时间的变化。每个数字将均匀分布在beats参数给定的效果持续时间内。可选start参数指定在开始效果之前等待多长时间（以节拍为单位）。

# 将音量减半
with gain(value = 0.5):
    playNote(48)

# 淡入
with gain(value = [0, 1], beats = 2):
    playNote(48, beats = 2)

# 一个节拍后淡出
with gain(value = [1, 0], beats = 2, start = 1):
    playNote(42, beats = 3)

with pan(value = 0, beats = 1, start = 0)

应用立体声平移效果，将声音更多地移向左侧或右侧扬声器。value参数的范围从-1.0（全左扬声器）到1.0（全右扬声器）。值为0.0均匀分割声音。如果提供单个数字，效果将是恒定的——不会随时间变化。您还可以传递数字列表以创建随时间的变化。每个数字将均匀分布在beats参数给定的效果持续时间内。可选start参数指定在开始效果之前等待多长时间（以节拍为单位）。

# 在三个节拍内缓慢从左扬声器平移到右扬声器
with pan(value = [-1.0, 1.0], beats = 3):
    playNote(35, beats = 3)

with lowpass(frequency = 1000, beats = 1, start = 0)

应用低通滤波器效果，降低高频声音的能量，同时保留低于截止点的低频声音不受影响。frequency参数指定效果的截止频率（介于10 Hz和22 kHz之间）。您还可以传递数字列表以创建随时间的变化。每个数字将均匀分布在beats参数给定的效果持续时间内。可选start参数指定在开始效果之前等待多长时间（以节拍为单位）。

# 一个节拍后通过在200和800 Hz之间快速更改低通滤波器的频率截止来创建哇音效果
with lowpass(frequency = [200, 800, 200, 800, 200, 800], beats = 1):
    playNote(47, beats = 3)

# 为钢琴音符添加节奏脉冲
for i in range(0, 4):
    with lowpass(frequency = [50, 800, 50], beats = 0.25, start = 1):
        playNote(33, 2)

with highpass(frequency = 1000, beats = 1, start = 0)

高通滤波器降低低频声音的能量，同时允许截止频率以上的频率不受改变地通过。frequency参数指定效果的截止频率（介于10 Hz和22 kHz之间）。您还可以传递数字列表以创建随时间的变化。每个数字将均匀分布在beats参数指定的效果持续时间内。可选start参数指定在开始效果之前等待多长时间（以节拍为单位）。

with bandpass(frequency = 1000, beats = 1, start = 0)

带通滤波器允许截止频率附近的频率不受改变地通过，同时降低上方和下方频率的能量。frequency参数指定效果的截止频率（介于10 Hz和22 kHz之间）。您还可以传递数字列表以创建随时间的变化。每个数字将均匀分布在beats参数指定的效果持续时间内。可选start参数指定在开始效果之前等待多长时间（以节拍为单位）。

# 为鼓中的拍手声音雕刻频率
clap = 10
with bandpass(frequency = [100, 11000], beats = 4):
    for i in range(0, 16):
        playNote(10, beats = 0.25)

with notch(frequency = 1000, beats = 1, start = 0)

陷波滤波器降低截止频率附近声音的能量，同时允许更高和更低的频率不受改变地通过。frequency参数指定效果的截止频率（介于10 Hz和22 kHz之间）。您还可以传递数字列表以创建随时间的变化。每个数字将均匀分布在beats参数指定的效果持续时间内。可选start参数指定在开始效果之前等待多长时间（以节拍为单位）。

with swing(value, beats = None, start = 0, rate = 0.5)

摇摆效果在节奏模式中引入延迟，这为节奏的时机增添弹跳感。这可以通过移除机械精度使表演听起来更人性化。value参数是0.0到1.0之间的数字，指定此效果应该有多明显。rate参数指定应该摇摆哪些音符值。

# 部分摇摆八分音符军鼓模式
snare = 2
with swing(0.5):
    for i in range(0, 16):
        playNote(snare, beats = 0.5)

# 完全摇摆十六分音符踩镲模式
hihat = 4
with swing(1.0, rate = 0.25):
    for i in range(0, 16):
        playNote(hihat, beats = 0.25)

TunePad和弦模块

使用以下命令将此模块导入您的代码：

from tunepad.chords import *

changeKey(key)

使用changeKey函数指定单元格的调，该函数更改单元格的全局调。此函数接受来自一组可能有效调的字符串，默认调为”C”大调。

changeKey("Cm")
changeKey("Bb")
changeKey("F#m")

buildChord(chord, octave=3, inversion=0)

buildChord函数返回输入的自然音或变化音和弦的整数列表，该和弦属于与罗马数字字符串和输入八度指定的音符相对应的全局调。八度可以使用[-1, 9]范围内的整数值指定。inversion参数控制音高的排序，范围为[0, 3]。

buildChord("I")
buildChord("ii", octave = [2, 3])
buildChord("V7", octave = 3, inversion = 2)

playChord(chord, beats=1, velocity=90, sustain=0, playType=‘block’, octave=3, inversion=0)

playChord函数播放给定调的指定自然音或变化音和弦。和弦指定为罗马数字字符串。有关beats、velocity和sustain参数的更多信息，请参见playNote。octave参数指定播放和弦的八度。此octave参数是[-1, 9]范围内的整数。inversion参数控制中音高的排序，范围为[0, 3]。使用playType参数允许我们从五种播放和弦的方法中选择一种：

默认方法是”block”，同时播放每个音符
“rolled”方法在每个音符之间引入轻微的随机偏移，以模仿人类可能如何演奏音符
“arpeggio”向上然后向下播放和弦，每个音符是总节拍的等分
“arpeggio_up”向上播放和弦，每个音符是总节拍的等分
“arpeggio_down”向下播放和弦，每个音符是总节拍的等分

playChord("I", beats = 4)
playChord("ii", beats = 4, octave = [2, 3])
playChord("V7", beats = 4, octave = 3, inversion = 2)
playChord("vi", beats = 4, octave = 3, inversion = 2, playType = "arpeggio")

buildScale(tonic, octave, mode, direction=“ascending”)

buildScale函数返回与输入音乐音阶相对应的整数列表，该音阶从输入的音符和八度开始。起始音符使用tonic参数指定，这是一组可能有效调的字符串。八度可以使用[-1, 9]范围内的整数值指定。direction参数支持”ascending”和”descending”，并指示音阶是按音高递增顺序还是递减顺序排列。mode参数接受等同于以下的字符串：

“Major”或”minor”
教会调式之一：“Ionian”、“Dorian”、“Phrygian”、“Lydian”、“Mixolydian”、“Aeolian”或”Locrian”
“Chromatic”、“Whole Tone”或”Diminished”

buildScale("C", 3, "Major")
buildScale("D", 2, "Dorian")
buildScale("F#", 3, "minor")

transpose(pitchSet, origKey, newKey)

transpose函数接受以整数列表形式在一个调中的音高集，并返回转移到新调的集合。origKey参数是音高集所属的原始调，newKey是将要转移到的调；origKey和newKey都使用来自一组可能有效调的字符串指定。

transpose([60, 62, 67], "C", "G")
transpose([60], "Cm", "Fm") # 返回[65]