GameSoundEngine

关于

这是一个简单、易于使用的由 Swift 编写的声效引擎，专为 iOS 游戏设计。它支持播放背景音乐和多个同时音效。为了确保音效的多样性，音效可以以随机音调和音量播放，也可以从一组音效中随机播放。

安装

可以使用 CocoaPods 安装 GameSoundEngine 框架。将以下行添加到您的项目 pod 文件中并运行“pod install”。

 pod 'GameSoundEngine', '~> 1.2'

使用 GameSoundEngine

导入框架

所有引用 GameSoundEngine 框架的 Swift 源文件都需要以下导入声明

 import GameSoundEngine

声效引擎初始化

每次应用会话都需要初始化一次声效引擎，以便它可以配置和设置其背景音乐播放器和音效播放器。应在显示任何 UI 之前，在您的 App Delegate 的 didFinishLaunchingWithOptions 方法中执行此操作

 SoundEngine.shared.startEngine()

或者

 SoundEngine.shared.startEngine(numSFXPlayers: 20)

可选的 numSFXPlayers 参数允许您指定由声效引擎配置的音效播放器数量。默认值为 20，对大多数游戏来说应该足够。但如果您的游戏需要同时播放大量声音，您可能需要增加此数字。如果需要增加 numSFXPlayers，声效引擎将在控制台显示以下消息

 All sfx players are busy. Increase numSFXPlayers in startEngine call

在配置音乐和音效播放器之外，startEngine 调用还会使用 AVAudioSession 配置您的应用音频会话。它还会创建事件监听器，以便在收到如电话呼叫或 Siri 等事件时按需暂停和恢复声音。音频会话根据 Apple 为游戏应用提供的音频指南进行了配置，具有以下行为

• 由静音/振动开关和屏幕锁定静音
• 发生音频中断（例如电话呼叫、Siri 等）时暂停所有音频
• 音频中断结束后恢复音频
• 播放音效同时允许其他应用（即音乐应用）的音频播放。
• 当没有其他音频播放时播放背景音乐，否则允许播放之前的音频。

设置整体音量

背景音乐和所有音效的主音量通过SoundEngine对象的两个属性来控制。

 SoundEngine.shared.backgroundMusicVolume = 1.0
    SoundEngine.shared.sfxVolume = 1.0

音量属性的合法值是0.0 - 1.0，其中0.0表示无音量，1.0表示全音量。

背景音乐

可以通过在SoundEngine对象上调用playBackgroundMusic方法来播放背景音乐。

 SoundEngine.shared.playBackgroundMusic("backgroundMusic.m4a", loop: true)

循环参数是可选的，如果没有提供则默认值为true。

要停止背景音乐，请调用stopBackgroundMusic。

 SoundEngine.shared.stopBackgroundMusic(fadeOut: true)

淡出参数是可选的，默认值为true。

请注意，同一时间只能播放一个背景音乐文件。当背景音乐正在播放时调用playBackgroundMusic将会停止当前音乐再开始新背景音乐。

GameSoundEngine还可以从背景音乐文件数组中随机选择播放。

 SoundEngine.shared.playRandomBackgroundMusic(["music1.m4a", "music2.m4a", "music3.m4a"], loop: true)

如果循环参数设置为true，每次循环将会从音乐文件数组中随机选择不同的内容播放。

音效

要播放音效，首先需要创建一个SoundSFX类的实例，并在初始化器中指定音频文件资源的名称。

 let fireworkSound = SoundSFX("fireworkA.caf")

当SoundSFX对象被创建时，其初始化器会从资源文件中预加载音频数据并将其加载到数据缓冲区，以便在播放时使用（预加载是在后台线程上完成的）。当SoundSFX对象超出作用域并被释放时，缓冲区将被释放。这确保了在播放audio时有很低的延迟，因为数据在播放之前已经被加载到内存中。最佳实践是在初始化场景或视图时创建SoundSFX对象，然后在场景被释放且不再需要声音时释放这些对象。

要播放SoundSFX，只需在SoundSFX对象上调用play方法。

 fireworkSound.play()

每个SoundSFX的音量可以通过初始化器中的可选参数来设置。默认值是1.0。

 let fireworkSound = SoundSFX("fireworkA.caf", volume: 1.0)

