HarmonyOS开发：游戏音频——背景音乐与音效管理

📌 核心要点：游戏音频不是"播放个mp3"那么简单，背景音乐要无缝循环，音效要并发播放且互不干扰，3D空间音频还要考虑距离衰减和声源方位，音频架构设计不好，游戏体验直接拉胯。

背景与动机

你有没有玩过那种"静音玩也没差"的游戏？

画面再炫、操作再爽，没有声音，游戏就像一盘没放盐的菜——能吃，但没味。枪声、脚步声、背景音乐、环境音效……这些声音构成了游戏的"氛围感"。

但游戏音频开发有个很现实的问题：鸿蒙的音频API不是为游戏设计的。

鸿蒙的@ohos.multimedia.media模块主要面向媒体播放场景（音乐播放器、视频播放器），不是游戏音频场景。你要是用它来播游戏音效，会发现一堆问题：延迟高、并发数有限、无法精确控制播放位置。

怎么办？得自己封装一层游戏音频管理器，把鸿蒙的音频API改造成游戏可用的形态。

核心原理

游戏音频架构

游戏音频分两大类：背景音乐（BGM）和音效（SFX）。它们的播放需求完全不同：

graph TB
    A[游戏音频系统] --> B[背景音乐BGM]
    A --> C[音效SFX]
    A --> D[3D空间音频]
    
    B --> B1[流式播放]
    B --> B2[无缝循环]
    B --> B3[淡入淡出]
    B --> B4[多轨道切换]
    
    C --> C1[即时播放]
    C --> C2[并发控制]
    C --> C3[音效池复用]
    C --> C4[优先级管理]
    
    D --> D1[距离衰减]
    D --> D2[声源方位]
    D --> D3[多普勒效应]
    D --> D4[环境混响]
    
    classDef mainStyle fill:#9B59B6,stroke:#8E44AD,color:#fff,font-weight:bold
    classDef bgmStyle fill:#E74C3C,stroke:#C0392B,color:#fff
    classDef sfxStyle fill:#3498DB,stroke:#2980B9,color:#fff
    classDef spatialStyle fill:#27AE60,stroke:#229954,color:#fff
    
    class A mainStyle
    class B,B1,B2,B3,B4 bgmStyle
    class C,C1,C2,C3,C4 sfxStyle
    class D,D1,D2,D3,D4 spatialStyle

音效池与并发控制

游戏里经常出现"同一时间多个相同音效"的情况——比如10发子弹同时命中，总不能只播一声吧？但又不能开10个播放器，系统资源扛不住。

解决方案是音效池：预创建固定数量的播放器，播放时从池中取一个空闲的，播完还回池里。类似数据库连接池的思路。

3D空间音频

3D游戏里，声音不是"从手机扬声器出来"那么简单。远处的爆炸声应该小，近处的脚步声应该大；左边的枪声应该偏左耳，右边的应该偏右耳。

这就是3D空间音频的核心：距离衰减和声源方位。

距离衰减公式（反距离模型）：

gain = referenceDistance / (referenceDistance + rolloffFactor * (distance - referenceDistance))

声源方位通过HRTF（头部相关传输函数）或简单的左右声道平衡来实现。

代码实战

基础用法：音频播放管理器

先搞定最基础的——能播BGM、能播音效、能控制音量。

// AudioManager.ets - 游戏音频管理器
import { media } from '@kit.MediaKit'
import { fileIo } from '@kit.CoreFileKit'

// 音频类型
enum AudioType {
  BGM,    // 背景音乐
  SFX,    // 音效
  VOICE   // 语音
}

// 音频播放状态
enum AudioState {
  IDLE,
  PLAYING,
  PAUSED,
  STOPPED
}

// 音效池中的播放单元
class SfxPlayerUnit {
  player: media.AVPlayer | null = null
  busy: boolean = false
  audioId: string = ''

