メインコンテンツまでスキップ

サウンドの再生

Soundコンポーネントは、1つのエンティティのサウンドを、名前の付いたスロットに保持します。スロットは、足音、エンジンのうなり、セリフの一言といった、エンティティが出せる1つのサウンドです。スロットは、どのオーディオアセットをどのように再生するかを指定するもので、名前を指定して再生します。

スロット​

各スロットには、次のプロパティがあります。かっこ内は、エディターでの名前です。

プロパティデフォルト説明
name(Name)スロットを再生するときに指定する名前。コンポーネント内で一意でなければなりません
asset(Asset)スロットが再生するオーディオアセット
volume(Volume)1サウンドの音量。0から1の範囲です
pitch(Pitch)1サウンドの再生速度。2にすると、速度が2倍になり、1オクターブ高くなります
loop(Loop)false停止されるまでサウンドを繰り返すかどうか
overlap(Overlap)falseスロットをもう一度再生したときに、サウンドのコピーをもう1つ追加するか、サウンドを最初から再生し直すか
autoPlay(Auto Play)falseコンポーネントが有効になった時点でスロットを再生するかどうか
startTime(Start Time)0アセット内でサウンドが始まる位置(秒単位)
duration(Duration)アセットのうち再生する長さ(秒単位)。未設定のままにすると、最後まで再生します

addSlot()は、スロットを作成して返します。コンポーネントのスロットはslotsオブジェクトにあり、slot()は名前でスロットを探します。

entity.addComponent('sound', { positional: false });

entity.sound.addSlot('footsteps', {
asset: footstepsAsset.id,
loop: true,
volume: 0.6
});

const slot = entity.sound.slot('footsteps');
slot.pitch = 1.2;

entity.sound.removeSlot('footsteps');

再生、一時停止、停止​

コンポーネントは、スロットを名前で再生します。これらはエンジンのメソッドで、どの環境でも同じです。コンポーネントには、スクリプトではthis.entity.soundとして、Reactでは<Entity>のrefを通して、Web Componentsでは<pc-sound>要素のcomponentプロパティを通してアクセスします。

entity.sound.play('footsteps'); // スロットを最初から再生します
entity.sound.pause('footsteps'); // その位置で一時停止します
entity.sound.resume('footsteps'); // その位置から再開します
entity.sound.stop('footsteps'); // 停止します

entity.sound.pause(); // 名前を渡さない場合: すべてのスロットを一時停止します
entity.sound.resume(); // すべてのスロットを再開します
entity.sound.stop(); // すべてのスロットを停止します

スロットの状態を調べるには、コンポーネントのisPlaying()、isPaused()、isStopped()、isLoaded()に、それぞれスロットの名前を渡します。スロットには、同じ4つがプロパティとしてあり、独自のplay()、pause()、resume()、stop()もあります。

const slot = entity.sound.slot('footsteps');
if (slot.isPlaying) {
slot.stop();
} else {
slot.play();
}

play()は、開始したサウンドインスタンスを返します。再生中の特定のサウンドを制御するには、このインスタンスを使います。コンポーネントにその名前のスロットがない場合や、コンポーネントまたはそのエンティティが無効になっている場合は、nullを返します。

ループ​

loopを設定したスロットは、停止するまで繰り返します。設定していないスロットは、1回再生して自動的に止まります。loopは、スロットの再生中にも変更できます。オフにすると、サウンドは現在の回を最後まで再生して止まります。

サウンドのオーバーラップ​

デフォルトでは、スロットは一度に1つのサウンドを再生します。再生中のスロットを再生すると、サウンドを停止して、最初から再生し直します。これは、音楽やエンジン音のように、1つだけ鳴っているべきサウンドには適していますが、連続するワンショットサウンドは途切れてしまいます。銃声が鳴るたびに、直前の銃声が消えてしまうのです。

overlapを設定すると、play()のたびに、まだ再生中のサウンドと並行して、サウンドのコピーがもう1つ再生されます。

entity.sound.addSlot('shot', { asset: shotAsset.id, overlap: true });

entity.sound.play('shot');
entity.sound.play('shot'); // 1発目が鳴り続けている間に、2発目を再生します