音效声调多样性

在游戏过程中反复播放的音效可能会对用户产生非常重复的感觉。为了解决这个问题，SoundSFX对象可以被配置为允许音效引擎在每次播放时随机设置不同的音量和音高。这将有助于防止声音过于重复。音量和音高可以随机变化的量通过SoundSFX初始化器中的可选参数来控制。

 let fireworkSound = SoundSFX("fireworkA.caf", volume: 1.0, volumeVary: 2.0, pitchVary: 100.0)

volumeVary的值以分贝（dB）为单位指定。2.0的值表示音量可以从基础音量（在volume参数中指定）随机变化+- 2 dB。pitchVary以百分比单位指定（1音分= 100分贝，1八度= 1200分贝）。100.0的值表示音高可以随机变化+- 100分贝。

框架包含一些预定义的常量，包含volumeVary和pitchVary值的推荐值。这些是好的起点，但可以指定任何值。

 public let kVolumeVaryLow: Float = 1       // 1 db
  public let kVolumeVaryMedium: Float = 2    // 2 db
  public let kVolumeVaryLarge: Float = 3     // 3 db

    public let kPitchVaryLow: Float = 100      // 1 semitone
  public let kPitchVaryMedium: Float = 200   // 2 semitone
  public let kPitchVaryLarge: Float = 300    // 3 semitone

GameSoundEngine还支持随机播放相同音效的不同版本，以增加更多音效变化。例如，如果我有3个不同的烟花音效版本，我可以在每次播放效果时随机选择这三个不同版本中的一个。为了实现这一点，创建一个RandomSoundSFX类的实例，并指定一个SoundSFX对象数组。

    let fireworkSound = RandomSoundSFX([
        SoundSFX("fireworkA.caf", volume: 1.0, volumeVary: kVolumeVaryLarge, pitchVary:kPitchVaryLow),
        SoundSFX("fireworkB.caf", volume: 1.0, volumeVary: kVolumeVaryLarge, pitchVary:kPitchVaryLow),
        SoundSFX("fireworkC.caf", volume: 0.3, volumeVary: kVolumeVaryLarge, pitchVary:kPitchVaryLarge)
    ])

现在每次调用fireworkSound.play()时，音效引擎都将随机播放fireworkA.caf、fireworkB.caf或fireworkC.caf中的一个。请注意，音量和音高也会按照SoundSFX的变音参数随机变化。总体效果创建了大量的音效变化。

将音效播放作为SpriteKit动作执行

框架还包括对SpriteKit SKAction的扩展，使得可以播放SoundSFX对象作为SKAction。这使得同步SoundSFX与SKAction序列和组中的动画更加容易。

 let fireWorkSoundAction = SKAction.playSoundSFX(fireworkSound)

playSoundSFX方法的参数可以是SoundSFX或RandomSoundSFX对象。在动作运行时，音效将会播放。

音文件格式

由于GameSoundEngine框架使用AVAudioEngine，它可以支持Core Audio支持的任何文件格式。然而，以下格式通常被认为是iOS游戏的好格式，因为它们解码效率高，CPU影响低，音质好。

对于背景音乐：MPEG 4音频格式，AAC。要将文件转换为该格式，请使用afconvert控制台命令。

 afconvert -f m4af -d aac input_file

对于音效：CAF格式，线性PCM，小端，16位。要将文件转换为该格式，请使用afconvert控制台命令。

 afconvert -f caff -d LEI16 input_file

为了获得最佳性能，请对所有音效使用相同的文件格式。使用不同格式的音效将需要GameSoundEngine动态重新配置其播放节点以匹配不同的文件格式。如果所有文件都是相同的格式，则不需要重新配置播放节点，从而提供更好的性能。

许可协议

版权所有2016 Endless Wave Software LLC

根据Apache License，版本2.0（“许可”）；除非遵守许可，否则您不得使用此文件。您可以在以下位置获得许可副本：

https://apache.ac.cn/licenses/LICENSE2.0

除非适用法律要求或已书面同意，否则在许可下分发的软件按“现状”分发，不提供任何形式（明示或暗示）的保证或条件。有关许可的具体语言、权限和限制，请参阅许可协议。