跳到主要内容
版本：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");