API/playdate.sound.instrument - Playdate 非公式開発まとめ wiki

playdate.sound.instrument

playdate.sound.instrument は、複数の Synth をまとめて扱うための音源です。
単体の Synth は基本的に1ボイスの音源ですが、instrument は複数の Synth を登録して、

音域ごとに別の Synth を使う
サンプルをキーごとに割り当てる
複数ボイスでポリフォニック再生する
Track / Sequence から演奏する

といった用途に使います。

playdate.sound.instrument
関連ページ

生成・読み込み

new(synth)

新しい instrument を作成します。

カテゴリ	名前	型	省略	説明
引数	synth	Synth	o	Synthを指定します。省略した場合は空の状態となります

-- 引数に synth を指定した場合.
local synth = playdate.sound.synth.new(playdate.sound.kWaveSine)
local inst = playdate.sound.instrument.new(synth)
 
-- 引数に synth を省略した場合.
local synth = playdate.sound.synth.new(playdate.sound.kWaveSine)
local inst = playdate.sound.instrument.new()
inst:addVoice(synth) -- 個別に追加可能.

instrument:addVoice(v, note, rangeend, transpose)

instrument に Synth を voice として追加します。

カテゴリ	名前	型	省略	説明
引数	v	Synth	x	登録するSynth
	note	integer / string	o	MIDIノート番号 or 音階文字列 ("Db3" など)
	rangeend	integer / string	o	MIDIノート番号 or 音階文字列 ("Db3" など)
	transpose	integer	o	半音単位で指定

引数の数で意味が変化するので、それぞれについて説明します。

【引数が1つ】addVoice(synth) の場合: 音域指定なしで synth を追加します。; この場合、その synth は instrument の通常ボイスとして使われ、複数追加すれば、同時発音用のボイスとして使えます。

local inst = playdate.sound.instrument.new()
-- 4ボイス程度のポリフォニック音源にする.
for i = 1, 4 do
    local s = playdate.sound.synth.new(playdate.sound.kWaveSquare)
    s:setADSR(0.01, 0.1, 0.8, 0.2)
    inst:addVoice(s)
end

【引数が2つ】addVoice(synth, note) の場合

その voice を特定のノート専用にします。

note だけを指定した場合、その voice はそのノートでのみ使われます。

また、そのノートを鳴らしたときに通常速度で再生されるようにトランスポーズされます。

sample の場合：rate = 1.0
synth の場合：C4

が基準になります。

これは例えば、ドラムキット的な使い方に向いています。

local kick = playdate.sound.synth.new(kickSample)
local snare = playdate.sound.synth.new(snareSample)
local inst = playdate.sound.instrument.new()
-- "C2" を Kick に割り当て.
inst:addVoice(kick, "C2")
-- "D2" を Snare に割り当て.
inst:addVoice(snare, "D2")
inst:playNote("C2") -- kick
inst:playNote("D2") -- snare

【引数が3つ】addVoice(synth, note, rangeend) の場合: その voice を note から rangeend までの範囲に割り当てます。; 範囲は両端を含みます。; 例えば、"C3" ～ "B3" を指定した場合、C3 から B3 までがその synth の担当範囲になります。

範囲指定した場合、範囲の最初のノート、つまり note が通常速度・基準ピッチになるようにトランスポーズされます。

サンプル音源を音域ごとに割り当てる場合に重要です。

inst:addVoice(lowSampleSynth,  36, 47) -- "C2" 〜 "B2"
inst:addVoice(midSampleSynth,  48, 59) -- "C3" 〜 "B3"
inst:addVoice(highSampleSynth, 60, 72) -- "C4" 〜 "C5"

【引数が4つ】addVoice(synth, note, rangeend, transpose) の場合

最後の transpose で、その voice の再生音を半音単位で移調します。

単位は半音です。

12 = 1オクターブ上
-12 = 1オクターブ下

inst:addVoice(synth, "C3", "B3", 12) -- ノート範囲は "C3" 〜 "B3"、実際の音程は 1オクターブ上にピッチシフトする

再生・停止

instrument:playNote(frequency, vel, length, when)

instrument でノートを再生します。
MIDIノート番号指定で再生したい場合は playMIDINote() を使います。

カテゴリ	名前	型	省略	説明
引数	frequency	integer / string	x	周波数 or 音階文字列
	vel	number	o	ベロシティ ("0.0〜1.0")。省略時は "1.0"
	length	number	o	ノート長 (秒)。省略時は noteOff(note) が呼ばれるまで鳴り続ける
	when	number	o	何秒後に再生するか (秒)。省略時は "0.0" (即時再生)

-- "C4" を ペロシティ "0.8" で、1秒後に 0.5秒再生.
inst:playNote("C4", 0.8, 0.5, 1.0)

instrument:playMIDINote(note, vel, length, when)

カテゴリ	名前	型	省略	説明
引数	frequency	integer / string	x	MIDIノート番号 or 音階文字列
	vel	number	o	ベロシティ ("0.0〜1.0")。省略時は "1.0"
	length	number	o	ノート長 (秒)。省略時は noteOff(note) が呼ばれるまで鳴り続ける
	when	number	o	何秒後に再生するか (秒)。省略時は "0.0" (即時再生)

MIDI ノート番号

60 = C4
61 = C#4
69 = A4

小数も使えます。

inst:playMIDINote(60.5)

これは C4 と C#4 の中間のようなピッチになります。

