跳至主要内容
版本：v3

MediaFrames

重要 注意 提醒

Coding Style wiki​

MediaFrames 是 MediaFrame 模組的統一呼叫入口（Facade），以巢狀靜態類提供 AudioFrame（音訊）與 VideoFrame（影片）兩組介面，涵蓋媒體資源的預載、播放、暫停、恢復、停止與卸載，底層皆具備引用計數管理。

命名空間OxGFrame.MediaFrame
類型public static class
原始碼MediaFrames.cs
using OxGFrame.MediaFrame;

注意 呼叫前需確保場景中已建置對應的 AudioManager / VideoManager 物件，相關設定請參考 MediaFrame 介紹。

快速上手​

// 預載 BGM
await MediaFrames.AudioFrame.Preload("TitleBgm");

// 播放 BGM（-1 = 無限循環）
var bgm = await MediaFrames.AudioFrame.Play("TitleBgm", null, -1);

// 播放音效（使用 res# 前綴，改由 Resources 載入）
await MediaFrames.AudioFrame.Play("res#Audio/Sound/ClickSfx");

// 播放過場影片
var video = await MediaFrames.VideoFrame.Play("OpeningCutscene");

// 停止 BGM
MediaFrames.AudioFrame.Stop("TitleBgm");

// 影片確定不再使用時，強制卸載釋放記憶體
MediaFrames.VideoFrame.ForceUnload("OpeningCutscene");

通用規則​

資源名稱前綴​

assetName 支援前綴解析，依前綴決定資源載入來源：

前綴說明範例
res#從 Unity 原生 Resources 載入資源（依 Resources 相對路徑）。res#Audio/Sound/ClickSfx
無前綴預設從 Asset Bundle (YooAsset) 載入資源（直接使用可尋址名稱 Address）。TitleBgm

資源包 (Package)​

Preload 與 Play 皆提供 packageName 多載：

  • 未指定 packageName：自動使用預設 Package（AssetPatcher.GetDefaultPackageName()）。
  • 指定 packageName：從指定的 Package 載入資源，適用於多 Package 分包管理。

引用計數與生命週期​

注意 MediaFrames 底層皆具備引用計數管理。媒體實例銷毀時，若該資源已無其他同名實例存在（引用歸零），且啟用 onDestroyAndUnload 設定，將自動連動 AssetLoader 卸載資源。

提醒 媒體實例的銷毀時機，可由 Prefab 上 AudioBase / VideoBase 元件的 onStopAndDestroy（停止時銷毀）與 onDestroyAndUnload（銷毀時卸載）設定控制，也可於呼叫 Stop 時傳入 forceDestroy 強制銷毀。

MediaFrames.AudioFrame​

音訊的統一操作介面。專門負責管理遊戲中的所有音訊（如 BGM、環境音、語音、音效），支援依 SoundType 分類管理，並與 Unity 的 AudioMixer 深度整合。

方法總覽​

初始化與元件存取​

方法說明
InitInstance初始化 AudioManager 單例實例。
GetComponent<T>取得指定名稱的音訊實例元件（首個匹配）。
GetComponents<T>取得指定名稱的所有音訊實例元件。

Mixer 控制​

方法說明
GetMixerByName依名稱取得已註冊於 AudioManager 的 AudioMixer。
SetMixerExposedParam設定 Mixer 的 Exposed Parameter 數值（自動記錄）。
ClearMixerExposedParam清除 Mixer 的 Exposed Parameter 設定（恢復預設值）。
AutoClearMixerExposedParams批次清除已記錄的 Exposed Parameters。
AutoRestoreMixerExposedParams批次還原已記錄的 Exposed Parameters。
GetMixerSnapshot取得 Mixer 中指定名稱的 Snapshot。
SetMixerSnapshot立即切換至指定的 Snapshot。
SetMixerTransitionToSnapshot在指定時間內加權混合過渡至多個 Snapshots。

播放與資源管理​

方法說明
Preload預載音訊資源至快取。
Play播放音訊，回傳 AudioBase 實例。
Pause暫停指定名稱的音訊。
PauseAll暫停所有音訊。
ResumeAll恢復所有處於暫停狀態的音訊。
Stop停止指定名稱的音訊。
StopAll停止所有音訊。
ForceUnload強制卸載指定名稱的音訊資源。

