audio-video

Decentraland のオーディオとビデオ

メディアコンポーネントの使い分け

必要な用途	コンポーネント	主な違い
ファイルから効果音を再生する（クリック音、爆発音、足音）	AudioSource	ローカルファイル、空間オーディオ、単発またはループ再生
BGM またはラジオストリームを再生する	AudioStream	外部 URL、非空間オーディオ、連続再生
表面にビデオを表示する（スクリーン、看板）	VideoPlayer + Material.Texture.Video	表示するメッシュが必要

選択フロー：

1. ローカルのオーディオファイルですか？ → AudioSource
2. ストリーミング URL（ラジオ、ライブオーディオ）ですか？ → AudioStream
3. ビデオコンテンツですか？ → 平面またはメッシュ上の VideoPlayer

オーディオの調達

コード内でオーディオファイルのパスを参照する前に、{baseDir}/references/audio-catalog.md を確認してください。ここには、ほとんどの用途（UI のクリック音、環境音楽、ゲームの仕組み、効果音）をカバーする、Decentraland の無料オーディオクリップ 50 個と、直接ダウンロードできる URL が掲載されています。

ユーザーから音声を求められたときの基本的なワークフローは次のとおりです。

1. このスキルと references/audio-catalog.md を読みます。
2. カタログに用途に合うクリップがある場合は、クリップ名と用途を添えてユーザーに候補として提示します。
3. どのように進めるかをユーザーに確認します。 カタログのクリップをダウンロードしたいクリエイターもいれば、後から自分のファイルを追加できるようにプレースホルダーパスを使いたいクリエイターもいます。決めつけないでください。
4. カタログのクリップを選んだ場合は、curl -o assets/Audio/<name>.mp3 "<URL>" でダウンロードします。これらの URL は Bash から直接使えるため、別のツールは不要です。
5. プレースホルダーを希望する場合は、わかりやすいプレースホルダーパス（例：assets/Audio/<name>.mp3）を使用し、どのファイルをどこに追加すればよいかユーザーに伝えます。
6. AudioSource.audioClipUrl で、生成したローカルパスを参照します。

避けるべきこと：

• 「オーディオファイルをダウンロードできません」とユーザーに伝えること。カタログの URL には Bash と curl で問題なくアクセスできます。ユーザーが希望するなら、その機能を利用できます。
• カタログに用途に合うクリップがあるかを確認せずに、外部ソース（freesound / mixkit / pixabay）を勧めること。
• ユーザーに確認せずにクリップをダウンロードすること。カタログにぴったりのものがあっても、プロジェクトにファイルを取り込む前に必ず確認してください。

AudioSource（効果音と音楽）

位置に応じたサウンドを再生するには、任意のエンティティにアタッチします。フィールド：audioClipUrl: string（ローカルファイルパス、必須）、playing?: boolean、loop?: boolean、volume?: number（デフォルトは 1.0）、pitch?: number（再生速度、デフォルトは 1.0）、currentTime?: number（秒単位の再生位置、デフォルトは 0）、global?: boolean。オーディオファイルは assets/Audio/ に配置します。対応形式：.mp3（音楽に推奨）、.ogg（効果音に推奨。ファイルサイズが小さい）、.wav。大きなファイルはシーンの読み込み時間を増やすため、オーディオファイルのサイズは小さく抑えてください。16-bit の .wav は、同じクリップの MP3/OGG と比べて数倍のサイズになります。配置する前に変換してください（ffmpeg -i in.wav -b:a 128k out.mp3）。

オーディオはデフォルトで空間オーディオです。エンティティから離れるほど音量が下がります。空間オーディオを無効にし、どこでも同じ音量にするには global: true を設定します。

