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

playdate.sound.fileplayer

FilePlayer は _SoundSource を継承する音声ソースです。名前の通り、音声ファイルをディスクからストリーミング再生するためのクラスです。
fileplayer はファイル全体を即座にメモリへ展開するのではなく、再生用バッファを使って逐次読み込むため、

BGMなど、長めの音声を扱いやすい
ただしバッファ不足による underrun（供給切れ）が起こりうる
setOffset() の反応速度とバッファサイズにトレードオフがある

という特徴があります。

効果音など、短めの音声を再生する場合はSamplePlayerを使います。

playdate.sound.fileplayer
関連ページ

生成・読み込み

new(buffersize)

空の fileplayer オブジェクトを生成します。
この時点では再生ファイルは未設定で、後から :load() で読み込む前提です。

カテゴリ	名前	型	省略	説明
引数	buffersize?	number	o	再生用データバッファのサイズを秒単位で指定

バッファが「短い (小さい)」ほど:

setOffset() 呼び出し時の反応が速くなります
その代わり buffer underrun の可能性が上がります

つまり、シーク性能重視なら短め、安定再生重視なら長めです。

向いている使い方

まずプレイヤーだけ作りたい
後から状況に応じて load() で別ファイルを差し替えたい
再利用したい

new(path, buffersize)

再生対象のファイルパス付きで fileplayer を生成します。

カテゴリ	名前	型	省略	説明
引数	path	string	x	再生対象ファイルへのパス
引数	buffersize?	number	o	バッファサイズ（秒）

重要点

new(path)で生成した時点ではまだ実ファイルはロードされません。

実際の読み込みは

:play()
:setBufferSize()

のどちらかが呼ばれた時に行われます。

初期化コストを下げるため、遅延ロードになっています。
つまり、new(path) は「ファイルを指定する」だけで、即再生可能な状態まで準備されるとは限りません。

fileplayer:load(path)

次に play() した時に再生するファイルを指定します。

カテゴリ	名前	型	省略	説明
引数	path	string	x	再生するファイルパス

この関数を呼び出すと、「再生オフセットが先頭に戻り」「ループ範囲がクリア」されます。
また、play()で再生中の場合には呼びだすことができません。

fileplayer:setBufferSize(seconds)

再生バッファサイズを秒単位で設定します。

カテゴリ	名前	型	省略	説明
引数	seconds	number	x	バッファサイズ

バッファが大きくするほど underrun が発生しなくなりますが、メモリを多く消費します。

バッファサイズが短い: 軽い・シーク反応よい・途切れやすい
バッファサイズが長い: 安定・重い・シーク反応鈍い

再生・停止

fileplayer:play(repeatCount)

ファイルを開いて再生を開始します。
バッファサイズが未設定の場合、0.25秒の再生バッファを作成して埋めてから再生します。

カテゴリ	名前	型	省略	説明
引数	repeatCount?	integer	o	再生を繰り返す回数 ("0" で無限ループ) 省略時は "1" となります
戻り値	-	boolean	x	再生に成功したかどうか
戻り値	-	string?	o	再生に失敗した場合、エラー文字列

repeatCount の意味

省略: 1回だけ再生
0: 無限ループ
1: 1回ループしてから末尾まで進む、ではなく、説明上は「ループ処理は 2 以上または 0 で意味を持つ」箇所があるので注意
2 以上: ループ回数付き再生

戻り値の実務上の意味

エラーとなる原因としては以下の理由が考えられます。

ファイルが開けない
バッファ設定に失敗
チャンネル追加に失敗

fileplayer:stop()

再生を停止し、再生位置を先頭に戻します。

挙動

stop()を呼び出すと以下の挙動いとなります。

再生停止
playback offset を 0 にリセット
finish callback を呼ぶ

pause() と異なり、再生位置がリセットされます。

setFinishCallback() を設定している場合、stop() によっても finish callback が走るため、自然終了と手動停止を区別したいなら追加フラグ管理が必要になる場合があります。

fileplayer:pause()

