Version: v3

MediaFrames

Important Attention Reminder

Coding Style wiki

MediaFrames is the unified entry point (Facade) of the MediaFrame module. It exposes two groups of APIs through nested static classes — AudioFrame (audio) and VideoFrame (video) — covering preloading, playing, pausing, resuming, stopping, and unloading of media assets, all backed by reference counting.


Namespace	`OxGFrame.MediaFrame`
Type	`public static class`
Source	MediaFrames.cs

using OxGFrame.MediaFrame;

Attention Before calling any API, make sure the corresponding AudioManager / VideoManager object has been set up in the scene. See the MediaFrame Introduction for setup details.

Quick Start

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

// Play the BGM (-1 = infinite loop)
var bgm = await MediaFrames.AudioFrame.Play("TitleBgm", null, -1);

// Play a sound effect (with the res# prefix, loaded from Resources instead)
await MediaFrames.AudioFrame.Play("res#Audio/Sound/ClickSfx");

// Play a cutscene video
var video = await MediaFrames.VideoFrame.Play("OpeningCutscene");

// Stop the BGM
MediaFrames.AudioFrame.Stop("TitleBgm");

// Force unload the video to release memory once it is no longer needed
MediaFrames.VideoFrame.ForceUnload("OpeningCutscene");

General Rules

Asset Name Prefix

assetName supports prefix resolution, which determines the loading source:

Prefix	Description	Example
res#	Loads the asset from Unity's native Resources (by relative path under Resources).	`res#Audio/Sound/ClickSfx`
None	Loads the asset from the Asset Bundle (YooAsset) by default (using its addressable name).	`TitleBgm`

Package

Both Preload and Play provide packageName overloads:

Without packageName: the default package is used automatically (AssetPatcher.GetDefaultPackageName()).
With packageName: the asset is loaded from the specified package, useful for multi-package management.

Reference Counting & Lifecycle

Attention MediaFrames is fully backed by reference counting. When a media instance is destroyed and no other instance of the same asset remains (the reference count reaches zero), the asset is automatically unloaded through AssetLoader if onDestroyAndUnload is enabled.

Reminder The destruction timing of media instances is controlled by the onStopAndDestroy (destroy on stop) and onDestroyAndUnload (unload on destroy) settings on the AudioBase / VideoBase component of the prefab. You can also pass forceDestroy to Stop to destroy an instance explicitly.

MediaFrames.AudioFrame

The unified audio API. It manages all audio in the game (such as BGM, ambience, voice, and sound effects), supports management grouped by SoundType, and is deeply integrated with Unity's AudioMixer.

Method Overview

Initialization & Component Access

Method	Description
InitInstance	Initializes the `AudioManager` singleton instance.
GetComponent<T>	Gets the audio instance component with the given name (first match).
GetComponents<T>	Gets all audio instance components with the given name.

Mixer Control

Method	Description
GetMixerByName	Gets an `AudioMixer` registered on the `AudioManager` by name.
SetMixerExposedParam	Sets an exposed parameter value on the mixer (auto-recorded).
ClearMixerExposedParam	Clears an exposed parameter override (restores the default value).
AutoClearMixerExposedParams	Clears all recorded exposed parameters in one call.
AutoRestoreMixerExposedParams	Restores all recorded exposed parameters in one call.
GetMixerSnapshot	Gets a snapshot of the mixer by name.
SetMixerSnapshot	Switches to the given snapshot immediately.
SetMixerTransitionToSnapshot	Transitions to a weighted blend of multiple snapshots over time.

Playback & Asset Management

Method	Description
Preload	Preloads audio assets into the cache.
Play	Plays an audio asset and returns its `AudioBase` instance.
Pause	Pauses the audio with the given name.
PauseAll	Pauses all audio.
ResumeAll	Resumes all paused audio.
Stop	Stops the audio with the given name.
StopAll	Stops all audio.
ForceUnload	Forcibly unloads the audio asset with the given name.

InitInstance

public static void InitInstance()

Description

Explicitly initializes the AudioManager singleton instance. It is recommended to call this once during game startup so the manager is ready ahead of time.

Attention If no AudioManager object exists in the scene, an error is logged.

GetComponent<T>

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

Parameters

Parameter	Type	Description
assetName	`string`	Audio asset name.

Returns

T — the first audio instance component matching the name; null if none is found.

Description

Gets the AudioBase component of the audio instance with the given name. Only instances that have entered the playback list (i.e., after calling Play) can be retrieved — assets that are merely preloaded are not instantiated yet.

Example

var audBase = MediaFrames.AudioFrame.GetComponent<AudioBase>("TitleBgm");
if (audBase != null && audBase.IsPlaying())
{
    // Perform advanced operations on the instance
}

GetComponents<T>

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

Parameters

Parameter	Type	Description
assetName	`string`	Audio asset name.