global: true のものも含め、AudioSource を持つすべてのエンティティには Transform が必要です。 Unity Explorer が Unity のオーディオソースを作成するのは、TransformComponent を持つエンティティだけです（UpdateAudioSourceSystem.CreateAudioSource クエリ、unity-explorer main 2026-10）。これがない場合、SDK、ビルド、ヘッドレスエンジンではコンポーネントが受け入れられますが、再生は一切行われず、エラーも記録されません。global が変更するのは空間化の設定であり、この前提条件ではありません。AudioSource.create の前に Transform.create(entity)（位置は任意）を作成してください。同じプロジェクトで、風の静かな環境音と、その後に追加した静かな音声キューの両方で、この問題が発生していました（2026-10）。検証ルールとして create-scene/references/entity-validation-rules.md に記載されています。 空間減衰の範囲は非常に広く、global: false は「この部屋だけ」という意味ではありません。 PBAudioSource には距離フィールドがまったくありません。Explorer はプールされた Unity の AudioSource に spatialize／spatialBlend／dopplerLevel だけを設定し、距離カーブは Unity のデフォルト（対数、minDistance 1 m、maxDistance 500 m）のままです。これは unity-explorer の AudioSourceExtensions.FromPBAudioSourceWithClip と AudioSourcesPlugin、および audio_source.gen.d.ts（7.30.1）で確認されています。そのため、音量の小さい部屋の環境音が互いにすべての部屋へ漏れ、「どこでも音が鳴る」と感じられます（オーナーから報告された症状、2026-10-10）。

1 つの部屋の中だけで再生させたい環境音は、プレイヤーとの距離に基づいてシステム内で自分で制御してください。一定の半径を超えたら playing: false と volume: 0 を設定し、その内側では音量を徐々に上げます。適切な半径は部屋の大きさ、クリップ、volume によって異なるため、ワールド内で調整してください。システムの実行頻度を抑え、変更があった場合のみ書き込みます。修正はコード上でのみ確認済みで、ワールド内では再聴取していません。

再トリガー（クリックのたびに音をもう一度鳴らす）： ヘルパー AudioSource.playSound(entity, clipUrl, resetCursor?) を使用してください。getMutable().playing を直接変更してはいけません。playSound はコンポーネント全体を書き込むため（createOrReplace／getMutableOrNull 経由）、パラメーターが同じでも確実に再送信されます。getMutable(entity).playing = true を直接設定する方法（または以前の「playing=false の後に playing=true にする」方法）は、値が変わらない場合に LWW-CRDT の重複排除によって通知されずに破棄されることがあり、2 回目以降のトリガーが何も起こさない場合があります。stopSound(entity, resetCursor?) で停止できます。どちらも resetCursor のデフォルトは true（開始／停止時に 0 に設定）です。false を渡すと、現在の currentTime から再開／一時停止します。

AudioSource.playSound(entity, 'assets/Audio/click.mp3') // retriggers from 0 every call
AudioSource.stopSound(entity)                            // stops, resets cursor to 0

どちらのヘルパーも、エンティティに AudioSource がない場合は false を返すため、先にコンポーネントを作成してください（例：初期化時に AudioSource.create(entity, { audioClipUrl, playing: false })）。

1 つの AudioSource で同時に再生できるクリップは 1 つです。 すでに再生中のエンティティに対して playSound を呼び出すと、そのクリップは置き換えられます（再トリガーテストシーンの URL 切り替えケース）。そのため、重なって再生される可能性のある合図（クリック音、判定音、死亡音など）にはそれぞれ別のエンティティが必要です。また、連続して複数のタイルをクリックする場合のように、同じ位置で音が重なる可能性がある場合は、少数のエンティティを用意して順番に使うプールが必要です。各クリップの長さと再生するタイミングも確認してください（ffprobe -v quiet -show_entries format=duration -of csv=p=0 file.mp3）。2 秒のゲームプレイ演出に 10 秒の効果音を重ねると、次の合図で途中停止するか、演出後まで鳴り続けてしまいます（オーナーから報告、2026-10）。

フェードやクロスフェードの API はありません。 PBAudioSource の音量レベルに関するフィールドは volume だけなので、音量を下げるには、毎フレーム AudioSource.getMutable(entity).volume を目標値に向けて徐々に変化させるシステムを使います（値が変化している間のみ書き込みます）。音楽を小さくして途中から元に戻すには、playing: true のまま音量を 0 にします。または stopSound(entity, false) で一時停止し、playSound(entity, url, false) で再開します。デフォルトの resetCursor のままでは、曲が最初から再生されるためです。