InitInstance​

public static void InitInstance()

說明

主動初始化 AudioManager 單例實例。建議於遊戲啟動階段呼叫一次，確保管理器提前就緒。

注意 若場景中不存在 AudioManager 物件，將輸出錯誤日誌。

GetComponent<T>​

public static T GetComponent<T>(string assetName) where T : AudioBase

參數

參數型別說明
assetNamestring音訊資源名稱。

回傳值

T — 首個名稱匹配的音訊實例元件；查無時回傳 null。

說明

取得指定名稱的音訊實例上的 AudioBase 元件。僅能取得已進入播放管理列表的實例（即呼叫過 Play 之後），僅預載的資源尚未實例化，無法取得。

範例

var audBase = MediaFrames.AudioFrame.GetComponent<AudioBase>("TitleBgm");
if (audBase != null && audBase.IsPlaying())
{
    // 對實例進行進階操作
}

GetComponents<T>​

public static T[] GetComponents<T>(string assetName) where T : AudioBase

參數

參數型別說明
assetNamestring音訊資源名稱。

回傳值

T[] — 所有名稱匹配的音訊實例元件陣列；查無時回傳空陣列。

說明

取得指定名稱的所有音訊實例元件。當同名音訊同時存在複數實例時（如多重播放的音效），可透過此方法批次取得。

GetMixerByName​

public static AudioMixer GetMixerByName(string mixerName)

參數

參數型別說明
mixerNamestringMixer 名稱。

回傳值

AudioMixer — 名稱匹配的 Mixer；未註冊或查無時回傳 null。

說明

依名稱取得 AudioMixer。

重要 必須先將 AudioMixer 掛載至場景中 AudioManager 的 Audio Mixer 清單（Inspector），才能透過此方法取得。

範例

var mixer = MediaFrames.AudioFrame.GetMixerByName("MasterMixer");

SetMixerExposedParam​

public static void SetMixerExposedParam(AudioMixer mixer, string expParam, float val)

參數

參數型別說明
mixerAudioMixer目標 Mixer。
expParamstringExposed Parameter 名稱。
valfloat設定數值。

說明

設定 Mixer 的 Exposed Parameter 數值（如分組音量控制）。設定成功時會自動記錄該參數值，供 AutoRestoreMixerExposedParams 還原使用。

範例

var mixer = MediaFrames.AudioFrame.GetMixerByName("MasterMixer");
// 將 BGM 分組音量調降至 -20 dB
MediaFrames.AudioFrame.SetMixerExposedParam(mixer, "BgmVol", -20f);

ClearMixerExposedParam​

public static void ClearMixerExposedParam(AudioMixer mixer, string expParam)

參數

參數型別說明
mixerAudioMixer目標 Mixer。
expParamstringExposed Parameter 名稱。

說明

清除指定 Exposed Parameter 的自定義設定，恢復為 Mixer 的預設值。

AutoClearMixerExposedParams​

public static void AutoClearMixerExposedParams(AudioMixer mixer)

參數

參數型別說明
mixerAudioMixer目標 Mixer。

說明

將該 Mixer 先前透過 SetMixerExposedParam 記錄過的參數批次清除（恢復 Mixer 預設值；其他 Mixer 的記錄不受影響），記錄值仍會保留，可再透過 AutoRestoreMixerExposedParams 還原。

AutoRestoreMixerExposedParams​

public static void AutoRestoreMixerExposedParams(AudioMixer mixer)

參數

參數型別說明
mixerAudioMixer目標 Mixer。

說明

將該 Mixer 先前記錄過的參數值批次還原。常用於清除後的參數復原。

GetMixerSnapshot​

public static AudioMixerSnapshot GetMixerSnapshot(AudioMixer mixer, string snapshotName)

參數

參數型別說明
mixerAudioMixer目標 Mixer。
snapshotNamestringSnapshot 名稱。

回傳值

AudioMixerSnapshot — 名稱匹配的 Snapshot；查無時回傳 null。

說明

取得 Mixer 中指定名稱的 Snapshot。

SetMixerSnapshot​

public static void SetMixerSnapshot(AudioMixer mixer, string snapshotName)

參數

參數型別說明
mixerAudioMixer目標 Mixer。
snapshotNamestringSnapshot 名稱。

說明