  // 播放音效
  async play(path: string, volume: number): Promise<void> {
    if (this.player) {
      // 复用已有播放器
      await this.player.reset()
    } else {
      this.player = await media.createAVPlayer()
    }

    this.busy = true
    this.audioId = path

    // 设置音频源
    const fd = await fileIo.open(path, fileIo.OpenMode.READ_ONLY)
    this.player.fdSrc = { fd: fd, offset: 0, length: -1 }

    // 设置音量
    this.player.setVolume(volume)

    // 播放完成后归还到池
    this.player.on('stateChange', (state: string) => {
      if (state === 'completed' || state === 'stopped') {
        this.busy = false
        this.audioId = ''
      }
    })

    // 准备并播放
    await this.player.prepare()
    await this.player.play()
  }

  // 停止
  async stop(): Promise<void> {
    if (this.player && this.busy) {
      await this.player.stop()
      this.busy = false
    }
  }
}

// 游戏音频管理器
class GameAudioManager {
  // BGM播放器
  private bgmPlayer: media.AVPlayer | null = null
  private bgmVolume: number = 0.5
  private bgmState: AudioState = AudioState.IDLE
  private currentBgm: string = ''

  // 音效池
  private sfxPool: SfxPlayerUnit[] = []
  private sfxPoolSize: number = 8
  private sfxVolume: number = 0.8

  // 语音播放器
  private voicePlayer: media.AVPlayer | null = null
  private voiceVolume: number = 1.0

  // 全局静音
  private muted: boolean = false

  constructor() {
    // 初始化音效池
    for (let i = 0; i < this.sfxPoolSize; i++) {
      this.sfxPool.push(new SfxPlayerUnit())
    }
  }

  // ========== BGM相关 ==========

  // 播放BGM
  async playBgm(path: string, fadeIn: number = 1000): Promise<void> {
    if (this.muted) return

    // 同一首BGM不重复播放
    if (this.currentBgm === path && this.bgmState === AudioState.PLAYING) return

    // 停止当前BGM
    if (this.bgmPlayer && this.bgmState !== AudioState.IDLE) {
      await this.stopBgm(fadeIn)
    }

    // 创建或复用播放器
    if (!this.bgmPlayer) {
      this.bgmPlayer = await media.createAVPlayer()
    }

    this.currentBgm = path

    // 设置音频源
    const fd = await fileIo.open(path, fileIo.OpenMode.READ_ONLY)
    this.bgmPlayer.fdSrc = { fd: fd, offset: 0, length: -1 }

    // 设置循环播放
    this.bgmPlayer.loop = true

    // 淡入效果
    if (fadeIn > 0) {
      this.bgmPlayer.setVolume(0)
      await this.bgmPlayer.prepare()
      await this.bgmPlayer.play()
      this.fadeVolume(this.bgmPlayer, 0, this.bgmVolume, fadeIn)
    } else {
      this.bgmPlayer.setVolume(this.bgmVolume)
      await this.bgmPlayer.prepare()
      await this.bgmPlayer.play()
    }

    this.bgmState = AudioState.PLAYING
  }

  // 停止BGM
  async stopBgm(fadeOut: number = 500): Promise<void> {
    if (!this.bgmPlayer || this.bgmState !== AudioState.PLAYING) return

    if (fadeOut > 0) {
      await this.fadeVolume(this.bgmPlayer, this.bgmVolume, 0, fadeOut)
    }

    await this.bgmPlayer.stop()
    this.bgmState = AudioState.STOPPED
    this.currentBgm = ''
  }

  // 暂停BGM
  async pauseBgm(): Promise<void> {
    if (!this.bgmPlayer || this.bgmState !== AudioState.PLAYING) return
    await this.bgmPlayer.pause()
    this.bgmState = AudioState.PAUSED
  }

  // 恢复BGM
  async resumeBgm(): Promise<void> {
    if (!this.bgmPlayer || this.bgmState !== AudioState.PAUSED) return
    await this.bgmPlayer.play()
    this.bgmState = AudioState.PLAYING
  }

  // ========== 音效相关 ==========

  // 播放音效
  async playSfx(path: string, volume?: number): Promise<void> {
    if (this.muted) return

    const vol = volume ?? this.sfxVolume

    // 从池中找空闲单元
    const unit = this.sfxPool.find(u => !u.busy)
    if (!unit) {
      // 池满了，找最早播放的覆盖
      const oldest = this.sfxPool[0]
      await oldest.stop()
      await oldest.play(path, vol)
      return
    }

    await unit.play(path, vol)
  }

