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

playdate.sound.sequence

playdate.sound.sequence は、Playdate のサウンドシーケンサーです。
単体で音を出すというより、

sequence
  ├─ track
  │   └─ instrument
  │       └─ synth
  ├─ track
  │   └─ instrument
  │       └─ synth
  ...

のように、複数の Track を持ち、それぞれの Track が Instrument を鳴らす構造です。
synth:playNote() は「今この音を鳴らす」用途ですが、sequence は「何ステップ目に何の音を鳴らすか」を並べて再生する用途です。

playdate.sound.sequence
関連ページ

生成

new(midi_path)

新しい sound sequence を作成します。

カテゴリ	名前	型	省略	説明
引数	midi_path	string	o	MIDIファイルのパス省略時は空のシーケンサーを生成
戻り値	-	playdate.sound.sequence	x	新しいシーケンサー

-- 空のシーケンサーを生成.
local seq = playdate.sound.sequence.new()
-- MIDI ファイルからシーケンサーを生成.
local seq2 = playdate.sound.sequence.new("music/stage1.mid")

MIDI を読み込んでも、各 track に適切な instrument が設定されていないと実際には音が鳴りません。

トラック管理

sequence:addTrack(track)

sequence に Track を追加します。

カテゴリ	名前	型	省略	説明
引数	track	Track	o	シーケンサーに追加するTrack 省略時は内部で新しいTrackを作成して追加します
戻り値	-	Track	o	引数省略時に生成した新しいTrack

track を追加しただけでは音は鳴りません。
track 側に、音源とノートイベントを設定する必要があります。

-- TrackにInstrumentを登録.
track:setInstrument(instrument)
-- Noteを登録.
track:addNote(...)

sequence:setTrackAtIndex(n, track)

sequence の指定位置に track を設定します。

カテゴリ	名前	型	省略	説明
引数	n	integer	x	トラック番号 (1始まり)
引数	track	Track	x	差し替えるトラック

-- Track1にメロディを追加.
seq:setTrackAtIndex(1, melodyTrack)
-- Track2にベースを追加.
seq:setTrackAtIndex(2, bassTrack)

sequence:getTrackAtIndex(n)

指定位置の Track を取得します。

カテゴリ	名前	型	省略	説明
引数	n	integer	x	トラック番号 (1始まり)
戻り値	-	Track	x	差し替えるトラック

MIDI ファイルから読み込んだ sequence の track を取得して、後から instrument を設定するような用途があります。

-- MIDIファイルからシーケンサーを生成.
local seq = playdate.sound.sequence.new("music/test.mid")
-- Synthを生成.
local synth = playdate.sound.synth.new(playdate.sound.kWaveSine)
-- Instrumentを生成.
local inst = playdate.sound.instrument.new(synth)
-- Trackに登録.
local track = seq:getTrackAtIndex(1)
track:setInstrument(inst)

sequence:getTrackCount()

sequence に含まれる track 数を返します。

カテゴリ	名前	型	説明
戻り値	-	integer	トラック数

MIDI 読み込み後に、各トラックに設定を行う場合に使えます。

for i = 1, seq:getTrackCount() do
    local track = seq:getTrackAtIndex(i)
    -- 各トラックに関する処理を行う.
end

再生・停止

sequence:play(finishCallback)

sequence の再生を開始します。
引数のfinishCallback は、sequence の再生が終了したとき、または停止したときに呼ばれるコールバックです。

カテゴリ	名前	型	省略	説明
引数	finishCallback	function(sequence)	o	再生停止・終了時のコールバック関数

play() は sequence 内の各 track を再生しますが、track に instrument が設定されていない場合、ノートイベントがあっても音が鳴りません。
最低限、以下のような構成が必要です。

最低限のSequence構成

sequence:stop()

sequence の再生を停止します。
play() に finishCallback を渡していた場合、stop() したときにも callback が呼ばれます。

sequence:isPlaying()

sequence が現在再生中かどうかを返します。

カテゴリ	名前	型	説明
戻り値	-	boolean	再生中であればtrue

if not seq:isPlaying() then
    seq:play() -- 再生中でなければ再生を開始する.
end

sequence:allNotesOff()

sequence 内のすべての track の instrument に対して、allNotesOff() メッセージを送ります。

再生位置

sequence:getCurrentStep()

sequence の現在の再生位置を step 番号で返します。

カテゴリ	名前	型	説明
戻り値	-	number	再生位置 (Step)。小数を返すこともあります

整数ではなく number です。テンポや再生中のタイミングによって、小数的な位置を返す可能性を考えておくと安全です。