Returns

T[] — all audio instance components matching the name; an empty array if none is found.

Description

Gets all audio instance components with the given name. Useful when multiple instances of the same asset exist at once (e.g., a sound effect played several times).

GetMixerByName

public static AudioMixer GetMixerByName(string mixerName)

Parameters

Parameter	Type	Description
mixerName	`string`	Mixer name.

Returns

AudioMixer — the mixer matching the name; null if not registered or not found.

Description

Gets an AudioMixer by name.

Important The AudioMixer must first be added to the Audio Mixer list on the AudioManager in the scene (Inspector); otherwise it cannot be retrieved by this method.

Example

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

SetMixerExposedParam

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

Parameters

Parameter	Type	Description
mixer	`AudioMixer`	Target mixer.
expParam	`string`	Exposed parameter name.
val	`float`	Value to set.

Description

Sets an exposed parameter value on the mixer (e.g., group volume control). On success, the value is automatically recorded so it can later be restored via AutoRestoreMixerExposedParams.

Example

var mixer = MediaFrames.AudioFrame.GetMixerByName("MasterMixer");
// Lower the BGM group volume to -20 dB
MediaFrames.AudioFrame.SetMixerExposedParam(mixer, "BgmVol", -20f);

ClearMixerExposedParam

public static void ClearMixerExposedParam(AudioMixer mixer, string expParam)

Parameters

Parameter	Type	Description
mixer	`AudioMixer`	Target mixer.
expParam	`string`	Exposed parameter name.

Description

Clears the override of the given exposed parameter, restoring the mixer's default value.

AutoClearMixerExposedParams

public static void AutoClearMixerExposedParams(AudioMixer mixer)

Parameters

Parameter	Type	Description
mixer	`AudioMixer`	Target mixer.

Description

Clears in one call the parameters previously recorded for the given mixer via SetMixerExposedParam (restoring the mixer defaults; other mixers' records are unaffected). The recorded values are kept, so they can be re-applied via AutoRestoreMixerExposedParams.

AutoRestoreMixerExposedParams

public static void AutoRestoreMixerExposedParams(AudioMixer mixer)

Parameters

Parameter	Type	Description
mixer	`AudioMixer`	Target mixer.

Description

Re-applies in one call the parameter values previously recorded for the given mixer. Commonly used to restore parameters after they have been cleared.

GetMixerSnapshot

public static AudioMixerSnapshot GetMixerSnapshot(AudioMixer mixer, string snapshotName)

Parameters

Parameter	Type	Description
mixer	`AudioMixer`	Target mixer.
snapshotName	`string`	Snapshot name.

Returns

AudioMixerSnapshot — the snapshot matching the name; null if not found.

Description

Gets the snapshot with the given name from the mixer.

SetMixerSnapshot

public static void SetMixerSnapshot(AudioMixer mixer, string snapshotName)

Parameters

Parameter	Type	Description
mixer	`AudioMixer`	Target mixer.
snapshotName	`string`	Snapshot name.

Description

Switches to the given snapshot immediately (internally transitioned over a very short 0.02-second window). Does nothing if the snapshot is not found.

Example

var mixer = MediaFrames.AudioFrame.GetMixerByName("MasterMixer");
// Entering a cave scene — switch to the cave sound profile
MediaFrames.AudioFrame.SetMixerSnapshot(mixer, "Cave");

SetMixerTransitionToSnapshot

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

Parameters

Parameter	Type	Description
mixer	`AudioMixer`	Target mixer.
snapshots	`AudioMixerSnapshot[]`	Snapshots participating in the blend.
weights	`float[]`	Blend weight of each snapshot (matched one-to-one with `snapshots`).
timeToReach	`float`	Transition duration in seconds. Default: `0.02f`

Description

Smoothly transitions to a weighted blend of multiple snapshots over the given duration — useful for gradual ambience changes.

Example

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

// Transition to a 30% Normal + 70% Cave blend over 2 seconds
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)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Audio asset name (bundle assets use their Address; supports the `res#` prefix).
assetNames	`string[]`	Array of audio asset names (batch preloading).

Returns

UniTask — an awaitable async operation.

Description

Loads audio assets into the cache ahead of time, so a later Play call can use them immediately without a loading delay.

Example

// Preload a single asset
await MediaFrames.AudioFrame.Preload("TitleBgm");

// Preload in batch
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)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Audio asset name (bundle assets use their Address; supports the `res#` prefix).
sourceClip	`AudioClip`	Audio clip source. If provided, it overrides the `audioClip` on the instance (useful for assigning audio content dynamically).
parent	`Transform`	Parent node to attach to (for 3D audio positioning). Default: `null` (attached automatically to the matching `SoundType` node under the `AudioManager`)
loops	`int`	Loop count. `-1` = infinite loop; `> 0` = the given number of loops. Default: `0` (uses the loop setting of the `AudioBase` on the prefab)
volume	`float`	Volume. Overrides the volume when `> 0`. Default: `0f` (uses the default volume of the `AudioSource`)