  // 停止所有音效
  async stopAllSfx(): Promise<void> {
    for (const unit of this.sfxPool) {
      if (unit.busy) {
        await unit.stop()
      }
    }
  }

  // ========== 音量控制 ==========

  // 设置BGM音量
  setBgmVolume(vol: number): void {
    this.bgmVolume = Math.max(0, Math.min(1, vol))
    if (this.bgmPlayer && this.bgmState === AudioState.PLAYING) {
      this.bgmPlayer.setVolume(this.bgmVolume)
    }
  }

  // 设置音效音量
  setSfxVolume(vol: number): void {
    this.sfxVolume = Math.max(0, Math.min(1, vol))
  }

  // 全局静音
  setMuted(muted: boolean): void {
    this.muted = muted
    if (muted) {
      this.pauseBgm()
      this.stopAllSfx()
    } else {
      this.resumeBgm()
    }
  }

  // ========== 工具方法 ==========

  // 音量渐变
  private fadeVolume(
    player: media.AVPlayer,
    from: number,
    to: number,
    duration: number
  ): Promise<void> {
    return new Promise((resolve) => {
      const steps = 20
      const stepTime = duration / steps
      const stepVol = (to - from) / steps
      let current = from
      let count = 0

      const timer = setInterval(() => {
        count++
        current += stepVol
        player.setVolume(Math.max(0, Math.min(1, current)))

        if (count >= steps) {
          clearInterval(timer)
          resolve()
        }
      }, stepTime)
    })
  }

  // 销毁所有资源
  async destroy(): Promise<void> {
    if (this.bgmPlayer) {
      await this.bgmPlayer.release()
      this.bgmPlayer = null
    }
    for (const unit of this.sfxPool) {
      if (unit.player) {
        await unit.player.release()
      }
    }
    this.sfxPool = []
    if (this.voicePlayer) {
      await this.voicePlayer.release()
      this.voicePlayer = null
    }
  }
}

// 全局音频管理器实例
let audioManager: GameAudioManager | null = null

export function getAudioManager(): GameAudioManager {
  if (!audioManager) {
    audioManager = new GameAudioManager()
  }
  return audioManager
}

进阶用法：3D空间音频

3D游戏里，声音得有"空间感"——远小近大、左右方位。

// SpatialAudio.ets - 3D空间音频

// 3D向量
class Vec3 {
  x: number = 0
  y: number = 0
  z: number = 0
  constructor(x: number = 0, y: number = 0, z: number = 0) {
    this.x = x; this.y = y; this.z = z
  }
  sub(v: Vec3): Vec3 { return new Vec3(this.x - v.x, this.y - v.y, this.z - v.z) }
  length(): number { return Math.sqrt(this.x * this.x + this.y * this.y + this.z * this.z) }
  normalize(): Vec3 {
    const len = this.length()
    return len > 0 ? new Vec3(this.x / len, this.y / len, this.z / len) : new Vec3()
  }
  dot(v: Vec3): number { return this.x * v.x + this.y * v.y + this.z * v.z }
}

// 空间音频参数
interface SpatialAudioParams {
  position: Vec3        // 声源位置
  velocity: Vec3        // 声源速度（用于多普勒效应）
  referenceDistance: number  // 参考距离（此距离内音量不衰减）
  maxDistance: number   // 最大可听距离
  rolloffFactor: number // 衰减速率
  innerAngle: number    // 内锥角（度）
  outerAngle: number    // 外锥角（度）
  direction: Vec3       // 声源朝向
}

// 空间音频计算器
class SpatialAudioCalculator {
  private listenerPos: Vec3 = new Vec3(0, 0, 0)
  private listenerDir: Vec3 = new Vec3(0, 0, -1) // 默认朝-Z方向看
  private listenerUp: Vec3 = new Vec3(0, 1, 0)
  private listenerVelocity: Vec3 = new Vec3(0, 0, 0)
  private speedOfSound: number = 343.3 // 音速（米/秒）

  // 设置听者（相机）位置
  setListener(pos: Vec3, dir: Vec3, up: Vec3, velocity: Vec3): void {
    this.listenerPos = pos
    this.listenerDir = dir.normalize()
    this.listenerUp = up.normalize()
    this.listenerVelocity = velocity
  }

