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

playdate.sound.track

playdate.sound.track は、Sequence の中に入れる「1パート分のノート列」です。

sequence
  ├─ track 1 -- メロディ
  ├─ track 2 -- ベース
  └─ track 3 -- ドラム

track 自体は音源ではなく、実際に鳴らすには Instrument または Synth を設定します。

playdate.sound.track
関連ページ

生成・音源設定

new()

新しい track を作成します。

track:setInstrument(inst)

track が鳴らす音源を設定します。

カテゴリ	名前	型	省略	説明
引数	inst	Instrument / Synth	x	音源

-- instrument を渡す場合.
local synth = playdate.sound.synth.new(playdate.sound.kWaveSine)
local inst = playdate.sound.instrument.new(synth)
track:setInstrument(inst)
 
-- synth を直接渡す場合.
-- 内部的にその synth 用の instrument が作られます
local synth = playdate.sound.synth.new(playdate.sound.kWaveSquare)
track:setInstrument(synth)

track:getInstrument()

track に設定されている Instrument を取得します。

カテゴリ	名前	型	説明
戻り値	-	Instrument	trackに設定されているInstrument

Synth を直接 setInstrument() した場合でも、取得するのは Instrument 扱いです。

ノート追加・取得・削除

track:addNote(step, note, length, velocity)

track に1つのノートイベントを追加します。

カテゴリ	名前	型	省略	説明
引数	step	integer	x	追加する位置 (Step)
	note	integer / string	x	追加するノート (MIDIノート番号 or 音階文字列)
	length	number	x	ノートの長さ (Step)
	velocity	number	o	Velocity (省略時は "1.0")

noteには「MIDIノート番号」または「音名文字列」を指定できます。

track:addNote(0, 60, 4)     -- C4
track:addNote(0, "C4", 4)
track:addNote(0, "Db3", 4)

なおgetNotes()で取得したときは、音名文字列ではなく MIDI ノート番号に変換されて返ります。

track:addNote(table)

テーブル形式で1つのノートを追加します。

track:addNote({
    step = 0,
    note = "C4",
    length = 4,
    velocity = 1.0
})

テーブル形式のデータ型は以下のとおりです。

{
    step = integer,
    note = number | string,
    length = integer,
    velocity = number
}

}
getNotes() が返す形式と互換性があります。

track:setNotes(list)

複数のノートをまとめて設定します。

カテゴリ	名前	型	省略	説明
引数	list	table[]	x	複数のノートのlist

listに指定する各要素は以下の形式です。

{
    step = integer,
    note = number | string,
    length = integer,
    velocity = number
}

スクリプトの例は以下のとおりです。

track:setNotes({
    { step = 0,  note = "C4", length = 2, velocity = 1.0 },
    { step = 2,  note = "D4", length = 2, velocity = 1.0 },
    { step = 4,  note = "E4", length = 2, velocity = 0.8 },
    { step = 6,  note = "G4", length = 2, velocity = 0.8 },
})

1音ずつ addNote() するより、パターンを一括で流し込む用途に向いています。

track:getNotes(step, endstep)

track に登録されているノートイベントを配列で返します。

カテゴリ	名前	型	省略	説明
引数	step	integer	o	取得するStep。省略時はすべてのノートを取得します。
引数	endstep	integer	o	取得するStepの範囲
戻り値	-	list	x	取得したノートのlist

引数なし

local notes = track:getNotes()

すべてのノートを取得します。

step のみ指定

local notes = track:getNotes(8)

指定 step にあるノートだけを取得します。

step と endstep を指定

local notes = track:getNotes(0, 16)

step から endstep までの範囲にあるノートを取得します。

endstep の位置にあるノートも含まれます。

戻り値のデータ形式は以下のとおりです。

{
    {
        step = integer,
        note = number,
        length = integer,
        velocity = number
    },
    ...
}

重要なのは、note が常に "MIDIノート番号" で返ることです。
例えば、

track:addNote(0, "C4", 4)

として追加しても、

local notes = track:getNotes()
print(notes[1].note) -- 60

のように数値で返ります。

track:removeNote(step, note)

指定 step にある、指定 note のノートイベントを削除します。

カテゴリ	名前	型	省略	説明
引数	step	integer	x	削除する Step数
引数	note	integer	x	MIDIノート番号

track:removeNote(0, 60) -- step 0 の C4 を削除

track:clearNotes()

track 内のすべてのノートを削除します。
パターンを作り直す場合や、エディタ的な実装で全消去したい場合に使います。

長さ・発音状態

track:getLength()

track の長さを step 単位で返します。

カテゴリ	名前	型	説明
戻り値	-	integer	trackの長さ

これは「最後のノートが終わる step」です。
例えば以下のトラックは、最後のノートは step 8 から長さ 2 なので、「8+2=10」となります。

track:addNote(0, "C4", 4)
track:addNote(8, "E4", 2)
track:getLength() -- 10

track:getNotesActive()

現在 track 上でアクティブになっているノート数を返します。

カテゴリ	名前	型	説明
戻り値	-	integer	アクティブなノート数

Sequence 再生中に、その track で現在鳴っているノート数を確認する用途です。

track:getPolyphony()

track 内で同時にアクティブになる最大ノート数を返します。

カテゴリ	名前	型	説明
戻り値	-	integer	同時にアクティブになる最大ノート数

既知の不具合: 現在これは MIDI ファイル由来の track でしか正常に動作しないとされています。; つまり、自分で addNote() / setNotes() した track に対しては、期待通りの値が返らない可能性があります。

ミュート

track:setMuted(flag)

track をミュート、またはミュート解除します。

カテゴリ	名前	型	省略	説明
引数	flag	boolean	x	trueでトラックをミュート

ControlSignal 関連

トラックに ControlSignal を追加します。

track:addControlSignal(controlsignal)

カテゴリ	名前	型	省略	説明
引数	controlsigna	ControlSignal	x	コントロールシグナル

controlsignal を track に追加しただけでは音は変わりません。
音として効果を出すには、その signal を何らかのモジュレーション入力に割り当てる必要があります。

track:getControlSignals()

track に割り当てられている ControlSignal の配列を返します。

カテゴリ	名前	型	説明
戻り値	-	playdate.sound.controlsignal[]	コントロールシグナルの配列

Playdate 非公式開発まとめ wiki