立即切換至指定的 Snapshot（內部以 0.02 秒極短時間過渡）。查無 Snapshot 時不動作。

範例

var mixer = MediaFrames.AudioFrame.GetMixerByName("MasterMixer");
// 進入洞窟場景，切換至洞窟音場
MediaFrames.AudioFrame.SetMixerSnapshot(mixer, "Cave");

SetMixerTransitionToSnapshot​

public static void SetMixerTransitionToSnapshot(AudioMixer mixer, AudioMixerSnapshot[] snapshots, float[] weights, float timeToReach = 0.02f)

參數

參數型別說明
mixerAudioMixer目標 Mixer。
snapshotsAudioMixerSnapshot[]參與混合的 Snapshots。
weightsfloat[]各 Snapshot 的混合權重（與 snapshots 一一對應）。
timeToReachfloat過渡時間（秒）。
預設值：0.02f

說明

在指定時間內，依權重平滑過渡至多個 Snapshots 的混合狀態，適用於漸進式的環境音場變化。

範例

var mixer = MediaFrames.AudioFrame.GetMixerByName("MasterMixer");
var normal = MediaFrames.AudioFrame.GetMixerSnapshot(mixer, "Normal");
var cave = MediaFrames.AudioFrame.GetMixerSnapshot(mixer, "Cave");

// 2 秒內過渡至 30% Normal + 70% Cave 的混合音場
MediaFrames.AudioFrame.SetMixerTransitionToSnapshot(
    mixer,
    new AudioMixerSnapshot[] { normal, cave },
    new float[] { 0.3f, 0.7f },
    2f
);

Preload​

public static async UniTask Preload(string assetName)
public static async UniTask Preload(string[] assetNames)
public static async UniTask Preload(string packageName, string assetName)
public static async UniTask Preload(string packageName, string[] assetNames)

參數

參數型別說明
packageNamestring資源包名稱。未指定時，使用預設 Package。
assetNamestring音訊資源名稱（Bundle 資源使用 Address 名稱；支援 res# 前綴）。
assetNamesstring[]音訊資源名稱陣列（批次預載）。

回傳值

UniTask — 可等待的非同步操作。

說明

預先將音訊資源載入至快取。之後呼叫 Play 時可直接從快取取用，避免播放當下產生載入延遲。

範例

// 單一預載
await MediaFrames.AudioFrame.Preload("TitleBgm");

// 批次預載
await MediaFrames.AudioFrame.Preload(new string[]
{
    "TitleBgm",
    "res#Audio/Sound/ClickSfx"
});

Play​

public static async UniTask<AudioBase> Play(string assetName, Transform parent = null, int loops = 0, float volume = 0f)
public static async UniTask<AudioBase> Play(string packageName, string assetName, Transform parent = null, int loops = 0, float volume = 0f)
public static async UniTask<AudioBase> Play(string assetName, AudioClip sourceClip, Transform parent = null, int loops = 0, float volume = 0f)
public static async UniTask<AudioBase> Play(string packageName, string assetName, AudioClip sourceClip, Transform parent = null, int loops = 0, float volume = 0f)

參數

參數型別說明
packageNamestring資源包名稱。未指定時，使用預設 Package。
assetNamestring音訊資源名稱（Bundle 資源使用 Address 名稱；支援 res# 前綴）。
sourceClipAudioClip音訊剪輯來源。指定時，將直接覆寫實例上的 audioClip（適用於動態指定音訊內容）。
parentTransform掛載的父節點（用於 3D 音訊定位）。
預設值：null（依 SoundType 自動掛載至 AudioManager 下的對應節點）
loopsint循環次數。-1 = 無限循環；> 0 = 指定循環次數。
預設值：0（使用 Prefab 上 AudioBase 的循環設定）
volumefloat音量。> 0 時覆寫音量。
預設值：0f（使用 AudioSource 上的預設音量）

回傳值

UniTask<AudioBase> — 播放中的音訊實例元件；載入失敗時回傳 null。

說明

載入並播放指定的音訊。

注意
  • 若同名音訊已在播放中，且其 SoundType 為 Sole（如 BGM），不會重複播放，將直接回傳既有實例。
  • 若同名音訊處於暫停狀態，呼叫後會恢復播放。

範例

// 播放 BGM（無限循環）
var bgm = await MediaFrames.AudioFrame.Play("TitleBgm", null, -1);