再生を一時停止しますが、play()すると、停止した位置から再生が開始します。
stop()の場合、再生位置は頭に戻ります。

再生の状態

fileplayer:isPlaying()

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

カテゴリ	名前	型	説明
戻り値	-	boolean	再生中かどうか

fileplayer:getLength()

音声ファイル全体の長さを秒単位で返します。
現在再生している位置を取りたい場合は getOffset()を使用します。

カテゴリ	名前	型	説明
戻り値	-	number	音声ファイル全体の長さ

fileplayer:getOffset()

現在の再生位置を秒単位で返します。
トータルの長さを取得したい場合はgetLength()を使用します。

カテゴリ	名前	型	説明
戻り値	-	number	現在の位置

重要点: この値は rate による補正をしない値です。; つまり setRate(2.0) で倍速再生していても、返ってくるのは「ファイル中のオフセット秒数」であり、体感再生時間そのものではありません。

fileplayer:setOffset(seconds)

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

カテゴリ	名前	型	省略	説明
引数	seconds	number	x	新しい再生位置

注意点: getOffset()と同じく、この値は rate (再生速度) の補正なしです。; つまり純粋なファイル上の位置を指定します。
バッファサイズとの関係: setOffset() のレスポンスはバッファ長に影響されます。; 短いバッファの方が、オフセット変更の反映は速いです。

速度・音量

fileplayer:getRate()

現在の再生レート (再生速度) を返します。

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

fileplayer:setRate(rate)

再生速度を設定します。

カテゴリ	名前	型	説明
引数	rate	number	再生速度 (デフォルト 1.0)

1.0 = 通常速度
0.5 = 1オクターブ下
2.0 = 1オクターブ上

ストリーム再生のため、fileplayer は逆再生できません。
つまり rate < 0 は不可です。

fileplayer:getVolume()

現在の音量を返します。

カテゴリ	名前	型	省略	説明
戻り値	-	number	x	left (ステレオ) or mono
戻り値	-	number?	o	right (ステレオ)

音源によって、Lua 側では戻り値の個数が変わるので、扱う時は少し注意が必要です。

モノラル音源なら単一値
ステレオ音源なら (left, right) の2値

local l, r = fp:getVolume()
if r == nil then
    -- mono
else
    -- stereo
end

fileplayer:setRateMod(signal)

再生レートに対するモジュレータ信号を設定します。

カテゴリ	名前	型	省略	説明
引数	signal?	Signal	o	再生レートに加算する値

この signal は setRate() で設定したベース値に加算されます。
つまり概念的には:

実効 rate = setRate() の値 + rateMod signal

です。
nil を渡すとモジュレータを解除します。

用途

LFO でピッチ揺れ
エンベロープで時間変化
独自 signal による速度変調

注意

もともと fileplayer は逆再生不可なので、変調結果が負方向に行くような設計は避けた方がよいです。

fileplayer:setVolume(left, right, fadeSeconds, fadeCallback, arg)

再生音量を設定します。

カテゴリ	名前	型	省略	説明
引数	left	number	x	設定する音量。(0.0〜1.0) この引数のみ指定した場合は左右の同じ音量を指定します
	right?	number	o	右側の音量
	fadeSeconds?	number	o	フェード時間 (秒) 音量が現在の音量から指定時間フェードします
	fadeCallback?	fun(self: _FilePlayer, arg?: any)	o	フェード完了時のコールバック
	arg?	any	o	fadeCallback の引数

例

fp:setVolume(1.0, 1.0)          -- 通常
fp:setVolume(0.5)               -- 左右とも0.5
fp:setVolume(1.0, 0.2)          -- 左右別
-- 2秒フェードアウト.
fp:setVolume(0, nil, 2.0, function(player)
    print("fade out finished") -- フェード完了時のコールバック.
end)

左右別の音量を指定することでパンニングが実現できます。

under run

underrun とは、再生中に、ファイルからの読み込みが間に合わず、再生すべきデータが尽きた状態です。
ストリーミング系ならではのエラーです。