  // 计算空间音频参数
  calculate(params: SpatialAudioParams): { volume: number; pan: number; pitch: number } {
    // 计算距离
    const toListener = this.listenerPos.sub(params.position)
    const distance = toListener.length()

    // 1. 距离衰减
    let volume = this.calculateDistanceAttenuation(
      distance, params.referenceDistance, params.maxDistance, params.rolloffFactor
    )

    // 2. 声源方向性（锥形衰减）
    if (params.innerAngle < 360 && params.direction.length() > 0) {
      const dirNorm = params.direction.normalize()
      const toListenerNorm = toListener.normalize()
      const angle = Math.acos(Math.max(-1, Math.min(1, dirNorm.dot(toListenerNorm)))) * 180 / Math.PI

      if (angle > params.outerAngle) {
        volume = 0 // 在锥形范围外，完全静音
      } else if (angle > params.innerAngle) {
        // 在内外锥之间，线性衰减
        const factor = 1 - (angle - params.innerAngle) / (params.outerAngle - params.innerAngle)
        volume *= factor
      }
    }

    // 3. 左右声道平衡（Pan）
    const pan = this.calculatePan(params.position)

    // 4. 多普勒效应（Pitch偏移）
    const pitch = this.calculateDoppler(params.position, params.velocity)

    return { volume, pan, pitch }
  }

  // 距离衰减计算（反距离模型）
  private calculateDistanceAttenuation(
    distance: number,
    refDist: number,
    maxDist: number,
    rolloff: number
  ): number {
    if (distance <= refDist) return 1.0
    if (distance >= maxDist) return 0.0

    const gain = refDist / (refDist + rolloff * (distance - refDist))
    return Math.max(0, Math.min(1, gain))
  }

  // 左右声道平衡
  private calculatePan(sourcePos: Vec3): number {
    const toSource = sourcePos.sub(this.listenerPos).normalize()
    // 计算听者右方向
    const right = new Vec3(
      this.listenerDir.z * this.listenerUp.y - this.listenerDir.y * this.listenerUp.z,
      this.listenerDir.x * this.listenerUp.z - this.listenerDir.z * this.listenerUp.x,
      this.listenerDir.y * this.listenerUp.x - this.listenerDir.x * this.listenerUp.y
    ).normalize()

    // pan值：-1（全左）到 1（全右）
    return Math.max(-1, Math.min(1, toSource.dot(right)))
  }

  // 多普勒效应
  private calculateDoppler(sourcePos: Vec3, sourceVel: Vec3): number {
    const toListener = this.listenerPos.sub(sourcePos).normalize()

    // 声源朝听者方向的速度分量
    const sourceRadialVel = sourceVel.dot(toListener)
    // 听者朝声源方向的速度分量
    const listenerRadialVel = this.listenerVelocity.dot(toListener.scale(-1))

    // 多普勒频率比
    const vls = listenerRadialVel
    const vss = sourceRadialVel
    const pitch = (this.speedOfSound - vls) / (this.speedOfSound - vss)

    return Math.max(0.5, Math.min(2.0, pitch)) // 限制范围
  }
}

完整示例：带音频的游戏场景

把音频管理器和空间音频结合起来，做一个有声音的游戏场景：

// GameAudioDemo.ets - 带音频的游戏场景
import { media } from '@kit.MediaKit'

// 音频事件类型
enum AudioEvent {
  SHOOT = 'shoot',
  EXPLOSION = 'explosion',
  HIT = 'hit',
  PICKUP = 'pickup',
  JUMP = 'jump',
  GAME_OVER = 'game_over'
}

// 音频事件映射表
const AUDIO_MAP: Map<string, string> = new Map([
  [AudioEvent.SHOOT, 'internal://media/shoot.mp3'],
  [AudioEvent.EXPLOSION, 'internal://media/explosion.mp3'],
  [AudioEvent.HIT, 'internal://media/hit.mp3'],
  [AudioEvent.PICKUP, 'internal://media/pickup.mp3'],
  [AudioEvent.JUMP, 'internal://media/jump.mp3'],
  [AudioEvent.GAME_OVER, 'internal://media/gameover.mp3']
])