Returns

UniTask<AudioBase> — the playing audio instance component; null if loading fails.

Description

Loads and plays the given audio.

Attention

If an audio asset with the same name is already playing and its SoundType is Sole (e.g., BGM), it is not played again — the existing instance is returned instead.
If an audio asset with the same name is paused, calling this resumes it.

Example

// Play the BGM (infinite loop)
var bgm = await MediaFrames.AudioFrame.Play("TitleBgm", null, -1);

// Play a sound effect from Resources
await MediaFrames.AudioFrame.Play("res#Audio/Sound/ClickSfx");

// Play from a specific package at 0.8 volume
await MediaFrames.AudioFrame.Play("OtherPackage", "Npc01Voice", volume: 0.8f);

// Play with a dynamically assigned AudioClip
await MediaFrames.AudioFrame.Play("SfxTemplate", downloadedClip);

Pause

public static void Pause(string assetName)

Parameters

Parameter	Type	Description
assetName	`string`	Audio asset name.

Description

Pauses all audio instances with the given name. Playback can be resumed via Play or ResumeAll.

PauseAll

public static void PauseAll()

Description

Pauses all playing audio.

ResumeAll

public static void ResumeAll()

Description

Resumes all paused audio. Audio that is currently playing is not affected.

Stop

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

Parameters

Parameter	Type	Description
assetName	`string`	Audio asset name.
disableEndEvent	`bool`	Whether to suppress the end event callback (`EndEvent`), so no end-of-playback handling is triggered on stop. Default: `false`
forceDestroy	`bool`	Whether to destroy the instance object forcibly. If not forced, the `onStopAndDestroy` setting on the prefab decides. Default: `false`

Description

Stops all audio instances with the given name. When instances are destroyed, reference counting determines whether the asset is unloaded automatically (see Reference Counting & Lifecycle).

Example

// Regular stop (the prefab settings decide whether to destroy)
MediaFrames.AudioFrame.Stop("TitleBgm");

// Stop + suppress the end event + force destroy
MediaFrames.AudioFrame.Stop("TitleBgm", true, true);

StopAll

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

Parameters

Parameter	Type	Description
disableEndEvent	`bool`	Whether to suppress the end event callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instance objects forcibly. Default: `false`

Description

Stops all audio instances. The parameters behave the same as in Stop.

ForceUnload

public static void ForceUnload(string assetName)

Parameters

Parameter	Type	Description
assetName	`string`	Audio asset name.

Description

Bypasses reference counting — forcibly stops and destroys playing instances, then unloads the source asset directly.

Important This releases the asset forcibly. Make sure the asset is no longer needed before calling it.

MediaFrames.VideoFrame

The unified video API. It controls video loading and playback (supporting both RenderTexture and Camera render modes), suitable for cutscenes, opening CGs, or animated UI backgrounds.

Method Overview

Initialization & Component Access

Method	Description
InitInstance	Initializes the `VideoManager` singleton instance.
GetComponent<T>	Gets the video instance component with the given name (first match).
GetComponents<T>	Gets all video instance components with the given name.

Playback & Asset Management

Method	Description
Preload	Preloads video assets into the cache.
Play	Plays a video asset and returns its `VideoBase` instance.
Pause	Pauses the video with the given name.
PauseAll	Pauses all videos.
ResumeAll	Resumes all paused videos.
Stop	Stops the video with the given name.
StopAll	Stops all videos.
ForceUnload	Forcibly unloads the video asset with the given name.

InitInstance

public static void InitInstance()

Description

Explicitly initializes the VideoManager singleton instance. It is recommended to call this once during game startup so the manager is ready ahead of time.

Attention If no VideoManager object exists in the scene, an error is logged.

GetComponent<T>

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

Parameters

Parameter	Type	Description
assetName	`string`	Video asset name.

Returns

T — the first video instance component matching the name; null if none is found.

Description

Gets the VideoBase component of the video instance with the given name. Only instances that have entered the playback list (i.e., after calling Play) can be retrieved — assets that are merely preloaded are not instantiated yet.

GetComponents<T>

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

Parameters

Parameter	Type	Description
assetName	`string`	Video asset name.

Returns

T[] — all video instance components matching the name; an empty array if none is found.

Description

Gets all video instance components with the given name.

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)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Video asset name (bundle assets use their Address; supports the `res#` prefix).
assetNames	`string[]`	Array of video asset names (batch preloading).

Returns

UniTask — an awaitable async operation.

Description

Loads video assets into the cache ahead of time, so a later Play call can use them immediately without a loading delay.

Example

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)

Parameters

