登录
侧边栏壁纸
博主头像
勇芳

  • 累计撰写 330 篇文章
  • 累计收到 0 条评论
VisualFreeBasic编程文档

SDL3_API分类参考_SDL_mixer 核心 API 集合（CategorySDLMixer）

勇芳
2026-3-7 / 0 评论 / 6 阅读

SDL_mixer 核心 API 集合（CategorySDLMixer）

SDL_mixer 是 SDL 官方的音频混音扩展库，旨在简化复杂的音频处理任务。它提供音频文件解码、多音效混音、基础 3D 定位音频、各类音频特效等核心能力，支持实时混音输出到多个音频设备，也可将混音数据生成到内存缓冲区，甚至能同时完成这两种操作，是 SDL 生态中处理音频播放与混音的核心工具。

核心概念与使用流程

  1. 初始化：调用 MIX_Init() 初始化库，指定支持的音频格式；
  2. 创建混音器：通过 MIX_CreateMixerDevice()（输出到硬件）或 MIX_CreateMixer()（输出到内存）创建混音器实例；
  3. 加载音频：使用 MIX_LoadAudio() 加载音频文件为可复用的 MIX_Audio 对象；
  4. 创建轨道：通过 MIX_CreateTrack() 创建音频轨道（每轨道对应一个同时播放的音效）；
  5. 绑定音频：用 MIX_SetTrackAudio() 将音频数据绑定到轨道；
  6. 播放控制：调用 MIX_PlayTrack() 播放轨道，支持循环、淡入淡出等效果；
  7. 高级控制：可设置轨道音量、3D 位置、播放速度，或通过标签批量控制多轨道；
  8. 清理：使用完毕后销毁轨道、混音器，调用 MIX_Quit() 释放资源。

核心 API 列表（按功能分类）

一、基础初始化与版本管理

  • MIX_Init：初始化 SDL_mixer 库（需指定支持的音频格式，如 MP3/OGG 等）
  • MIX_Quit：清理 SDL_mixer 所有资源（程序退出前必须调用）
  • MIX_Version：获取当前 SDL_mixer 版本信息
  • SDL_MIXER_MAJOR_VERSION：SDL_mixer 主版本号宏（如 3 代表 SDL_mixer 3.x）
  • SDL_MIXER_MINOR_VERSION：SDL_mixer 次版本号宏
  • SDL_MIXER_MICRO_VERSION：SDL_mixer 修订版本号宏
  • SDL_MIXER_VERSION：构造版本结构体的宏
  • SDL_MIXER_VERSION_ATLEAST：编译期检查版本是否满足最低要求

二、音频数据（MIX_Audio）管理

1. 音频加载/销毁

  • MIX_LoadAudio：从文件加载音频数据为 MIX_Audio 对象（自动解码）
  • MIX_LoadAudio_IO：从 SDL_IOStream 流加载音频数据
  • MIX_LoadAudioWithProperties：带自定义属性加载音频（如采样率、声道数）
  • MIX_LoadAudioNoCopy：加载音频但不复制数据（直接使用内存缓冲区）
  • MIX_LoadRawAudio：加载原始 PCM 音频数据（无需解码）
  • MIX_LoadRawAudio_IO：从流加载原始 PCM 音频
  • MIX_LoadRawAudioNoCopy：加载原始 PCM 音频且不复制数据
  • MIX_CreateSineWaveAudio：生成正弦波音频数据（用于测试/音效生成）
  • MIX_DestroyAudio：销毁 MIX_Audio 对象，释放音频数据

2. 音频属性查询

  • MIX_GetAudioFormat：获取音频的 PCM 格式（如 SDL_AUDIO_F32、SDL_AUDIO_S16）
  • MIX_GetAudioDuration：获取音频总时长（采样帧数）
  • MIX_GetAudioProperties：获取音频的元数据（如 ID3 标签、时长、码率等）
  • MIX_AudioFramesToMS：将音频的采样帧数转换为毫秒
  • MIX_AudioMSToFrames：将毫秒转换为音频的采样帧数

三、音频解码器（MIX_AudioDecoder）

  • MIX_CreateAudioDecoder：创建音频解码器实例（通用接口）
  • MIX_CreateAudioDecoder_IO：从 SDL_IOStream 流创建解码器
  • MIX_DestroyAudioDecoder：销毁解码器实例
  • MIX_DecodeAudio：解码音频数据到 PCM 格式
  • MIX_GetAudioDecoder：获取指定索引的解码器名称（如 "mp3"、"ogg"）
  • MIX_GetNumAudioDecoders：获取支持的解码器总数
  • MIX_GetAudioDecoderFormat：获取解码器输出的 PCM 格式
  • MIX_GetAudioDecoderProperties：获取解码器配置属性