fileplayer:didUnderrun()

underrun が発生したかどうかを返します。

カテゴリ	名前	型	説明
戻り値	-	boolean	underunが発生したかどうか

用途

finish callback の中で underrun を確認する用途が想定されています。

たとえば:

再生が正常終了したのか
バッファ不足で止まったのか

を判定したい時に使えます。

動作を安定したい場合は setBuffetSize() でバッファサイズを増やします。ただしメモリ消費量やシーク速度のトレードオフが発生します。

fileplayer:setStopOnUnderrun(flag)

underrun 発生時の挙動を設定します。

カテゴリ	名前	型	省略	説明
引数	flag	boolean	x	true:underrunで停止 false:停止せずに途切れ途切れで再生

コールバック

fileplayer:setFinishCallback(func, arg)

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

カテゴリ	名前	型	省略	説明
引数	func	fun(self: _FilePlayer, arg?: any)	x	再生完了時に呼び出される関数
引数	arg?	any	o	funcに渡す引数

コールバックに渡るもの

第1引数: fileplayer 自身
第2引数: 任意の arg

用途

再生終了後に次の曲へ
UI更新
リソース解放
underrun 確認

注意

stop() でも finish callback が呼ばれます。

fp:setFinishCallback(function(player, tag)
    print("finished", tag)
    if player:didUnderrun() then
        print("underrun happened")
    end
end, "bgm1")

fileplayer:setLoopCallback(callback, arg)

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

カテゴリ	名前	型	省略	説明
引数	callback	fun(self: _FilePlayer, arg?: any)	x	ループ時に呼び出される関数
引数	arg?	any	o	callbackに渡す引数

コールバック発火条件

play(repeatCount) の repeatCount は

0（無限ループ）
2 以上

でないと、この callback は呼ばれません。

コールバックに渡るもの

第1引数: fileplayer 自身
第2引数: 任意の arg

fileplayer:setLoopRange(start, _end, loopCallback, arg)

ファイル全体ではなく、一部分だけをループ対象にするための設定です。
例えばBGMにイントロ部とループ区間がある場合に使用します。

カテゴリ	名前	型	省略	説明
引数	start	number	x	ループ開始 (秒)
	_end	number	x	ループ終了 (秒)
	loopCallback?	fun(arg?: any): nil	o	ループ時に呼び出される関数
	arg?	any	o	loopCallbackの引数

サンプルコード

local fp = playdate.sound.fileplayer.new("myaudiofile")
-- 10〜20秒区間をループ.
fp:setLoopRange(10, 20)
-- 3回ループ再生.
fp:play(3)

資料

注意点

1. fileplayer は「長い音を扱うためのストリーミング再生器」

短い効果音を即座に鳴らすというより、

BGM
長いボイス
環境音
長尺SE

向きです。

2. バッファサイズがかなり重要

このクラスは buffersize / setBufferSize() の存在からもわかる通り、使い勝手がバッファ設計にかなり依存します。

安定性重視 → 大きめ
シーク反応重視 → 小さめ

3. pause() と stop() の意味がはっきり違う

音楽プレイヤー的に使うなら非常に重要です。

一時停止UI → pause()
完全停止UI → stop()

4. ループには少し条件がある

単に setLoopRange() しただけでなく、play(repeatCount) 側の値が重要です。

ループ動作や loop callback を期待するなら repeatCount = 0 または 2以上を意識した方が安全です。

5. 逆再生はできない

sampleplayer 的な感覚で負の rate を期待しない方がよいです。

最小使用例

local pd = playdate
local snd = pd.sound
local fp = snd.fileplayer.new("audio/bgm", 0.5)
fp:setFinishCallback(function(player)
    print("finished")
    if player:didUnderrun() then
        print("buffer underrun")
    end
end)
fp:setVolume(1.0)
fp:setRate(1.0)
local ok, err = fp:play(0) -- 無限ループ
if not ok then
    print("play error:", err)
end

Playdate 非公式開発まとめ wiki