音の再生終了を検出する： ループしないクリップが自然に終了すると、エンジンは AudioSource.playing を false に戻します。読み取り専用ゲッターでポーリングし、true → false の遷移をエッジ検出してください。getMutable でポーリングしてはいけません（毎フレーム、コンポーネントが変更済みになります）。

let wasPlaying = false
engine.addSystem(() => {
	const isPlaying = AudioSource.get(entity).playing ?? false
	if (wasPlaying && !isPlaying) console.log('sound finished') // chain next sound/action here
	wasPlaying = isPlaying
})

エンジンがフラグを切り替えるのは、自然に再生が完了した場合だけです。シーンから開始する stopSound() は独自に書き込むものであり、ループ再生するクリップではフラグは切り替わりません。代わりに audioEventsSystem を使うと、MediaState が変化するたびにコールバックを受け取れます（MS_PLAYING → MS_READY = 停止、MS_ERROR = ファイルの読み込み失敗）。詳しくは、以下の「Audio Events System」セクションを参照してください。どちらも保証ではなく通知として扱ってください。タイムアウト時のフォールバックなしに、これらに依存して処理を完全にブロックしないでください。モバイルでは、音量カーブと空間減衰をUnityに合わせるオーディオのパリティ対応とともに、AudioEvent（PBAudioEvent）が**v1.14.0（2026年9月）**で提供されます（ドキュメントのコミット b4d4c88）。それまでは、モバイルのミックスはデスクトップと聴感上異なり、オーディオイベントも発生しません。これは、タイムアウト時のフォールバックがすでにカバーしている「再生完了シグナルなし」のケースと同じです。

オーディオを再生する前に、プレイヤーはシーンを操作（クリック）する必要があります（ブラウザーの自動再生ポリシー）。プレイヤーが操作した瞬間にすぐ再生できるよう、オーディオファイルを準備しておく必要がある場合は、AssetLoad コンポーネントを使ってアセットを事前に読み込んでください。

シーンの起動時に開始したサウンドは、Explorerのローディング画面の背後で再生されるため、プレイヤーには聞こえません。ウェルカムボイスオーバー、イントロのジングル、またはシーンを最初に見たときに流したい音楽は、EngineInfo.sceneHidden が false に切り替わる（ローディング画面のフェードアウト）まで待ってから playing: true を設定してください。詳しくはscene-runtimeスキルを参照してください。

シーンが非表示のときはオーディオを一時停止してください： 同じ EngineInfo.getOrNull(engine.RootEntity)?.sceneHidden フラグは、シーンが全画面表示のExplorer UI（マップ、バックパック、設定）で覆われているときも true になります。その状態ではオーディオソースを一時停止またはミュートし、sceneHidden が false に戻ったら再開してください。

オーディオを追加する前に：外部ソースからオーディオを取得する場合は、事前にユーザーに確認してください。

AudioStream（ストリーミング）

URLからオーディオをストリーミング再生します（ラジオ、ライブストリーム）。主なフィールドは url（ストリーミングURL）、playing、volume です。デフォルトでは空間化されず、どこでも同じ音量で再生されます。距離に応じて音量を変えるには、spatial: true と spatialMinDistance／spatialMaxDistance を設定してください。

AudioStream.getAudioState(entity) で状態を照会できます。返されるのは PBAudioEvent | undefined です。これは単なるenumではなく、state フィールド（MS_PLAYING、MS_ERROR などを含む MediaState enum）と timestamp フィールドを持つオブジェクトです。状態を読み取るには AudioStream.getAudioState(entity)?.state を使ってください。ポーリングではなく、コールバックで状態の変化を受け取る場合は、audioEventsSystem.registerAudioEventsEntity をAudioStreamエンティティでも使用できます（前述のAudioSourceの再生完了検出に関する注意を参照してください）。

ストリーミングURLを追加する前に：ユーザーから提示されていない場合は、まずソースを確認してください。

オーディオイベントシステム（audioEventsSystem）

AudioSource と AudioStream のメディア状態の変化を監視します。@dcl/sdk/ecs からインポートします。システムは状態が変化した場合にのみコールバックを実行します（毎フレームではありません）。

import { engine, audioEventsSystem, AudioSource } from '@dcl/sdk/ecs'