四、混音器（MIX_Mixer）管理

1. 混音器创建/销毁

  • MIX_CreateMixer：创建内存混音器（输出到内存缓冲区）
  • MIX_CreateMixerDevice：创建设备混音器（输出到音频硬件）
  • MIX_DestroyMixer：销毁混音器实例
  • MIX_LockMixer：锁定混音器（防止多线程操作冲突）
  • MIX_UnlockMixer：解锁混音器

2. 混音器属性控制

  • MIX_GetMixerFormat：获取混音器输出的 PCM 格式
  • MIX_GetMixerGain：获取混音器主音量增益（0.0~1.0）
  • MIX_SetMixerGain：设置混音器主音量增益
  • MIX_GetMixerFrequencyRatio：获取混音器输出的播放速度比例
  • MIX_SetMixerFrequencyRatio：设置播放速度比例（>1 加速，<1 减速，同步调整音调）
  • MIX_GetMixerProperties：获取混音器完整配置属性
  • MIX_SetPostMixCallback：设置混音后回调（处理最终输出的 PCM 数据）
  • MIX_Generate：手动触发混音器生成音频数据（内存混音器专用）

五、音频轨道（MIX_Track）管理

1. 轨道创建/销毁

  • MIX_CreateTrack：创建音频轨道（混音器的核心播放单元）
  • MIX_DestroyTrack：销毁轨道实例

2. 轨道输入绑定

  • MIX_SetTrackAudio：将 MIX_Audio 绑定到轨道（播放预加载的音频）
  • MIX_SetTrackAudioStream：将 SDL_AudioStream 绑定到轨道（流式播放）
  • MIX_SetTrackIOStream：将 SDL_IOStream 绑定到轨道（实时解码播放）
  • MIX_SetTrackRawIOStream：绑定原始 PCM 数据流到轨道

3. 播放控制

  • MIX_PlayTrack：播放轨道（支持循环次数、淡入淡出、起始位置等参数）
  • MIX_PlayAudio：快速播放 MIX_Audio（自动创建临时轨道）
  • MIX_PauseTrack：暂停指定轨道
  • MIX_ResumeTrack：恢复暂停的轨道
  • MIX_StopTrack：停止轨道播放
  • MIX_PauseAllTracks：暂停所有轨道
  • MIX_ResumeAllTracks：恢复所有轨道
  • MIX_StopAllTracks：停止所有轨道
  • MIX_TrackPlaying：检查轨道是否正在播放
  • MIX_TrackPaused：检查轨道是否处于暂停状态

4. 轨道属性控制

  • MIX_GetTrackGain：获取轨道音量增益
  • MIX_SetTrackGain：设置轨道音量增益（独立于主音量）
  • MIX_GetTrackFrequencyRatio：获取轨道播放速度比例
  • MIX_SetTrackFrequencyRatio：设置轨道播放速度（同步调整音调）
  • MIX_GetTrackLoops：获取轨道循环次数
  • MIX_SetTrackLoops：设置轨道循环次数（0=播放1次，-1=无限循环）
  • MIX_GetTrackFadeFrames：获取轨道淡入/淡出的采样帧数
  • MIX_SetTrackOutputChannelMap：设置轨道输出声道映射（调整音频输出到指定扬声器）
  • MIX_GetTrackPlaybackPosition：获取轨道当前播放位置（采样帧）
  • MIX_SetTrackPlaybackPosition：设置轨道播放位置（定位到指定帧）
  • MIX_GetTrackRemaining：获取轨道剩余播放帧数

5. 3D 与立体声控制

  • MIX_SetTrack3DPosition：设置轨道的 3D 空间位置（支持距离衰减、空间化）
  • MIX_GetTrack3DPosition：获取轨道的 3D 位置
  • MIX_SetTrackStereo：设置轨道的立体声平衡（左右声道音量比例）

6. 轨道标签与批量控制

  • MIX_TagTrack：为轨道添加自定义标签（如 "music"、"ui_sfx"）
  • MIX_UntagTrack：移除轨道的指定标签
  • MIX_GetTrackTags：获取轨道的所有标签
  • MIX_GetTaggedTracks：获取指定标签的所有轨道
  • MIX_PlayTag：播放所有带指定标签的轨道
  • MIX_PauseTag：暂停所有带指定标签的轨道
  • MIX_ResumeTag：恢复所有带指定标签的轨道
  • MIX_StopTag：停止所有带指定标签的轨道
  • MIX_SetTagGain：设置指定标签所有轨道的音量增益