instrument:noteOff(note, when)

指定ノートを停止します。

カテゴリ	名前	型	省略	説明
引数	note	integer	x	停止したいMIDIノート番号
引数	when	number	o	何秒後に停止するか。省略時は即時停止

この関数は synth:stop() のような強制停止ではなく、「ノートオフ信号」を送ります。
登録されている synth に release が設定されていれば、release に従って自然に減衰します。

instrument:allNotesOff()

現在鳴っているすべてのノートに stop / note off 信号を送ります。

ピッチ操作

instrument:setTranspose(halfsteps)

instrument 全体を移調します。

カテゴリ	名前	型	省略	説明
引数	halfsteps	number	x	移調値 (単位は半音)

移調値には小数も使えます。

inst:setTranspose(12)   -- 1オクターブ上
inst:setTranspose(-12)  -- 1オクターブ下
inst:setTranspose(0.5)  -- 半音の半分

instrument:setPitchBend(amount)

instrument 全体にピッチベンドを適用します。

カテゴリ	名前	型	省略	説明
引数	amount	number	x	ピッチベンド値 ("-1.0〜1.0")

amount は pitch bend range に対する割合です。(→setPitchBendRange())

0.0 = ベンドなし
1.0 = 最大上方向
-1.0 = 最大下方向

inst:setPitchBendRange(12) -- pitch bend range = 12
inst:setPitchBend(1.0) -- +12半音=1オクターブ上
inst:setPitchBend(-0.5) -- -6半音

instrument:setPitchBendRange(halfsteps)

ピッチベンドの最大範囲を設定します。
実際にはピッチベンドを行うには setPitchBend() を使用します。

カテゴリ	名前	型	省略	説明
引数	amount	number	x	ピッチベンドの範囲 (半音単位)

デフォルトは 12、つまり上下1オクターブ分です。

音量

instrument:setVolume(left, right)

instrument 全体の音量を設定します。

カテゴリ	名前	型	省略	説明
引数	left	number	x	音量 ("0.0 ～ 1.0")。rightの指定がある場合は左側の音量
引数	right	number	o	右側の音量

instrument:getVolume()

instrument の現在音量を取得します。
mono の場合は1値、stereo の場合は left / right の2値を返します。

カテゴリ	名前	型	省略	説明
戻り値	left_or_mono	number	x	音量。ステレオの場合は左側の音量
戻り値	right	number	o	ステレオの場合は右側の音量

資料

1. 単一 synth を instrument 化する

local synth = playdate.sound.synth.new(playdate.sound.kWaveSine)
synth:setADSR(0.01, 0.1, 0.8, 0.2)
local inst = playdate.sound.instrument.new(synth)
inst:playNote("C4", 1.0, 0.5)

track:setInstrument() に渡す場合もこの形が使いやすいです。

2. ポリフォニック instrument を作る

local inst = playdate.sound.instrument.new()
for i = 1, 4 do
    local synth = playdate.sound.synth.new(playdate.sound.kWaveTriangle)
    synth:setADSR(0.01, 0.1, 0.7, 0.3)
    inst:addVoice(synth)
end
inst:playNote("C4", 0.8, 1.0)
inst:playNote("E4", 0.8, 1.0)
inst:playNote("G4", 0.8, 1.0)

同時に複数ノートを鳴らしたい場合、複数 voice を追加するのが基本です。

3. ドラムキット的に使う

local kickSample = playdate.sound.sample.new("sounds/kick")
local snareSample = playdate.sound.sample.new("sounds/snare")
local kick = playdate.sound.synth.new(kickSample)
local snare = playdate.sound.synth.new(snareSample)
local drums = playdate.sound.instrument.new()
drums:addVoice(kick, "C2")
drums:addVoice(snare, "D2")
drums:playNote("C2", 1.0)
drums:playNote("D2", 1.0)

特定ノートに特定サンプルを割り当てる使い方です。

4. サンプルを音域ごとに割り当てる

local inst = playdate.sound.instrument.new()
local low = playdate.sound.synth.new(playdate.sound.sample.new("sounds/piano_low"))
local mid = playdate.sound.synth.new(playdate.sound.sample.new("sounds/piano_mid"))
local high = playdate.sound.synth.new(playdate.sound.sample.new("sounds/piano_high"))
inst:addVoice(low,  36, 47)
inst:addVoice(mid,  48, 59)
inst:addVoice(high, 60, 72)

サンプラー的な使い方です。
広い音域を1つのサンプルだけで再生すると不自然になりやすいため、複数サンプルを音域ごとに割り当てる設計に向いています。

Synth との違い

Synthは単一音源です。

local synth = playdate.sound.synth.new()
synth:playNote("C4")

単発の効果音、単音リード、単純なサンプル再生に向いています。

それに対してinstrumentは複数の Synth をまとめる音源です。

local inst = playdate.sound.instrument.new()
inst:addVoice(synth1)
inst:addVoice(synth2)
inst:addVoice(synth3)

ポリフォニー
ドラムキット
マルチサンプル
sequence / track での演奏
音域ごとの音色切り替え

に向いています。

instrument は「複数の Synth を束ねて、演奏可能な楽器として扱うためのクラス」です。単音や単発SEなら Synth / SamplePlayer で十分ですが、音域割り当て・同時発音・ドラムキット・シーケンス再生を考えるなら instrument を使うのが自然です。

Playdate 非公式開発まとめ wiki