// 游戏音频控制器
class GameAudioController {
  private audioMgr: GameAudioManager = getAudioManager()
  private spatialCalc: SpatialAudioCalculator = new SpatialAudioCalculator()
  private bgmPlaying: boolean = false

  // 初始化音频
  async init(): Promise<void> {
    // 设置默认音量
    this.audioMgr.setBgmVolume(0.4)
    this.audioMgr.setSfxVolume(0.7)
  }

  // 播放BGM
  async playBgm(scene: string): Promise<void> {
    if (this.bgmPlaying) return

    const bgmMap: Map<string, string> = new Map([
      ['menu', 'internal://media/bgm_menu.mp3'],
      ['battle', 'internal://media/bgm_battle.mp3'],
      ['boss', 'internal://media/bgm_boss.mp3']
    ])

    const path = bgmMap.get(scene)
    if (path) {
      await this.audioMgr.playBgm(path, 1500)
      this.bgmPlaying = true
    }
  }

  // 切换BGM
  async switchBgm(scene: string): Promise<void> {
    await this.audioMgr.stopBgm(800)
    await this.audioMgr.playBgm(
      `internal://media/bgm_${scene}.mp3`,
      1200
    )
  }

  // 播放2D音效（无空间感）
  async playSfx(event: AudioEvent): Promise<void> {
    const path = AUDIO_MAP.get(event)
    if (path) {
      await this.audioMgr.playSfx(path)
    }
  }

  // 播放3D空间音效
  async playSpatialSfx(event: AudioEvent, sourcePos: Vec3, sourceVel?: Vec3): Promise<void> {
    const path = AUDIO_MAP.get(event)
    if (!path) return

    // 计算空间音频参数
    const spatial = this.spatialCalc.calculate({
      position: sourcePos,
      velocity: sourceVel ?? new Vec3(),
      referenceDistance: 5,
      maxDistance: 100,
      rolloffFactor: 1.0,
      innerAngle: 360,
      outerAngle: 360,
      direction: new Vec3()
    })

    // 根据空间参数调整音量和声道
    const adjustedVolume = spatial.volume * 0.8
    await this.audioMgr.playSfx(path, adjustedVolume)

    // 注意：鸿蒙的AVPlayer不直接支持声道平衡（pan）
    // 需要通过AudioRenderer的声道控制来实现
    // 这里简化处理，仅调整音量
  }

  // 更新听者位置（每帧调用）
  updateListener(pos: Vec3, dir: Vec3, velocity: Vec3): void {
    this.spatialCalc.setListener(pos, dir, new Vec3(0, 1, 0), velocity)
  }

  // 暂停所有音频
  async pauseAll(): Promise<void> {
    await this.audioMgr.pauseBgm()
  }

  // 恢复所有音频
  async resumeAll(): Promise<void> {
    await this.audioMgr.resumeBgm()
  }

  // 销毁
  async destroy(): Promise<void> {
    await this.audioMgr.destroy()
  }
}

// 游戏页面中使用
@Entry
@Component
struct GameAudioDemoPage {
  private audioCtrl: GameAudioController = new GameAudioController()
  private settings: RenderingContextSettings = new RenderingContextSettings(true)
  private ctx: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
  private playerX: number = 180
  private playerY: number = 600
  private isTouching: boolean = false
  private shootTimer: number = 0
  private running: boolean = false
  private lastTime: number = 0
  private timer: number = -1

  aboutToAppear(): void {
    this.audioCtrl.init()
    this.running = true
  }

  aboutToDisappear(): void {
    this.running = false
    if (this.timer !== -1) clearTimeout(this.timer)
    this.audioCtrl.destroy()
  }

  build() {
    Column() {
      Canvas(this.ctx)
        .width('100%')
        .height('100%')
        .onReady(() => {
          this.lastTime = Date.now()
          this.audioCtrl.playBgm('battle')
          this.gameLoop()
        })
        .onTouch((event: TouchEvent) => {
          if (event.type === TouchType.Down) {
            this.isTouching = true
          } else if (event.type === TouchType.Up) {
            this.isTouching = false
          }
        })
    }
    .width('100%')
    .height('100%')
  }