const radioEntity = engine.addEntity()
AudioSource.create(radioEntity, { audioClipUrl: 'assets/Audio/music.mp3', playing: true })

audioEventsSystem.registerAudioEventsEntity(radioEntity, (event) => {
  // event is PBAudioEvent: { state: MediaState, timestamp: number }
  console.log('Audio state changed:', event.state)
})

API（@dcl/ecs、コミット f858f905 に照らして検証済み）：

• audioEventsSystem.registerAudioEventsEntity(entity, callback) — オーディオ状態の変化を通知するコールバックを登録します。コールバックには、state（MediaState 列挙型）と timestamp を含む PBAudioEvent が渡されます。状態が変化した場合にのみ実行されます。
• audioEventsSystem.removeAudioEventsEntity(entity) — コールバックの登録を解除します。
• audioEventsSystem.hasAudioEventsEntity(entity) — boolean を返します。
• audioEventsSystem.getAudioState(entity) — PBAudioEvent | undefined（最新の状態）を返します。

MediaState の値： MS_LOADING、MS_READY、MS_PLAYING、MS_PAUSED、MS_STOPPED、MS_ERROR、MS_SEEKING、MS_BUFFERING、MS_NONE。

エンティティが削除された場合、または AudioSource／AudioStream コンポーネントを持たなくなった場合、登録は自動的に解除されます。AudioSource または AudioStream のいずれかを持つエンティティで動作します（レンダラーは、これらのコンポーネントを持つエンティティに基盤となる AudioEvent コンポーネントを追加します）。

AudioStream.getAudioState との関係： AudioStream.getAudioState は AudioStream コンポーネント自体の便利なラッパーです。一方、audioEventsSystem.getAudioState は基盤となる AudioEvent コンポーネントを読み取り、AudioSource と AudioStream の両方で機能します。コールバック駆動の状態監視が必要な場合や、AudioSource を使用する場合は audioEventsSystem を使ってください。

VideoPlayer

サーフェス上で動画を再生します。主なフィールド：src（URL またはローカルパス）、playing、loop、volume、playbackRate、position（再生開始時刻、秒単位）。デフォルトでは空間オーディオではありません。位置に応じたオーディオにするには、最小距離と最大距離を指定して spatial: true を設定します。

セットアップには 3 つの手順が必要です： MeshRenderer.setPlane() でエンティティを作成し、VideoPlayer を追加して、Material.Texture.Video({ videoPlayerEntity }) を作成し、マテリアルに適用します。画面を明るく表示するには、Material.setBasicMaterial（推奨。パフォーマンスが向上します）または発光を設定した Material.setPbrMaterial を使ってください。

videoEventsSystem で再生状態を監視します：

• videoEventsSystem.registerVideoEventsEntity(entity, callback) — 状態が変化するたびに、コールバックに PBVideoEvent が渡されます。
• videoEventsSystem.removeVideoEventsEntity(entity) — コールバックの登録を解除します。
• videoEventsSystem.hasVideoEventsEntity(entity): boolean — エンティティが登録済みかどうかを確認します。
• videoEventsSystem.getVideoState(entity): PBVideoEvent | undefined — コールバックを使わずに最新の状態をポーリングします。

状態：VS_READY、VS_PLAYING、VS_PAUSED、VS_ERROR、VS_BUFFERING。

再登録しても、最後に報告された状態は保持されます： 登録済みのエンティティに対して registerVideoEventsEntity を呼び出すと、コールバックは置き換えられますが、最後に報告された状態は保持されるため、新しいコールバックに報告済みの状態変化が再通知されることはありません。同じ動作は assetLoadLoadingStateSystem.registerAssetLoadLoadingStateEntity にも当てはまります。再登録時に報告済みイベントの数が保持され、コールバックの重複を防ぎます。js-sdk-toolchain のコミット 9055b4b4 に照らして検証済みです。

複数の Material.Texture.Video() 呼び出しで同じ videoPlayerEntity を参照すると、1 つの VideoPlayer を複数の画面で共有できます。

曲面スクリーンなど、プリミティブではない形状で動画を再生するには、GltfNodeModifiers を使って GLTF モデルのマテリアルを差し替えます。

無料のオーディオファイル

