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

playdate.sound.sampleplayer

SamplePlayer は、音声データをメモリに持つため、再生開始が軽く、効果音向きです。
長いBGMは FilePlayer の方が適しています。

---

---

生成・読み込み・サンプル設定

new(path)

音声ファイルを読み込み、新しい SamplePlayer を作成します。

カテゴリ	名前	型	省略	説明
引数	path	string	x	音声ファイルのパス
戻り値	-	_SamplePlayer	x	新しいSamplePlayer。読み込み失敗時は nil
	err?	string	o	読み込みエラー時はエラー文字列

-- soundsファルダにある "hit" を読み込む.
local se, err = playdate.sound.sampleplayer.new("sounds/hit")
if se == nil then
    print(err) -- 読み込みエラー時にログ出力.
end
 

new(sample)

既に読み込んだ playdate.sound.sample を使って sampleplayer を作成します。
同じサンプルを複数の player で使い回したい場合に便利です。

カテゴリ	名前	型	省略	説明
引数	sample	_SamplePlayer	x	読み込み済みのSample

local sample = playdate.sound.sample.new("sounds/jump")
-- 作成済みのSamplePlayerを元に読み込み.
local player = playdate.sound.sampleplayer.new(sample)
player:play()
 

sampleplayer:copy()

同じ sample、volume、rate を持つ新しい sampleplayer を返します。

local p1 = playdate.sound.sampleplayer.new("sounds/hit")
p1:setVolume(0.5)
p1:setRate(1.2)
-- SamplePlayerをコピーして作成.
local p2 = p1:copy()
p2:play()
 

sampleplayer:setSample(sample)

再生対象の Sample を差し替えます。

カテゴリ	名前	型	省略	説明
引数	sample	_SamplePlayer	x	差し替えるSample

sampleplayer:getSample()

現在設定されている Sample を返します。

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

再生・停止

sampleplayer:play(repeatCount, rate)

サンプルを再生します。

カテゴリ	名前	型	省略	説明
引数	repeatCount?	integer	o	繰り返し回数 (未指定の場合 "1")
	rate?	number	o	再生速度 (未指定の場合 "1.0")

repeatCountについて

repeatCount はループ回数指定です

• 省略: 1回再生
• 2以上: 指定回数ループ
• 0: 無限ループ

rateについて

rate を指定すると、その再生時だけ指定レートで鳴らします。

setRate() で設定済みの値より優先されます。

player:play(1, 2.0) -- 2倍速
player:play(1, 0.5) -- 半速、1オクターブ下
player:play(1, -1.0) -- 逆再生。ただし[[ADPCM]]では不可

sampleplayer:playAt(when, vol, rightvol, rate)

指定したオーディオデバイス時刻に再生予約します。

local t = playdate.sound.getCurrentTime()
-- 現在から 0.5秒後に再生.
player:playAt(t + 0.5)
 

when は「現在から何秒後」ではなく、playdate.sound.getCurrentTime() と同じ時間軸上の絶対時刻です。

カテゴリ	名前	型	省略	説明
引数	when	number	x	再生するオーディオデバイス時刻 (秒)
	vol?	number	o	音量 (デフォルト "1.0") rightvolの指定がある場合は左側の音量
	rightvol?	number	o	右側の音量
	rate?	number	o	再生速度 (デフォルト "1.0")

注意点として、予約できるイベントは1つだけです。playAt() を再度呼ぶと、前の予約は新しい予約で上書きされます。

sampleplayer:stop()

再生を停止します。
無限ループ再生を止める場合にも使います。

sampleplayer:isPlaying()

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

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

sampleplayer:setPaused(flag)

一時停止・再開します。
stop() とは違い、再生位置を保持したまま止めます。

音量

sampleplayer:setVolume(left, right)

再生音量を設定します。範囲は 0.0 から 1.0 です。

カテゴリ	名前	型	省略	説明
引数	left	number	x	左側の音量 (デフォルト "1.0") rightが省略されている場合は左右の音量となります
	right	number	o	右側の音量

right を省略すると、左右同じ音量になります。

player:setVolume(0.7) -- left=0.7, right=0.7
 

現在再生中で、かつ playAt() 側で個別音量を指定していない場合は、再生中の音量も変わります。

sampleplayer:getVolume()

現在の音量を返します。

カテゴリ	名前	型	省略	説明
戻り値	-	number	x	左側の音量。モノラルの場合は単一の値となります
	-	number?	o	右側の音量