オーバーラップするスロットは、次の3つの点で動作が異なります。

  • プロパティは次回の再生から適用される。 オーバーラップしないスロットでvolume、pitch、startTime、durationを変更すると、再生中のサウンドが変わります。オーバーラップするスロットでは、すでに再生中のサウンドは、開始時の値を保ちます。Soundコンポーネントのvolumeとpitchを変更しても、これらのサウンドには反映されません。loopは例外で、再生中のすべてのサウンドに常に適用されます。
  • サウンドはエンティティがなくなった後も鳴り続ける。 エンティティが破棄されたとき、またはそのSoundコンポーネントが削除されたとき、オーバーラップするサウンドは最後まで再生されます。そのため、破棄された敵の爆発音も最後まで聞こえます。ほかのスロットのサウンドは、ただちに停止します。
  • コンポーネントを無効にしても、サウンドは一時停止されない。 最後まで再生されます。

スロットが再生しているサウンドは、そのinstances配列に入っています。オーバーラップするスロットを1秒間に何度も再生すると、インスタンスが大量にたまることがあります。インスタンスは1つごとに処理時間を消費するので、連続するサウンドを鳴らす頻度には上限を設けてください。

音量とピッチ​

サウンドの音量は、スロットのvolumeにコンポーネントのvolumeを掛けたもので、ピッチは、スロットのpitchにコンポーネントのpitchを掛けたものです。コンポーネントの値はエンティティ全体の音を上げ下げするために使い、スロットの値はそのサウンド同士のバランスを取るために使います。

entity.sound.volume = 0.5; // このエンティティが再生するすべてのサウンドが、半分の音量になります
entity.sound.slot('footsteps').volume = 0.6; // 足音は0.5 × 0.6 = 0.3になります

音量は、0から1の範囲に制限されます。ピッチは再生速度なので、サウンドの音の高さだけでなく、長さも変わります。ピッチが2なら、半分の時間で再生されます。ピッチを0.01未満にすることはできません。

繰り返し鳴るサウンドは、少し変化を付けると単調さが和らぎます。ワンショットサウンドでは、再生のたびにランダムなピッチを設定します。

const slot = entity.sound.slot('shot');
slot.pitch = 0.9 + Math.random() * 0.2;
slot.play();

これらにさらに掛けられるマスター音量については、音量とミキシングを参照してください。

ファイルの一部の再生​

startTimeとdurationは、スロットをアセットの一区間に限定します。単位は秒です。両方を設定すると、スロットはstartTimeからduration秒間再生し、ループする場合はその区間をループします。これにより、複数のサウンドがオーディオスプライトとして1つのファイルを共有できます。また、サウンドの冒頭を飛ばして、本体の部分だけをループさせることもできます。

entity.sound.addSlot('explosion', {
asset: sfxAsset.id,
startTime: 3,
duration: 1.3
});

自動再生​

autoPlayを設定したスロットは、コンポーネントが有効になったときに再生されます。つまり、シーンの開始時、後からエンティティが有効になったとき、またはすでに有効なコンポーネントにスロットが追加されたときです。BGMや環境音のループを、コードなしで再生するもっとも簡単な方法です。

ブラウザーは、ユーザーがページを操作するまでオーディオを保留するので、自動再生されるサウンドは、最初のクリックやタップまで聞こえません。自動再生とユーザー操作を参照してください。

有効化と無効化​

Soundコンポーネント、またはそのエンティティを無効にすると、再生中のスロットが一時停止します。再び有効にすると、それらが再開し、まだ再生されていないautoPlayスロットも再生されます。コンポーネントが無効な間、play()は何もせず、nullを返します。

例​

このエンジンアプリは、オーディオスプライトとして、1つのファイルから4つのサウンドを切り出し、それぞれにスロットを与えます。ボタンを押すとスロットが再生され、スロットが再生されるたびに、そのボックスがジャンプします。

ライブサンプル
import {
AppBase,
AppOptions,
Asset,
AudioHandler,
CameraComponentSystem,
Color,
createGraphicsDevice,
DEVICETYPE_WEBGPU,
Entity,
FILLMODE_FILL_WINDOW,
LightComponentSystem,
RenderComponentSystem,
RESOLUTION_AUTO,
SoundComponentSystem,
SoundManager,
StandardMaterial
} from 'playcanvas';

// 使用するコンポーネントシステムとリソースハンドラーを指定してアプリケーションを作成します
const canvas = document.getElementById('application');
const device = await createGraphicsDevice(canvas, {
deviceTypes: [DEVICETYPE_WEBGPU]
});
device.maxPixelRatio = Math.min(window.devicePixelRatio, 2);

const options = new AppOptions();
options.graphicsDevice = device;
options.soundManager = new SoundManager();
options.componentSystems = [
RenderComponentSystem,
CameraComponentSystem,
LightComponentSystem,
SoundComponentSystem
];
options.resourceHandlers = [AudioHandler];