Parameter	Type	Description
packageName	`string`	Package name. If omitted, the default package is used.
assetName	`string`	Video asset name (bundle assets use their Address; supports the `res#` prefix).
sourceClip	`VideoClip`	Video clip source. If provided, it overrides the `videoClip` on the instance (useful for assigning video content dynamically).
parent	`Transform`	Parent node to attach to. Default: `null` (attached under the `VideoManager` node)
loops	`int`	Loop count. `-1` = infinite loop; `> 0` = the given number of loops. Default: `0` (uses the loop setting of the `VideoBase` on the prefab)
volume	`float`	Volume. Overrides the volume when `> 0`. Default: `0f` (uses the default volume of the `VideoPlayer`)

Returns

UniTask<VideoBase> — the playing video instance component; null if loading fails.

Description

Loads and plays the given video.

Attention

If a video with the same name is already playing, it is not played again — the existing instance is returned instead.
If a video with the same name is paused, calling this resumes it.

Example

// Play a cutscene video
var video = await MediaFrames.VideoFrame.Play("OpeningCutscene");

// Play with a dynamically assigned VideoClip
await MediaFrames.VideoFrame.Play("VideoTemplate", downloadedClip);

Pause

public static void Pause(string assetName)

Parameters

Parameter	Type	Description
assetName	`string`	Video asset name.

Description

Pauses all video instances with the given name. Playback can be resumed via Play or ResumeAll.

PauseAll

public static void PauseAll()

Description

Pauses all playing videos.

ResumeAll

public static void ResumeAll()

Description

Resumes all paused videos. Videos that are currently playing are not affected.

Stop

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

Parameters

Parameter	Type	Description
assetName	`string`	Video asset name.
disableEndEvent	`bool`	Whether to suppress the end event callback (`EndEvent`), so no end-of-playback handling is triggered on stop. Default: `false`
forceDestroy	`bool`	Whether to destroy the instance object forcibly. If not forced, the `onStopAndDestroy` setting on the prefab decides. Default: `false`

Description

Stops all video instances with the given name. When instances are destroyed, reference counting determines whether the asset is unloaded automatically (see Reference Counting & Lifecycle).

StopAll

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

Parameters

Parameter	Type	Description
disableEndEvent	`bool`	Whether to suppress the end event callback. Default: `false`
forceDestroy	`bool`	Whether to destroy the instance objects forcibly. Default: `false`

Description

Stops all video instances. The parameters behave the same as in Stop.

ForceUnload

public static void ForceUnload(string assetName)

Parameters

Parameter	Type	Description
assetName	`string`	Video asset name.

Description

Bypasses reference counting — forcibly stops and destroys playing instances, then unloads the source asset directly.

Important Video files are usually large. Once a video is no longer needed, call this method manually to force-release the memory.

Example

// The cutscene has finished and is no longer needed
MediaFrames.VideoFrame.ForceUnload("OpeningCutscene");

Coding Style wiki​

Quick Start​

General Rules​

Asset Name Prefix​

Package​

Reference Counting & Lifecycle​

MediaFrames.AudioFrame​

Method Overview​

Initialization & Component Access​

Mixer Control​

Playback & Asset Management​

InitInstance​

GetComponent<T>​

GetComponents<T>​

GetMixerByName​

SetMixerExposedParam​

ClearMixerExposedParam​

AutoClearMixerExposedParams​

AutoRestoreMixerExposedParams​

GetMixerSnapshot​

SetMixerSnapshot​

SetMixerTransitionToSnapshot​

Preload​

Play​

Pause​

PauseAll​

ResumeAll​

Stop​

StopAll​

ForceUnload​

MediaFrames.VideoFrame​

Method Overview​

Initialization & Component Access​

Playback & Asset Management​

InitInstance​

GetComponent<T>​

GetComponents<T>​

Preload​

Play​

Pause​

PauseAll​

ResumeAll​

Stop​

StopAll​

ForceUnload​

Coding Style wiki

Quick Start

General Rules

Asset Name Prefix

Package

Reference Counting & Lifecycle

MediaFrames.AudioFrame

Method Overview

Initialization & Component Access

Mixer Control

Playback & Asset Management

InitInstance

GetComponent<T>

GetComponents<T>

GetMixerByName

SetMixerExposedParam

ClearMixerExposedParam

AutoClearMixerExposedParams

AutoRestoreMixerExposedParams

GetMixerSnapshot

SetMixerSnapshot

SetMixerTransitionToSnapshot

Preload

Play

Pause

PauseAll

ResumeAll

Stop

StopAll

ForceUnload

MediaFrames.VideoFrame

Method Overview

Initialization & Component Access

Playback & Asset Management

InitInstance

GetComponent<T>

GetComponents<T>

Preload

Play

Pause

PauseAll

ResumeAll

Stop

StopAll

ForceUnload