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

playdate.sound.sample

Sample は「音声データそのもの」を表すクラスです。
再生機能は持っていますが、実際には内部で SamplePlayer を作って再生する簡易関数です。

playdate.sound.sample
- 生成・読み込み
- フォーマット変更・取得
関連ページ

生成・読み込み

new(path)

音声ファイルを読み込み、メモリ上に sample オブジェクトを作成します。
読み込みに失敗した場合は、nil とエラーメッセージを返します。

local sample, err = playdate.sound.sample.new("sounds/hit")
if sample == nil then
    print(err)
end

効果音のような短い音声向けです。長いBGMを読み込むとメモリを消費するため、BGM用途なら FilePlayer の方が適しています。

new(seconds, format)

指定秒数ぶんの空のサンプルバッファを作成します。

local sample = playdate.sound.sample.new(
    2.0, -- 2.0秒のバッファを作成.
    playdate.sound.kFormat16bitStereo -- 16bit/ステレオ
)

format を省略した場合は、playdate.sound.kFormat16bitStereo になります。
主な用途は、あとから sample:load() で別の音声データを読み込むためのバッファ確保です。
これにより毎回バッファを再確保せずに済むため、メモリ断片化を避けやすいとされています。

指定可能な format

playdate.sound.kFormat8bitMono: 8bit/モノラル
playdate.sound.kFormat8bitStereo: 8bit/ステレオ
playdate.sound.kFormat16bitMono: 16bit/モノラル
playdate.sound.kFormat16bitStereo: 16bit/ステレオ

sample:load(path)

既存の sample バッファに、指定した音声ファイルを読み込みます。

local sample = playdate.sound.sample.new(2.0)
local ok = sample:load("sounds/hit")
if not ok then
    print("load failed")
end

ファイルが存在しない場合は nil を返します。
主な用途は、同じ sample オブジェクト・同じバッファを使い回して、メモリ再確保を減らすことです。

local sample = playdate.sound.sample.new(1.0)
sample:load("sounds/se1")
sample:play()
sample:load("sounds/se2")
sample:play()

ただし、読み込む音声が確保済みバッファより大きい場合の扱いには注意が必要です。安全に使うなら、あらかじめ十分な秒数のバッファを作っておくのがよいです。

フォーマット変更・取得

sample:decompress()

ADPCM 圧縮されたサンプルを、16-bit PCM データに展開します。
成功すると true、失敗すると false, errorMessage を返します。

local ok, err = sample:decompress()
if not ok then
    print(err)
end

重要なのは、展開しても音質は良くならないという点です。元のADPCM音声をPCM形式に戻すだけです。

必要になるケースは主に次です。

-- 逆再生したい
player:setRate(-1.0)
-- synth で sample を使いたい
synth:setSample(sample)

注意点として、メモリ使用量は "約4倍" になります。Playdate はメモリに余裕がある環境ではないため、必要なサンプルだけ展開するべきです。

sample:getFormat()

サンプルの音声フォーマットを返します。

戻り値は整数で、以下のいずれかです。

playdate.sound.kFormat8bitMono
playdate.sound.kFormat8bitStereo
playdate.sound.kFormat16bitMono
playdate.sound.kFormat16bitStereo

sample:getLength()

サンプルの長さを秒単位で返します。
戻り値は2つです。

local available, allocated = sample:getLength()

戻り値	意味
sampleSeconds	実際に利用可能な音声データの長さ
buffer_size_seconds	確保されているバッファ全体の長さ

録音用などで先に大きめのバッファを作った場合、実データ長とバッファ長が異なる可能性があります。

local sample = playdate.sound.sample.new(5.0)
local length, bufferLength = sample:getLength()
-- length は実データ長
-- bufferLength は確保済みバッファ長

sample:getSampleRate()

サンプルレートを整数で返します。

local rate = sample:getSampleRate()
print(rate) -- 44100 や 22050 など

getSubsample() や sampleplayer:setPlayRange() はフレーム単位を使うため、秒からフレームへ変換したいときに重要です。

local sampleRate = sample:getSampleRate()
-- 0.5秒の位置.
local startFrame = 0.5 * sampleRate
-- 1.0秒の位置.
local endFrame = 1.0 * sampleRate

sample:getSubsample(startOffset, endOffset)

元の sample の一部範囲を切り出し、新しい sample として返します。

local sample = playdate.sound.sample.new("sounds/voice")
local rate = sample:getSampleRate()
local sub = sample:getSubsample(
    math.floor(0.5 * rate),
    math.floor(1.0 * rate)
)

startOffset と endOffset は秒ではなく、フレーム単位です。バイト単位でもありません。
たとえば、サンプルレートが 44100 の場合：

0.5秒 = 22050フレーム
1.0秒 = 44100フレーム

用途としては、1つの効果音ファイルから一部だけを抜き出して鳴らしたい場合や、音声の一部分を別サンプルとして扱いたい場合です。

Playdate 非公式開発まとめ wiki