sequence:goToStep(step, play)

sequence の再生位置を指定 step に移動します。

カテゴリ	名前	型	省略	説明
引数	step	integer	x	移動する再生位置 (Step)
引数	play	boolean	o	trueで再生位置にあるノートを発音します。デフォルトはfalseです

-- 先頭へ戻す
seq:goToStep(0)
-- 16 step 目に移動し、その位置の音も鳴らす
seq:goToStep(16, true)

長さ・テンポ

sequence:getLength()

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

カテゴリ	名前	型	説明
戻り値	-	number	最も長い trackの長さ (Step)

この関数は Sequence が管理している最も長い track の長さを返します。
track 単体の長さの場合は、track:getLength()で取得できます。

sequence:setTempo(stepsPerSecond)

sequence のテンポを設定します。

カテゴリ	名前	型	省略	説明
引数	stepsPerSecond	number	x	1秒あたりに進む Step数

単位は steps per second、つまり「1秒あたり何 step 進むか」で、一般的な BPM とは違います。
例えば「16ステップで1小節、4/4、120BPM」のように扱いたい場合、

120 BPM = 1分に120拍 = 1秒に2拍 (120÷60秒)
16分音符を 1 step とするなら、1拍 = 4 step → 1秒に 2 × 4 = 8 step

なので、

seq:setTempo(8) -- 4/4拍子 / 120 BPM

になります。

-- 4/4拍子
 local bpm = 120
 -- Sequenceのテンポに変換.
 local tempo = (bpm / 60) * 4

sequence:getTempo()

sequence のテンポを取得します。

カテゴリ	名前	型	説明
戻り値	-	number	単位は steps per second

ループ設定

sequence:setLoops(loopCount)

sequence 全体をループ範囲として設定します。

カテゴリ	名前	型	省略	説明
引数	loopCount	integer	x	ループ回数

sequence:setLoops(startStep, endStep, loopCount)

sequence のループ範囲を指定します。

カテゴリ	名前	型	省略	説明
引数	startStep	integer	x	ループ区間の開始 (Step)
	endStep	integer	x	ループ区間の終端 (Step)
	loopCount	integer	o	ループ回数 (省略時または "0" で無限ループ)

-- 48〜64 step の範囲を無限ループ.
seq:setLoops(48, 64, 0)

資料

1. 最小構成で sequence を鳴らす

local seq = playdate.sound.sequence.new()
local track = playdate.sound.track.new()
local synth = playdate.sound.synth.new(playdate.sound.kWaveSine)
local inst = playdate.sound.instrument.new(synth)
track:setInstrument(inst)
track:addNote(0,  "C4", 2, 1.0)
track:addNote(2,  "D4", 2, 1.0)
track:addNote(4,  "E4", 2, 1.0)
track:addNote(6,  "G4", 2, 1.0)
seq:addTrack(track)
seq:setTempo(4)
seq:play()

この場合、1秒に4 step 進みます。
各ノートの長さは 2 step なので、実時間では、

2 / 4 = 0.5 秒

です。

2. 無限ループする BGM パターン

local seq = playdate.sound.sequence.new()
local track = playdate.sound.track.new()
local synth = playdate.sound.synth.new(playdate.sound.kWaveSquare)
local inst = playdate.sound.instrument.new(synth)
track:setInstrument(inst)
track:addNote(0,  "C3", 1, 0.8)
track:addNote(4,  "E3", 1, 0.8)
track:addNote(8,  "G3", 1, 0.8)
track:addNote(12, "E3", 1, 0.8)
seq:addTrack(track)
seq:setTempo(8)
seq:setLoops(0, 16, 0)
seq:play()

setTempo(8) なので、16 step は 2 秒です。

16 / 8 = 2 秒

3. 再生・停止をボタンで切り替える

function playdate.update()
    if playdate.buttonJustPressed(playdate.kButtonA) then
        if seq:isPlaying() then
            seq:stop()
            seq:allNotesOff()
        else
            seq:goToStep(0)
            seq:play()
        end
    end
end

stop() だけで音が残る場合に備えて、allNotesOff() を併用すると安全です。

sequence と track の関係

sequence は「曲全体」や「パターン全体」で、track はその中の1パートです。
例えば、

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

のような構成になります。

sequence 側で行うことは、

seq:addTrack(track)
seq:setTempo(8)
seq:setLoops(0, 64, 0)
seq:play()
seq:stop()

track 側で行うことは、

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

という分担です。

Playdate 非公式開発まとめ wiki