  private gameLoop(): void {
    if (!this.running) return

    const now = Date.now()
    const dt = Math.min((now - this.lastTime) / 1000, 0.05)
    this.lastTime = now

    // 射击逻辑
    this.shootTimer -= dt
    if (this.isTouching && this.shootTimer <= 0) {
      this.shootTimer = 0.15
      // 播放射击音效
      this.audioCtrl.playSfx(AudioEvent.SHOOT)
    }

    this.render()

    this.timer = setTimeout(() => this.gameLoop(), 16)
  }

  private render(): void {
    const ctx = this.ctx
    ctx.clearRect(0, 0, 360, 720)
    ctx.fillStyle = '#1a1a2e'
    ctx.fillRect(0, 0, 360, 720)

    ctx.fillStyle = '#ffffff'
    ctx.font = '16px sans-serif'
    ctx.fillText('触摸屏幕射击（带音效）', 10, 30)
    ctx.fillText('BGM正在播放中...', 10, 55)
  }
}

踩坑与注意事项

坑1：AVPlayer初始化延迟

media.createAVPlayer()是异步操作，创建一个AVPlayer需要几十到上百毫秒。你在游戏循环里临时创建播放器来播音效，声音会延迟一拍。所以音效池必须提前初始化好。

坑2：音频文件格式

鸿蒙的AVPlayer支持的格式有限。MP3和WAV是安全的，OGG和FLAC不一定支持。音效推荐用WAV（延迟最低），BGM推荐用MP3（文件小）。别用AAC，有些设备解码延迟大。

坑3：并发播放数限制

鸿蒙上同时活跃的AVPlayer数量有上限（通常8-16个，取决于设备）。你音效池开20个，超过上限的播放器直接报错。音效池大小别超过8，不够用就做优先级覆盖。

坑4：后台音频中断

电话来了、闹钟响了，系统会中断你的音频播放。你需要在on('stateChange')里监听中断事件，保存当前播放状态，中断结束后恢复播放。

坑5：音频文件路径

鸿蒙的音频文件路径不是简单的相对路径。你要用$rawfile()访问resources/rawfile下的文件，或者用fileIo.open()获取文件描述符。直接传文件路径给AVPlayer是不行的。

HarmonyOS 6适配说明

HarmonyOS 6在音频方面有几个重大更新：

1. AudioRenderer低延迟模式：新增了低延迟音频渲染API，专门为游戏音效设计。延迟从原来的100ms+降低到20ms以内，终于可以做到"按键即响"了。

// HarmonyOS 6 低延迟音频渲染
import { audio } from '@kit.AudioKit'

// 创建低延迟音频渲染器
const rendererOptions: audio.AudioRendererOptions = {
  streamInfo: {
    samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000,
    channels: audio.AudioChannel.CHANNEL_2,
    sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
    encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
  },
  rendererInfo: {
    usage: audio.StreamUsage.STREAM_USAGE_GAME, // 游戏音频场景
    rendererFlags: 1 // 低延迟标志
  }
}

const renderer = await audio.createAudioRenderer(rendererOptions)
await renderer.start()

2. 空间音频API：HarmonyOS 6新增了@ohos.multimedia.spatialaudio模块，提供了系统级的空间音频渲染能力。你不需要自己算距离衰减和声道平衡了，设置声源位置，系统自动处理。

3. 音频焦点管理增强：游戏场景的音频焦点优先级提升，不会被通知音、系统提示音轻易打断。

4. 音频预加载：新增prepare()的快速路径，预加载音频数据到内存，播放时直接解码输出，延迟更低。

总结

游戏音频不是"播个mp3"那么简单。BGM要无缝循环、淡入淡出；音效要低延迟、可并发；3D空间音频还要考虑距离和方位。

核心思路就一个：BGM用流式播放+循环，音效用预加载+池化复用。空间音频是锦上添花，2D游戏不需要，3D游戏很有必要。

音频架构要在项目初期就搭好，别等后期再加。音频管理器一旦写好，其他模块只需要调一个playSfx()就完事，不用关心底层怎么播放的。

下一篇讲游戏输入——触控、陀螺仪与手柄适配。游戏好不好玩，输入体验占一半。