オーディオカタログを最初に確認してください。このスキルの冒頭にあるオーディオの調達セクションをご覧ください。音楽、環境音、インタラクション音、効果音、ゲームの仕組みに関するサウンドなど、無料で使えるDecentralandのクリップが50件掲載されており、それぞれにcurlですぐに使えるURLが記載されています。

オーディオをおすすめする前に{baseDir}/references/audio-catalog.mdを読み、具体的な候補を提示してから、ユーザーにこれらのクリップをダウンロードしたいか、プレースホルダーを使いたいかを確認してください。

重要：AudioSourceはローカルファイルでのみ動作します。audioClipUrlに外部URLを使用しないでください。必ず先にassets/Audio/へダウンロードしてください。

カタログにない環境音の録音

カタログには環境音の機械音（水滴、モーター、扇風機、冷蔵庫のうなり、エスカレーター音）はありません。ffmpegやPythonで代わりの音を合成しないでください。環境音を依頼したクリエイターは、音声トーンジェネレーターの音だとすぐに見抜いて却下します（2026-10-10に確認）。Wikimedia Commonsは実際の録音を入手するのに有用なソースです。

• 検索：https://commons.wikimedia.org/w/api.php?action=query&list=search&srnamespace=6&srsearch=<terms>+filetype:audio&format=jsonを使い、検索結果に対してaction=query&prop=imageinfo&iiprop=url|extmetadataを実行して、LicenseShortNameとArtistを確認します。
• CC0／パブリックドメインを優先してください。CC BYおよびCC BY-SAの場合、シーンを公開する場所にクレジット表記が必要です。ダウンロード時に、タイトル、作者、ライセンス、ソースURLをシーンのdesign/メモに記録してください。
• 説明的なUser-Agentを設定し、リクエストの間隔を空けてください。約8回連続でリクエストしたところ、APIからHTTP 429が返されました。
• LL-Q1860 …という名前のファイルはLingua Libreの単語の発音音声であり、効果音ではありません。使用しないでください。
• assets/Audio/に配置する前に、ffmpeg（afadeによるフェードイン／アウトとloudnorm）でループ用に編集してください。

アセットフォルダーの規則

• 自分でダウンロードするオーディオの標準の保存先はassets/Audio/です。
• 既存のシーンでは、オーディオがすでにassets/scene/Audio/にある場合があります。このパスも引き続き使用できます。そのようなシーンに新しいクリップを追加するときは、別途assets/Audio/フォルダーを作らず、既存のパスを再利用してください。
• Creator Hubのアセット：Creator HubのUIから直接インポートしたオーディオは、標準のパスと同じassets/Audio/に保存されます。無料のDCLアセットパックのアイテムはassets/asset-packs/に、カスタムアイテムはassets/custom/に保存されます。古いシーンでは、ユーザーがインポートしたものがassets/scene/直下にある場合もあります。これらのパスはそのまま参照してください。移動したり名前を変更したりしないでください。

新しいファイルの保存先を決める前に、必ずシーンの既存フォルダーを確認してください。

Creator Hubでシーンを開いているときの最速の方法

Local Assetsタブからメディアファイルをビューポートにドラッグすると、そのファイルを参照するカタログの対応するスマートアイテムが生成されます（creator-hub 062ed0a2）。.mp3／.ogg／.wavの場合は、AudioSource.audioClipUrlがそのファイルを参照するように変更されたAmbient Sound - Forest Birdsが生成されます。.mp4の場合は、VideoPlayer.srcとasset-packs::VideoScreen.defaultURLの両方がそのファイルを参照するように変更されたVideo Screenが生成されます。これはエンティティの作成とコンポーネントの追加を個別に行う代わりに、1回の操作で済みます。また、手動で配置したアイテムと同じ一式のコンポーネントと基本ビュー設定を持つエンティティが作成されます。ユーザーがキーボードを操作できる場合は、エンティティを手作業で構築するよりもこの方法を優先してください。アセットIDと同等のツール呼び出しについてはcreator-hub-mcpを参照してください。

⚠️ **Video Screenアイテムでは、VideoPlayer.srcだけでは不十分です。**管理者メッセージバスは実行時にasset-packs::VideoScreen.defaultURLからsrcを再設定するため、defaultURLを更新せずに設定したsrcは、テンプレートのストリームURLに気づかれないまま置き換えられます。