const app = new AppBase(canvas);
app.init(options);
app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
app.setCanvasResolution(RESOLUTION_AUTO);
window.addEventListener('resize', () => app.resizeCanvas());
app.start();

app.scene.ambientLight = new Color(0.35, 0.35, 0.4);

// 4つのサウンドを収めた1つのファイルを読み込みます
const asset = new Asset('sfx', 'audio', {
url: 'https://developer.playcanvas.com/assets/sfx.mp3'
});
await new Promise((resolve) => {
asset.ready(resolve);
app.assets.add(asset);
app.assets.load(asset);
});

const camera = new Entity('camera');
camera.addComponent('camera', {
clearColor: new Color(0.11, 0.12, 0.17)
});
camera.setPosition(0, 0.5, 7);
app.root.addChild(camera);

const light = new Entity('light');
light.addComponent('light');
light.setEulerAngles(48, 38, 0);
app.root.addChild(light);

// 各サウンドがファイル内のどこにあるか(秒単位)と、そのボックスの色です
const sprites = {
coin: { start: 0, duration: 0.7, color: new Color(0.95, 0.75, 0.2) },
jump: { start: 1, duration: 0.8, color: new Color(0.3, 0.75, 0.45) },
laser: { start: 2, duration: 0.7, color: new Color(0.9, 0.3, 0.35) },
explosion: { start: 3, duration: 1.3, color: new Color(0.45, 0.5, 0.9) }
};
const names = Object.keys(sprites);

// サウンドごとのスロットを持つ、1つのSoundコンポーネントです
const source = new Entity('source');
source.addComponent('sound', { positional: false });
for (const name of names) {
source.sound.addSlot(name, {
asset: asset.id,
startTime: sprites[name].start,
duration: sprites[name].duration
});
}
app.root.addChild(source);

// スロットごとのボックスです
const boxes = {};
const hop = {};
names.forEach((name, i) => {
const material = new StandardMaterial();
material.diffuse = sprites[name].color;
material.update();

const box = new Entity(name);
box.addComponent('render', { type: 'box', material });
box.setPosition((i - 1.5) * 1.8, 0, 0);
app.root.addChild(box);
boxes[name] = box;
hop[name] = 0;
});

// コンポーネントは、いずれかのスロットが再生されるたびに、そのスロットを渡して'play'を発火します
source.sound.on('play', (slot) => {
hop[slot.name] = 1;
});

const status = document.createElement('div');
status.style.cssText = 'position: absolute; left: 12px; bottom: 10px; color: #ccc; font: 14px sans-serif;';
document.body.appendChild(status);

app.on('update', (dt) => {
let playing = 0;
for (const name of names) {
hop[name] = Math.max(0, hop[name] - dt * 3);
boxes[name].setPosition(boxes[name].getPosition().x, hop[name] * 0.6, 0);
playing += source.sound.slot(name).instances.length;
}
status.textContent = `Sounds playing: ${playing}`;
});

// ボタンとオプションです
const panel = document.createElement('div');
panel.style.cssText = 'position: absolute; left: 12px; top: 12px; display: flex; flex-wrap: wrap; gap: 8px; align-items: center; color: #ccc; font: 14px sans-serif;';
document.body.appendChild(panel);

let varyPitch = false;
for (const name of names) {
const button = document.createElement('button');
button.textContent = name;
button.onclick = () => {
const slot = source.sound.slot(name);
slot.pitch = varyPitch ? 0.8 + Math.random() * 0.4 : 1;
slot.play();
};
panel.appendChild(button);
}

const addCheckbox = (text, onChange) => {
const label = document.createElement('label');
const input = document.createElement('input');
input.type = 'checkbox';
input.onchange = () => onChange(input.checked);
label.append(input, ` ${text}`);
panel.appendChild(label);
};
addCheckbox('Overlap', (checked) => {
for (const name of names) {
source.sound.slot(name).overlap = checked;
}
});
addCheckbox('Vary pitch', (checked) => {
varyPitch = checked;
});

次のことを試してみてください。

  • explosionをすばやく数回クリックします。クリックのたびに、サウンドが最初から再生し直されます。Overlapをオンにしてもう一度試すと、爆発音が重なっていき、再生中のサウンドの数が増えます。
  • Vary pitchをオンにしてcoinを繰り返しクリックすると、ピッチを少しランダムに変えるだけで、繰り返し鳴るサウンドが耳障りでなくなることがわかります。
  • jumpのdurationを2に変更します。スロットは、自身のサウンドの終わりを越えて、ファイル内でその次にあるレーザーの音まで再生するようになります。

関連情報​