SwiftAudioEx

Add the following line to your Podfile to install SwiftAudioEx via CocoaPods:

pod 'SwiftAudioEx', '~> 1.0.0'

Add the following line to your Cartfile and follow the standard Carthage framework installation instructions:

github "doublesymmetry/SwiftAudioEx" ~> 1.0.0

Use AudioSessionController to manage the app's audio session category and handle interruptions.

Note: To allow audio to play in the background, you must enable 'Audio, AirPlay, and Picture in Picture' in your app's Background Modes capabilities.

To handle interruptions (e.g., phone calls), implement AudioSessionControllerDelegate and use the handleInterruption(type:) method. You can disable these notifications by setting isObservingForInterruptions = false.

try? AudioSessionController.shared.set(category: .playback)
// ... wait until you actually start playback
try? AudioSessionController.shared.activateSession()

To install SwiftAudioEx using SwiftPM, use Xcode 11 or later. Go to File -> Swift Packages -> Add Package Dependency and enter the repository URL: https://github.com/doublesymmetry/SwiftAudio.git. You can choose to depend on a specific tagged version, branch, or commit.

If you are developing a framework that uses SwiftAudioEx, add it to your Package.swift dependencies:

let package = Package(
    // 0.12.0 ..< 1.0.0
    dependencies: [
        .package(url: "https://github.com/doublesymmetry/SwiftAudio.git", from: "1.0.0")
    ],
    // ...
)

The AudioPlayer is the primary class for playing audio from streams or files. Use DefaultAudioItem to wrap your audio source.

To listen for state changes, subscribe to the event.stateChange listener.

// Basic playback
let player = AudioPlayer()
let audioItem = DefaultAudioItem(audioUrl: "someUrl", sourceType: .stream)
player.load(item: audioItem, playWhenReady: true)

// Subscribing to events
class MyCustomViewController: UIViewController {
    let audioPlayer = AudioPlayer()

    override func viewDidLoad() {
        super.viewDidLoad()
        audioPlayer.event.stateChange.addListener(self, handleAudioPlayerStateChange)
    }

    func handleAudioPlayerStateChange(state: AudioPlayerState) {
        // Handle the event
    }
}

To support remote control (e.g., Lock Screen or Control Center), populate the remoteCommands array on the player.

If you need specific items to have different commands, implement RemoteCommandable in a custom AudioItem subclass. These will override the player's default commands.

To provide custom logic for these commands, override the handlers in the player's RemoteCommandController.

// Enable commands
audioPlayer.remoteCommands = [
    .play,
    .pause,
    .skipForward(intervals: [30]),
    .skipBackward(intervals: [30]),
  ]

// Custom handler
let player = QueuedAudioPlayer()
player.remoteCommandController.handlePlayCommand = { (event) in
    // Handle remote command here.
}

The AudioPlayer can automatically update nowPlayingInfo (artist, title, album, artwork, etc.) if automaticallyUpdateNowPlayingInfo is true (default).

To set additional custom properties, use the nowPlayingInfoController. You can use set(keyValue:) or set(keyValues:) with MediaItemProperty or NowPlayingInfoProperty values.

To manually refresh or clear info:

• loadNowPlayingMetaValues(): Force reload metadata.
• updateNowPlayingPlaybackValues(): Force update playback values.
• nowPlayingInfoController.clear(): Clear current info.

let player = AudioPlayer()
player.load(item: someItem)

// Set custom property
player.nowPlayingInfoController.set(keyValue: NowPlayingInfoProperty.isLiveStream(true))

// Manual updates
player.loadNowPlayingMetaValues()
player.updateNowPlayingPlaybackValues()

// Clear info
player.nowPlayingInfoController.clear()

QueuedAudioPlayer is a subclass of AudioPlayer that maintains a queue of AudioItems. When a track finishes, it automatically loads the next item in the queue.

Navigating the queue

• next(): Increments the queue and loads the next item.
• previous(): Decrements the queue and loads the previous item.
• jumpToItem(atIndex:): Jumps to a specific index and loads that item.

Manipulating the queue

• removeItem(at:): Removes a specific item.
• removeUpcomingItems(): Removes all items in nextItems.

let player = QueuedAudioPlayer()
let audioItem = DefaultAudioItem(audioUrl: "someUrl", sourceType: .stream)
player.add(item: audioItem, playWhenReady: true)

// Navigation
player.next()
player.previous()
player.jumpToItem(atIndex: 2)

// Manipulation
player.removeItem(at: 1)
player.removeUpcomingItems()

You can customize the behavior of an AudioPlayer using several properties:

General Options:

• bufferDuration: Seconds to be buffered.
• timeEventFrequency: Frequency of time progress events.
• automaticallyWaitsToMinimizeStalling: Whether to delay playback to minimize stalling.
• volume: Playback volume.
• isMuted: Mute status.
• rate: Playback rate.
• audioTimePitchAlgorithm: The AVAudioTimePitchAlgorithm used (can be overridden per AudioItem by implementing TimePitching).

QueuedAudioPlayer Options:

• repeatMode: Options are .off, .track, or .queue.