7. 轨道回调函数

  • MIX_SetTrackRawCallback：设置原始音频回调（解码后、未处理前的 PCM 数据）
  • MIX_SetTrackCookedCallback：设置处理后音频回调（应用淡入淡出、3D 等效果后的 PCM 数据）
  • MIX_SetTrackStoppedCallback：设置轨道播放结束回调

8. 时间转换

  • MIX_TrackFramesToMS：将轨道的采样帧数转换为毫秒
  • MIX_TrackMSToFrames：将毫秒转换为轨道的采样帧数
  • MIX_FramesToMS：通用的帧数转毫秒
  • MIX_MSToFrames：通用的毫秒转帧数

六、音频组（MIX_Group）管理

  • MIX_CreateGroup：创建音频组（管理一组轨道，单独混音）
  • MIX_DestroyGroup：销毁音频组
  • MIX_SetTrackGroup：将轨道加入指定音频组
  • MIX_GetGroupMixer：获取音频组的混音器实例
  • MIX_GetGroupProperties：获取音频组属性
  • MIX_SetGroupPostMixCallback：设置音频组混音后回调（处理组内轨道的混音数据）

七、通用工具函数

  • MIX_GetTrackMixer：获取轨道所属的混音器
  • MIX_GetTrackAudio：获取轨道绑定的 MIX_Audio 对象
  • MIX_GetTrackAudioStream：获取轨道绑定的音频流

数据类型（Datatypes）

  • MIX_Audio：封装解码后的音频数据（PCM 数据、格式、时长等）
  • MIX_AudioDecoder：音频解码器实例（用于解码各类音频格式）
  • MIX_Group：音频组对象（管理一组轨道，支持独立混音）
  • MIX_GroupMixCallback：音频组混音回调函数类型
  • MIX_Mixer：混音器实例（核心混音单元，分设备/内存两种）
  • MIX_PostMixCallback：混音后回调函数类型（处理最终输出数据）
  • MIX_Track：音频轨道对象（混音器的播放单元，每轨道对应一个音效）
  • MIX_TrackMixCallback：轨道音频回调函数类型（处理原始/处理后数据）
  • MIX_TrackStoppedCallback：轨道播放结束回调函数类型

结构体（Structs）

  • MIX_Point3D：3D 空间坐标结构体（用于设置轨道的 3D 位置）
  • MIX_StereoGains：立体声增益结构体（左右声道音量比例）

FreeBASIC 示例代码

' 引入 SDL 及 SDL_mixer 相关声明（需链接 SDL3 和 SDL3_mixer 库）
#Include "SDL.bi"
#Include "SDL_mixer.bi"

' 补充关键常量/类型声明（FreeBASIC 绑定可能缺失）
#Define MIX_INIT_MP3 1
#Define MIX_INIT_OGG 2
Type MIX_Point3D
    x As Float
    y As Float
    z As Float
End Type

' 检查 SDL_mixer 版本
Sub CheckMixerVersion()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "【检查 SDL_mixer 版本】")

    Dim As SDL_version ver
    MIX_Version(@ver)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "SDL_mixer 版本：%d.%d.%d", ver.major, ver.minor, ver.patch)

    ' 编译期版本检查
    #If SDL_MIXER_VERSION_ATLEAST(3, 0, 0)
        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "✓ 满足 SDL_mixer 3.0.0 最低版本要求")
    #Else
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "✗ 不满足 SDL_mixer 3.0.0 最低版本要求")
    #EndIf
End Sub

' 轨道播放结束回调函数
Sub TrackStoppedCallback Cdecl (ByVal track As MIX_Track Ptr, ByVal userdata As Any Ptr)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "【回调】轨道播放结束！")
End Sub