// 從 Resources 播放音效
await MediaFrames.AudioFrame.Play("res#Audio/Sound/ClickSfx");

// 指定 Package 並以 0.8 音量播放
await MediaFrames.AudioFrame.Play("OtherPackage", "Npc01Voice", volume: 0.8f);

// 動態指定 AudioClip 播放
await MediaFrames.AudioFrame.Play("SfxTemplate", downloadedClip);

Pause​

public static void Pause(string assetName)

參數

參數型別說明
assetNamestring音訊資源名稱。

說明

暫停指定名稱的所有音訊實例。可透過 Play 或 ResumeAll 恢復播放。

PauseAll​

public static void PauseAll()

說明

暫停所有播放中的音訊。

ResumeAll​

public static void ResumeAll()

說明

恢復所有處於暫停狀態的音訊，對播放中的音訊不產生影響。

Stop​

public static void Stop(string assetName, bool disableEndEvent = false, bool forceDestroy = false)

參數

參數型別說明
assetNamestring音訊資源名稱。
disableEndEventbool是否禁用結束事件回呼（EndEvent），停止時將不觸發播放結束的後續處理。
預設值：false
forceDestroybool是否強制銷毀實例物件。未強制時，依 Prefab 上 onStopAndDestroy 設定決定。
預設值：false

說明

停止指定名稱的所有音訊實例。實例銷毀時將連動引用計數，決定是否自動卸載資源（參考引用計數與生命週期）。

範例

// 一般停止（依 Prefab 設定決定是否銷毀）
MediaFrames.AudioFrame.Stop("TitleBgm");

// 停止 + 不觸發結束事件 + 強制銷毀
MediaFrames.AudioFrame.Stop("TitleBgm", true, true);

StopAll​

public static void StopAll(bool disableEndEvent = false, bool forceDestroy = false)

參數

參數型別說明
disableEndEventbool是否禁用結束事件回呼。
預設值：false
forceDestroybool是否強制銷毀實例物件。
預設值：false

說明

停止所有音訊實例，參數行為同 Stop。

ForceUnload​

public static void ForceUnload(string assetName)

參數

參數型別說明
assetNamestring音訊資源名稱。

說明

略過引用計數，強制停止銷毀播放中的實例，並直接卸載源頭資源。

重要 此操作會強制釋放資源，呼叫前請確認該資源已無使用需求。

MediaFrames.VideoFrame​

影片的統一操作介面。用於控制影片的載入與播放（支援 RenderTexture 與 Camera 渲染方式），適用於過場動畫、開頭 CG 或 UI 動態背景等應用。

方法總覽​

初始化與元件存取​

方法說明
InitInstance初始化 VideoManager 單例實例。
GetComponent<T>取得指定名稱的影片實例元件（首個匹配）。
GetComponents<T>取得指定名稱的所有影片實例元件。

播放與資源管理​

方法說明
Preload預載影片資源至快取。
Play播放影片，回傳 VideoBase 實例。
Pause暫停指定名稱的影片。
PauseAll暫停所有影片。
ResumeAll恢復所有處於暫停狀態的影片。
Stop停止指定名稱的影片。
StopAll停止所有影片。
ForceUnload強制卸載指定名稱的影片資源。

InitInstance​

public static void InitInstance()

說明

主動初始化 VideoManager 單例實例。建議於遊戲啟動階段呼叫一次，確保管理器提前就緒。

注意 若場景中不存在 VideoManager 物件，將輸出錯誤日誌。

GetComponent<T>​

public static T GetComponent<T>(string assetName) where T : VideoBase

參數

參數型別說明
assetNamestring影片資源名稱。

回傳值

T — 首個名稱匹配的影片實例元件；查無時回傳 null。

說明

取得指定名稱的影片實例上的 VideoBase 元件。僅能取得已進入播放管理列表的實例（即呼叫過 Play 之後），僅預載的資源尚未實例化，無法取得。

GetComponents<T>​

public static T[] GetComponents<T>(string assetName) where T : VideoBase

參數

參數型別說明
assetNamestring影片資源名稱。

回傳值

T[] — 所有名稱匹配的影片實例元件陣列；查無時回傳空陣列。

說明

取得指定名稱的所有影片實例元件。

Preload​