⚠️ Creator Hubのビューポートにミュート切り替え機能があるのは、Bevyレンダラー使用時のみです（ツールバーのスピーカーアイコン：シーンの音声をミュート／シーンの音声のミュートを解除）。これを使うと、すべてのAudioSource／AudioStreamの音量が0になり、状態は再読み込み後も維持されます。Babylonでは、エディターはシーンの音声を一切再生しません。そのため、エディターで無音でも原因を特定したことにはなりません。volumeやplayingを変更する前に、実際のプレビューで音声を確認してください。

オーディオに反応するシーン（ビジュアライザー、ビート同期）

任意の AudioSource、AudioStream、または VideoPlayer からリアルタイムの振幅データと周波数帯域データを取得するには、専用の audio-analysis スキルを使用してください。音楽ビジュアライザー、イコライザーバー、反応するライトやパーティクルに使用する AudioAnalysis コンポーネント（Unity-explorer のみ）について説明しています。

外部メディアの権限

[LEGACY] 外部のオーディオ／動画 URL に ALLOW_MEDIA_HOSTNAMES 権限は必要ありません。権限とその allowedMediaHostnames リストは @dcl/schemas に残っていますが、現在これを強制するクライアントはありません。unity-explorer のホスト名チェックは CHECK_ALLOWED_MEDIA_HOSTNAMES コンパイル定義の有効化が条件ですが（どのビルド設定でも設定されていないため、SceneData.TryGetMediaUrl は URL の構文チェックのみを行います）、bevy-explorer にも強制機能はありません。これを強制していたのは、すでに廃止された web クライアントだけです。新しいシーンには追加しないでください。現在のクライアントでは、外部メディアを権限なしで再生できます。

動画の制限とヒント

• 同時に再生する動画：複数の動画を同時に再生することは避けてください。明示的に要求された場合にのみ、同時に 1 本を超える動画を再生してください。上限は各プレーヤーの画質設定によって異なります（低画質では 1 本までの場合があります。{baseDir}/references/media-reference.md の Video Limits テーブルを参照）。そのため、安全に再生できる下限は 1 本と考えてください。
• HTTPS が必須：動画ソースには HTTPS URL が必要です。HTTP は使用できません。
• 距離に応じた制御：帯域幅を節約するため、プレイヤーが遠くにいる場合は動画を一時停止してください。
• 対応フォーマット：.mp4（H.264）、.webm、ライブストリーミング用 HLS（.m3u8）
• ライブストリーミング：クライアント間で最も安定して動作する HLS（.m3u8）URL を使用してください。

サンプルシーン

エンジンチームが実際のエクスプローラーでテストしたシーンです。

• audio-source-retrigger-test — AudioSource.playSound／stopSound、同じ URL での再トリガー、1 つのエンティティ上での URL 切り替え、resetCursor の動作、音量／ピッチ／ループの各種設定、および getMutable を直接変更するより playSound が優れている理由（LWW による重複排除）。
• audio-visualization — AudioAnalysis を使った音楽ビジュアライザー（audio-analysis スキルを参照）。
• audio-finish — playing の切り替わりと audioEventsSystem コールバックによる自然終了の検出、およびシーンからの停止と自然終了を区別する方法。
• asset-load — テクスチャ、動画、glb とあわせて mp3 を事前ロードする AssetLoad と、アセットごとの assetLoadLoadingStateSystem 状態コールバック（存在しないパスが NOT_FOUND として解決されるケースを含む）。プレイヤーが最初にクリックした瞬間に音声を再生できるように事前ロードするためのパターンです。
• gltfnodemodifier — プリミティブではなく GLB 上での VideoPlayer の使用例。HLS .m3u8 ストリームを GltfNodeModifiers の動画テクスチャで特定の GLTF ノードに適用します。前述の曲面スクリーン／非プリミティブの場合の実例です。

コードの完全な例と実装パターンについては、{baseDir}/references/media-patterns.md を参照してください。コンポーネントのフィールドの詳細については、{baseDir}/references/media-reference.md を参照してください。