william-weng/wwnormalizeaudioplayer

📖 簡介

WWNormalizeAudioPlayer 可用來播放一組音訊檔，並在需要時根據目標分貝值進行音量調整。 它適合用在需要連續播放多段音檔，或希望避免不同來源音檔音量忽大忽小的情境。

✨ 特色

• 支援從 Bundle 以檔名直接播放音檔。
• 支援 URL 陣列播放。
• 支援多段音檔依序播放。
• 支援音量正規化，可指定 targetDB。
• 支援播放進度通知、單曲播放完成通知與錯誤回報。
• 支援暫停、恢復與停止播放。

📦 安裝方式

Swift Package Manager

dependencies: [
    .package(url: "https://github.com/William-Weng/WWNormalizeAudioPlayer.git", .upToNextMajor(from: "1.6.0"))
]

🚀 使用方式

import UIKit
import AVFoundation
import WWNormalizeAudioPlayer

final class ViewController: UIViewController {
    
    private let audioPlayer = WWNormalizeAudioPlayer()
    private let filenames = ["do-re-mi-re-do.m4a", "audio.mp3"]
    private let index = 0
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        Task {
            let audioURLs = filenames.map { URL.documentsDirectory.appendingPathComponent($0) }
            audioPlayer.prepare(audioURLs: audioURLs, delegate: self)
            try await audioPlayer.play(at: index)
        }
    }
}

extension ViewController: WWNormalizeAudioPlayer.Delegate {
    
    func audioPlayer(_ player: WWNormalizeAudioPlayer, prepare tracks: [WWNormalizeAudioPlayer.TrackInformation]) {
        tracks.forEach { print($0) }
    }
    
    func audioPlayer(_ player: WWNormalizeAudioPlayer, isPlaying currentTime: TimeInterval, trackTime: TimeInterval) {
        print("[\(filenames[index])] = \(currentTime) of \(trackTime)")
    }
    
    func audioPlayer(_ player: WWNormalizeAudioPlayer, didFinished callbackType: AVAudioPlayerNodeCompletionCallbackType) {
        print("finished = \(callbackType)")
    }
    
    func audioPlayer(_ player: WWNormalizeAudioPlayer, error: Error) {
        print("error = \(error)")
    }
}

⚙️ 可用參數

| 參數 | 說明 | |---|---| | equalizer | 音訊等化器封裝。 | | volume | 調整播放器音量，範圍為 0.0 ~ 1.0。 | | audioNode | 目前播放音訊所對應的節點，可用於安裝 tap 取得即時音訊資料。 |

🧩 可用方法

| 方法 | 說明 | |---|---| | prepare(audioURLs:delegate:preferredFrameRateRange:options:) | 設定代理與更新頻率，並初始化音訊引擎。 | | play(at:filenames:targetDB:) | 播放音訊檔案列表其中一首。 | | stop() | 停止播放並重置狀態。 | | resume() | 從暫停狀態繼續播放。 | | pause() | 暫停播放並保留目前進度。 |

⚠️ 錯誤類型

| 錯誤 | 說明 | |---|---| | currentTimeUnavailable | 目前時間無法取得。 | | playerNodeNotReady | 播放節點尚未準備好。 | | audioSessionConfigurationFailed | 音訊 Session 設定失敗。 |

📝 WWNormalizeAudioPlayer.Delegate

| 方法 | 說明 | |---|---| | audioPlayer(:prepare:) | 告知代理：播放器即將開始準備指定的音軌。 | | audioPlayer(:isPlaying:currentTime:tracTime:) | 回報目前播放進度。 | | audioPlayer(:didFinished:) | 告知代理：目前音軌已播放完成。 | | audioPlayer(:error:) | 當播放過程中發生錯誤時呼叫。 |

💡 範例

import UIKit
import AVFoundation
import WWNormalizeAudioPlayer

final class ViewController: UIViewController {
    
    private let audioPlayer = WWNormalizeAudioPlayer()
    private let filenames = ["do-re-mi-re-do.m4a", "audio.mp3"]
    private let index = 0
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        Task {
            let audioURLs = filenames.map { URL.documentsDirectory.appendingPathComponent($0) }
            audioPlayer.prepare(audioURLs: audioURLs, delegate: self)
            try await audioPlayer.play(at: index)
        }
    }
}

extension ViewController: WWNormalizeAudioPlayer.Delegate {
    
    func audioPlayer(_ player: WWNormalizeAudioPlayer, prepare tracks: [WWNormalizeAudioPlayer.TrackInformation]) {
        tracks.forEach { print($0) }
    }
    
    func audioPlayer(_ player: WWNormalizeAudioPlayer, isPlaying currentTime: TimeInterval, trackTime: TimeInterval) {
        print("[\(filenames[index])] = \(currentTime) of \(trackTime)")
    }
    
    func audioPlayer(_ player: WWNormalizeAudioPlayer, didFinished callbackType: AVAudioPlayerNodeCompletionCallbackType) {
        print("finished = \(callbackType)")
    }
    
    func audioPlayer(_ player: WWNormalizeAudioPlayer, error: Error) {
        print("error = \(error)")
    }
}

Package Metadata

Repository: william-weng/wwnormalizeaudioplayer

Default branch: main

README: README.md