' 基础音频播放示例
Sub BasicAudioPlaybackExample(ByVal audioPath As ZString Ptr)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "【基础音频播放示例】")

    ' 1. 初始化 SDL_mixer（支持 MP3 和 OGG）
    Dim As Integer initFlags = MIX_INIT_MP3 Or MIX_INIT_OGG
    If (MIX_Init(initFlags) <> initFlags) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_mixer 初始化失败：%s", MIX_GetError())
        Exit Sub
    End If

    ' 2. 创建设备混音器（输出到默认音频设备）
    Dim As MIX_Mixer Ptr mixer = MIX_CreateMixerDevice(NULL)
    If (mixer = NULL) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "创建混音器失败：%s", MIX_GetError())
        MIX_Quit()
        Exit Sub
    End If

    ' 3. 加载音频文件
    Dim As MIX_Audio Ptr audio = MIX_LoadAudio(audioPath)
    If (audio = NULL) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "加载音频失败：%s", MIX_GetError())
        MIX_DestroyMixer(mixer)
        MIX_Quit()
        Exit Sub
    End If

    ' 4. 查询音频属性
    Dim As Uint32 audioFormat
    Dim As Integer freq, channels
    MIX_GetAudioFormat(audio, @audioFormat, @freq, @channels)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "音频格式：%u, 采样率：%d Hz, 声道数：%d", audioFormat, freq, channels)

    Dim As Uint64 totalFrames = MIX_GetAudioDuration(audio)
    Dim As Uint64 totalMS = MIX_AudioFramesToMS(audio, totalFrames)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "音频时长：%llu 帧 / %llu 毫秒", totalFrames, totalMS)

    ' 5. 创建音频轨道
    Dim As MIX_Track Ptr track = MIX_CreateTrack(mixer)
    If (track = NULL) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "创建轨道失败：%s", MIX_GetError())
        MIX_DestroyAudio(audio)
        MIX_DestroyMixer(mixer)
        MIX_Quit()
        Exit Sub
    End If

    ' 6. 配置轨道
    MIX_SetTrackAudio(track, audio)          ' 绑定音频数据
    MIX_SetTrackGain(track, 0.8)             ' 设置轨道音量（80%）
    MIX_SetTrackLoops(track, 1)              ' 循环1次（总共播放2次）
    MIX_SetTrackStoppedCallback(track, @TrackStoppedCallback, NULL)  ' 设置结束回调
    MIX_TagTrack(track, "music")             ' 添加标签

    ' 7. 设置 3D 位置（右侧 2 米处）
    Dim As MIX_Point3D pos = {2.0, 0.0, 0.0}
    MIX_SetTrack3DPosition(track, @pos)

    ' 8. 播放轨道
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "开始播放音频...")
    If (MIX_PlayTrack(track, 0, 0, 0) = SDL_FALSE) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "播放轨道失败：%s", MIX_GetError())
    End If

    ' 9. 等待播放完成（简单演示，实际项目需用事件循环）
    While (MIX_TrackPlaying(track))
        SDL_Delay(100)
        ' 打印当前播放进度
        Dim As Uint64 currFrames = MIX_GetTrackPlaybackPosition(track)
        Dim As Uint64 currMS = MIX_TrackFramesToMS(track, currFrames)
        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "播放进度：%llu/%llu 毫秒", currMS, totalMS)
    Wend

    ' 10. 释放资源
    MIX_DestroyTrack(track)
    MIX_DestroyAudio(audio)
    MIX_DestroyMixer(mixer)
    MIX_Quit()

    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "音频播放完成")
End Sub

' 批量控制带标签的轨道示例
Sub TagBasedControlExample(ByVal mixer As MIX_Mixer Ptr, ByVal sfxPath As ZString Ptr)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "【标签批量控制示例】")

    ' 1. 加载音效并创建多个带 "ui_sfx" 标签的轨道
    Dim As MIX_Audio Ptr sfxAudio = MIX_LoadAudio(sfxPath)
    If (sfxAudio = NULL) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "加载音效失败：%s", MIX_GetError())
        Exit Sub
    End If

    ' 创建3个UI音效轨道
    For i As Integer = 0 To 2
        Dim As MIX_Track Ptr track = MIX_CreateTrack(mixer)
        If (track <> NULL) Then
            MIX_SetTrackAudio(track, sfxAudio)
            MIX_SetTrackGain(track, 0.5)
            MIX_TagTrack(track, "ui_sfx")
        End If
    Next

    ' 2. 批量播放所有 "ui_sfx" 标签的轨道
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "批量播放 UI 音效...")
    MIX_PlayTag(mixer, "ui_sfx", 0, 0, 0)

    ' 3. 延迟后批量暂停
    SDL_Delay(500)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "批量暂停 UI 音效...")
    MIX_PauseTag(mixer, "ui_sfx")

    ' 4. 延迟后批量恢复
    SDL_Delay(500)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "批量恢复 UI 音效...")
    MIX_ResumeTag(mixer, "ui_sfx")

    ' 5. 等待播放完成
    SDL_Delay(1000)

    ' 6. 释放资源
    MIX_DestroyAudio(sfxAudio)
End Sub