local left, right = player:getVolume()
 

mono の場合は単一値、stereo の場合は left/right の2値を返します。

再生速度

sampleplayer:setRate(rate)

再生速度、つまりピッチを設定します。

カテゴリ	名前	型	省略	説明
引数	rate	number	x	再生速度 (標準は "1.0")

player:setRate(1.0) -- 通常
player:setRate(0.5) -- 1オクターブ下
player:setRate(2.0) -- 1オクターブ上
player:setRate(-1.0) -- 逆再生
 

sampleplayer は負の rate による逆再生が可能です。ただし ADPCM エンコードされたファイルでは逆再生できません。

sampleplayer:getRate()

現在の再生レートを返します。

カテゴリ	名前	型	説明
戻り値	-	number	再生速度 (標準は "1.0")

sampleplayer:setRateMod(signal)

再生レートにモジュレーション信号を加えます。

カテゴリ	名前	型	省略	説明
引数	signal?	Signal	o	シグナル (LFO)

-- LFOシグナルを生成.
local lfo = playdate.sound.lfo.new(playdate.sound.kLFOSine)
lfo:setRate(4) -- 速度 "4.0"
lfo:setDepth(0.1) -- LFOデプス "0.1"
-- SamplePlayer設定.
player:setRate(1.0) -- 再生速度 "1.0"
player:setRateMod(lfo) -- LFOシグナルを設定.
 

setRate(1.0) の値に、signal の出力が加算される形です。

シグナルを解除する場合は、"nil" を設定します。

player:setRateMod(nil) -- モジュレーション信号を無効化.
 

再生位置・長さ

sampleplayer:setOffset(seconds)

再生位置を秒単位で設定します。

カテゴリ	名前	型	省略	説明
引数	seconds	number	x	再生位置 (秒)

-- 0.5秒の位置に移動.
player:setOffset(0.5)
player:play()
 

注意点として、引数の "seconds" は rate の影響を受けない値です。
つまり、2倍速で再生していても「サンプル上の0.5秒位置」という意味です。

sampleplayer:getOffset()

現在の再生位置を秒単位で返します。
setOffset()と同様に rate 補正されない値です。

カテゴリ	名前	型	説明
戻り値	-	number	現在の再生位置 (秒)

sampleplayer:getLength()

サンプルの長さを秒単位で返します。

カテゴリ	名前	型	説明
戻り値	-	number	サンプルの長さ (秒)

戻り値は再生レートでスケーリングされません。
たとえば、長さ2秒のサンプルを rate = 2.0 で再生しても、getLength() は2秒を返します。実際の再生時間は約1秒になります。

sampleplayer:setPlayRange(start, _end)

サンプル内の再生範囲を指定します。

カテゴリ	名前	型	省略	説明
引数	start	integer	x	開始範囲
	_end	integer	x	終端範囲

引数は秒ではなく「フレームオフセット」です。
たとえば 44.1kHz のサンプルなら、44100フレームがおよそ1秒です。

-- 44.1kHz想定で、0.5秒〜1.0秒あたりを再生
player:setPlayRange(22050, 44100)
 

秒指定したい場合は、サンプルレートを前提に変換する必要があります。

コールバック

sampleplayer:setFinishCallback(func, arg)

再生完了時に呼ばれるコールバックを設定します。

カテゴリ	名前	型	省略	説明
引数	func	function(sample, arg)	x	再生完了時に呼び出される関数。 第1引数にSample、第2引数に任意の arg が渡されます
	arg?	any	o	funcの引数

player:setFinishCallback(function(sample, arg)
    -- 再生完了コールバック.
    print("finished", arg)
end, "jump_se") -- コールバック引数.
 

sampleplayer:setLoopCallback(callback, arg)

サンプルがループするたびに呼ばれるコールバックを設定します。

カテゴリ	名前	型	省略	説明
引数	callback	function(sample, arg)	x	ループ時に呼び出される関数。 第1引数にSample、第2引数に任意の arg が渡されます
	arg?	any	o	callbackの引数

-- ループコールバックを登録.
player:setLoopCallback(function(sample, arg)
    print("loop", arg)
end, "bg_loop")
player:play(0) -- 無限ループ再生.
 

play(0) の無限ループや、play(3) のような複数回ループ時に使います。

関連ページ

• API
• API/playdate.sound.fileplayer
• API/playdate.sound.instrument
• API/playdate.sound.sample
• API/playdate.sound.synth
• PCM
• サンプルプレイヤー
• 用語集