public static async UniTask Preload(string assetName)
public static async UniTask Preload(string[] assetNames)
public static async UniTask Preload(string packageName, string assetName)
public static async UniTask Preload(string packageName, string[] assetNames)

參數

參數型別說明
packageNamestring資源包名稱。未指定時，使用預設 Package。
assetNamestring影片資源名稱（Bundle 資源使用 Address 名稱；支援 res# 前綴）。
assetNamesstring[]影片資源名稱陣列（批次預載）。

回傳值

UniTask — 可等待的非同步操作。

說明

預先將影片資源載入至快取。之後呼叫 Play 時可直接從快取取用，避免播放當下產生載入延遲。

範例

await MediaFrames.VideoFrame.Preload("OpeningCutscene");

Play​

public static async UniTask<VideoBase> Play(string assetName, Transform parent = null, int loops = 0, float volume = 0f)
public static async UniTask<VideoBase> Play(string packageName, string assetName, Transform parent = null, int loops = 0, float volume = 0f)
public static async UniTask<VideoBase> Play(string assetName, VideoClip sourceClip, Transform parent = null, int loops = 0, float volume = 0f)
public static async UniTask<VideoBase> Play(string packageName, string assetName, VideoClip sourceClip, Transform parent = null, int loops = 0, float volume = 0f)

參數

參數型別說明
packageNamestring資源包名稱。未指定時，使用預設 Package。
assetNamestring影片資源名稱（Bundle 資源使用 Address 名稱；支援 res# 前綴）。
sourceClipVideoClip影片剪輯來源。指定時，將直接覆寫實例上的 videoClip（適用於動態指定影片內容）。
parentTransform掛載的父節點。
預設值：null（掛載至 VideoManager 節點下）
loopsint循環次數。-1 = 無限循環；> 0 = 指定循環次數。
預設值：0（使用 Prefab 上 VideoBase 的循環設定）
volumefloat音量。> 0 時覆寫音量。
預設值：0f（使用 VideoPlayer 上的預設音量）

回傳值

UniTask<VideoBase> — 播放中的影片實例元件；載入失敗時回傳 null。

說明

載入並播放指定的影片。

注意
  • 若同名影片已在播放中，不會重複播放，將直接回傳既有實例。
  • 若同名影片處於暫停狀態，呼叫後會恢復播放。

範例

// 播放過場影片
var video = await MediaFrames.VideoFrame.Play("OpeningCutscene");

// 動態指定 VideoClip 播放
await MediaFrames.VideoFrame.Play("VideoTemplate", downloadedClip);

Pause​

public static void Pause(string assetName)

參數

參數型別說明
assetNamestring影片資源名稱。

說明

暫停指定名稱的所有影片實例。可透過 Play 或 ResumeAll 恢復播放。

PauseAll​

public static void PauseAll()

說明

暫停所有播放中的影片。

ResumeAll​

public static void ResumeAll()

說明

恢復所有處於暫停狀態的影片，對播放中的影片不產生影響。

Stop​

public static void Stop(string assetName, bool disableEndEvent = false, bool forceDestroy = false)

參數

參數型別說明
assetNamestring影片資源名稱。
disableEndEventbool是否禁用結束事件回呼（EndEvent），停止時將不觸發播放結束的後續處理。
預設值：false
forceDestroybool是否強制銷毀實例物件。未強制時，依 Prefab 上 onStopAndDestroy 設定決定。
預設值：false

說明

停止指定名稱的所有影片實例。實例銷毀時將連動引用計數，決定是否自動卸載資源（參考引用計數與生命週期）。

StopAll​

public static void StopAll(bool disableEndEvent = false, bool forceDestroy = false)

參數

參數型別說明
disableEndEventbool是否禁用結束事件回呼。
預設值：false
forceDestroybool是否強制銷毀實例物件。
預設值：false

說明

停止所有影片實例，參數行為同 Stop。

ForceUnload​

public static void ForceUnload(string assetName)

參數

參數型別說明
assetNamestring影片資源名稱。

說明

略過引用計數，強制停止銷毀播放中的實例，並直接卸載源頭資源。

重要 影片檔案通常較大，當確定不再需要該影片時，應手動呼叫此方法強制釋放記憶體。

範例

// 過場影片播放完畢，確定不再使用
MediaFrames.VideoFrame.ForceUnload("OpeningCutscene");