' 主程序
Sub Main()
    ' 初始化 SDL 音频子系统
    If (SDL_Init(SDL_INIT_AUDIO) < 0) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL 初始化失败：%s", SDL_GetError())
        Exit Sub
    End If

    ' 运行示例
    CheckMixerVersion()
    BasicAudioPlaybackExample(StrPtr("background_music.mp3"))  ' 替换为实际音频文件路径
    ' TagBasedControlExample(mixer, StrPtr("ui_click.wav"))  ' 需先创建混音器，此处仅演示

    ' 清理 SDL
    SDL_Quit()

    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "程序正常退出")
End Sub

' 运行主程序
Main()

核心知识点补充

  1. 采样帧与时间转换：

    • SDL_mixer 中所有时间计算基于「采样帧」（Sample Frame），而非毫秒，确保采样级精度；
    • 立体声 16 位 PCM 音频：1 帧 = 2 采样 × 2 字节 = 4 字节；
    • 不同采样率的音频，相同毫秒对应的帧数不同，需用 MIX_TrackMSToFrames() 等函数转换。

  2. 混音器类型选择：

    • 设备混音器（MIX_CreateMixerDevice）：输出到音频硬件，适合实时播放；
    • 内存混音器（MIX_CreateMixer）：输出到内存缓冲区，适合音频录制、离线处理。

  3. 3D 音频限制：

    • SDL_mixer 仅提供基础 3D 定位（距离衰减、立体声空间化），不支持复杂的 3D 音效（如混响、遮挡）；
    • 如需专业 3D 音频，建议搭配 OpenAL 等专用库；
    • 3D 效果仅在立体声/环绕声设备上生效，单声道设备无效果。

  4. 性能优化要点：

    • 复用 MIX_Audio 对象（加载一次，多次播放），避免重复解码；
    • 复用轨道对象（播放不同音频时仅需调用 MIX_SetTrackAudio()）；
    • 大量音效播放时使用标签批量控制，减少循环遍历；
    • 多线程操作混音器时必须调用 MIX_LockMixer()/MIX_UnlockMixer() 加锁。

  5. 跨平台注意事项：

    • Windows/macOS 支持主流音频格式（MP3/OGG/WAV/FLAC），Linux 需确保安装对应解码器；
    • 移动平台需将音频文件放入 assets 目录，使用绝对路径加载；
    • 音频设备权限：Android/iOS 需申请音频播放权限（Android 13+ 需 POST_NOTIFICATIONS 权限）。

总结

  1. 核心优势：

    • 一站式音频解决方案：解码、混音、播放、特效全覆盖，无需集成多个音频库；
    • 无缝衔接 SDL 核心库，与 SDL 窗口/事件系统兼容；
    • 支持多轨道混音、3D 定位、播放速度调整等常用功能，满足游戏/多媒体开发需求；
    • 高精度时间控制（采样帧级），支持实时/离线混音；
    • 灵活的回调机制，可自定义音频处理逻辑。

  2. 使用建议：

    • 初始化时仅加载需要的解码器（减少内存占用）；
    • 预加载常用音频为 MIX_Audio 对象，播放时复用轨道；
    • 音效分类管理：用标签区分音乐、UI 音效、环境音效，方便批量控制；
    • 实时音频处理（如音效滤镜）可通过 Raw/Cooked 回调实现；
    • 避免在主线程中长时间阻塞，建议用回调/事件处理播放状态。

  3. 关键点回顾：

    • SDL_mixer 是 SDL 的音频混音扩展库，核心是混音器（Mixer）、轨道（Track）、音频数据（Audio）三层结构；
    • MIX_Init()/MIX_Quit() 是必选的初始化/清理接口，需指定支持的音频格式；
    • 轨道是播放的基本单元，支持音量、速度、3D 位置、标签等配置；
    • 时间计算基于采样帧，需通过专用函数转换为毫秒；
    • 标签功能可批量控制多轨道，适合游戏中按类型管理音效。
0
版权属于： 勇芳
本文链接： http://bbs.yfvb.com/post-332.html
文章声明： 本文版权内容属于《勇芳软件工作室》转载请标明出处
相关推荐
VisualFreeBasic控件_Miniblink 小型谷歌浏览器
VisualFreeBasic控件_Miniblink 小型谷歌浏览器
 VisualFreeBasic代码_函数指针
VisualFreeBasic代码_函数指针
 VisualFreeBasic指南_代码库
VisualFreeBasic指南_代码库
 VisualFreeBasic游戏趣味编程_4.5_循环的嵌套
VisualFreeBasic游戏趣味编程_4.5_循环的嵌套

评论一下？

OωO
取消