AudioAsset

Uniasset.Audio.AudioAsset 是 Uniasset 音频模块的核心类，提供音频加载、读取和转换功能。

类定义

namespace Uniasset.Audio
{
    public sealed class AudioAsset : IDisposable { }
}

属性

SampleRate

public int SampleRate { get; }

音频采样率（Hz），例如 44100、48000。

SampleCount

public long SampleCount { get; }

总采样点数。对于多声道音频，SampleCount = FrameCount * ChannelCount。

ChannelCount

public int ChannelCount { get; }

声道数。1 = 单声道，2 = 立体声。

FrameCount

public long FrameCount { get; }

总帧数。一帧包含所有声道的一个采样点。

UnsafeHandle

public UnsafeAudioAsset UnsafeHandle { get; }

获取底层的不安全句柄。仅在需要直接调用 FFI 时使用。

方法

Load

public void Load(string path, SampleFormat sampleFormat = SampleFormat.Float)

从文件路径加载音频。

参数：

参数	类型	默认值	说明
path	string	—	音频文件路径
sampleFormat	SampleFormat	Float	采样格式

var audio = new AudioAsset();
audio.Load("music.mp3");

---

Load (Span\<byte>)

public void Load(Span<byte> data, SampleFormat sampleFormat = SampleFormat.Float)

从字节数组加载音频。

参数：

参数	类型	默认值	说明
data	Span<byte>	—	音频数据
sampleFormat	SampleFormat	Float	采样格式

byte[] audioData = File.ReadAllBytes("music.mp3");
audio.Load(audioData);

---

LoadIO

public void LoadIO(IUniassetStream stream, SampleFormat sampleFormat = SampleFormat.Float)

从自定义流加载音频。详见 自定义流。

---

Tell

public long Tell()

获取当前读取位置（帧索引）。

返回值： 当前帧位置。

long position = audio.Tell();
Debug.Log($"当前位置: {position} / {audio.FrameCount}");

---

Seek

public void Seek(long position)

跳转到指定帧位置。

参数：

参数	类型	说明
position	long	目标帧位置

// 跳转到第 1000 帧
audio.Seek(1000);

---

Read\<T>

public int Read<T>(Span<T> buffer, int frameCount) where T : unmanaged

读取 PCM 帧数据到缓冲区。

参数：

参数	类型	说明
buffer	Span<T>	目标缓冲区
frameCount	int	要读取的帧数

返回值： 实际读取的帧数。

类型参数 T： 应与加载时指定的 SampleFormat 匹配：

SampleFormat	T
Float	float
Int16	short

// 读取 1024 帧
float[] buffer = new float[1024 * audio.ChannelCount];
int framesRead = audio.Read<float>(buffer, 1024);

---

ToAudioClip

public AudioClip ToAudioClip(string name = "created_from_uniasset", bool stream = true)

将音频转换为 Unity AudioClip。

参数：

参数	类型	默认值	说明
name	string	"created_from_uniasset"	AudioClip 名称
stream	bool	true	是否使用流式播放

返回值： 创建的 AudioClip 实例。

流式播放 (stream = true)：

• 音频数据在播放时按需读取
• 内存占用低，适合长音频
• 适合背景音乐、播客等

全量加载 (stream = false)：

• 所有音频数据预先加载到内存
• 播放延迟低，适合短音效
• 适合游戏音效、UI 音效等

// 流式播放（适合背景音乐）
AudioClip bgm = audio.ToAudioClip("BGM", stream: true);

// 全量加载（适合音效）
AudioClip sfx = audio.ToAudioClip("Explosion", stream: false);

---

Unload

public void Unload()

卸载已加载的音频数据。卸载后可以重新调用 Load 方法加载新音频。

---

Dispose

public void Dispose()

释放所有资源。释放后不可再使用此实例。

示例

加载音频并播放

using Uniasset;
using Uniasset.Audio;

using var audio = new AudioAsset();
audio.Load("background.mp3");

AudioClip clip = audio.ToAudioClip("BGM");
audioSource.clip = clip;
audioSource.Play();

手动读取 PCM 数据

using var audio = new AudioAsset();
audio.Load("music.flac", SampleFormat.Float);

// 逐块读取
float[] buffer = new float[4096];
int totalFramesRead = 0;

while (true)
{
    int framesRead = audio.Read<float>(buffer, buffer.Length / audio.ChannelCount);
    if (framesRead == 0) break;

    totalFramesRead += framesRead;
    // 处理 buffer 中的数据...
}

Debug.Log($"总共读取 {totalFramesRead} 帧");

使用 Int16 格式

using var audio = new AudioAsset();
audio.Load("sound.wav", SampleFormat.Int16);

short[] buffer = new short[2048];
int framesRead = audio.Read<short>(buffer, 1024);