william-weng/wwsimplevideoplayerviewui

🎬 簡介

使用 UIKit 的 AVPlayerViewController，直接展示系統內建的播放控制器。
背後使用 AVPlayer 來播放本地或網路影片。
使用 Binding<URL> 與 Binding<Bool> 接收外部影片來源與是否自動播放。
支援在播放過程中更換影片來源，例如切換不同的 .mp4 或 HLS 網址。

📦 安裝方式

Swift Package Manager

swift package add https://github.com/William-Weng/WWSimpleVideoPlayerViewUI.git

或在 Xcode 中：

File → Add Packages → https://github.com/William-Weng/WWSimpleVideoPlayerViewUI.git

✨ 功能

使用 UIKit 播放器整合到 SwiftUI，實作完整自訂播放控制。
支援播放、暫停、拖曳進度條、音量與亮度手勢調整。
可透過 Binding<WWSimpleVideoPlayerDataSource> 即時切換影片來源。
可透過 Binding<Bool> 控制自動播放行為。
支援本地檔案與遠端影片來源。

🧩 可用參數

| 方法 | 說明 | |---|---| | source | 影片來源 URL 的 Binding。 | | isAutoplay | 是否自動播放的 Binding。 | | configure | 進度條的樣式、顏色，以及縮圖擷取步進與縮圖尺寸等相關配置設定。 |

🚀 範例

基本播放

import SwiftUI
import AVFAudio
import WWSimpleVideoPlayerViewUI

struct ContentView: View {
    
    private let configure: WWSimpleVideoPlayerConfigure = .init(thumb: Image("thumb"), mainColor: .mint, thumbnailStep: 5.0, thumbnailSize: .init(width: 240, height: 136))
    
    @State var isAutoplay = true
    @State var source: ShortVideo = .init(url: .documentsDirectory.appendingPathComponent("demo.mp4"))

    var body: some View {
        
        WWSimpleVideoPlayerViewUI<ShortVideo>(source: $source, isAutoplay: $isAutoplay, configure: configure)
            .task {
                setupAudioSession()
            }
            .frame(maxWidth: .infinity)
    }
}

private extension ContentView {
    
    func setupAudioSession() {
        do {
            try AVAudioSession.sharedInstance().setCategory(.playback, mode: .default, options: [])
            try AVAudioSession.sharedInstance().setActive(true)
        } catch {
            print("音訊會話設定失敗: \(error.localizedDescription)")
        }
    }
}

📱 畫中畫 (PiP) 支援度與事前準備

要讓 App 成功啟用畫中畫功能，要完成的專案設定與音訊配置。

Xcode 專案後台權限設定 (Capabilities)

必須手動為 App 開啟後台播放權限，否則系統會強制阻擋畫中畫的運作：

設定路徑：Project Target ➡️ Signing & Capabilities ➡️ 點擊左上角 + Capability ➡️ 搜尋並新增 Background Modes。
勾選項目：在 Background Modes 列表中，務必勾選 Audio, AirPlay, and Picture in Picture。

音訊會話配置 (Audio Session Setup)

在影片播放前或 App 啟動時，必須將系統音訊類別（Audio Session）明確指定為 .playback。
若未配置，系統的畫中畫按鈕將會自動隱藏或呈現灰色無法點擊的狀態。
建議在 App 啟動時（App 的 init），或是播放器 Manager 初始化、準備載入影片 URL 的當下立即呼叫此方法，以確保使用者滑回主畫面時，系統能無縫接軌啟動畫中畫。

/// 將音訊類別設為 .playback（允許 App 在背景或靜音模式下繼續播放聲音）
func setupAudioSession() {
    do {
        try AVAudioSession.sharedInstance().setCategory(.playback, mode: .default, options: [])
        try AVAudioSession.sharedInstance().setActive(true)
        print("🎵 Audio Session 成功設定為 .playback 模式")
    } catch {
        print("❌ 音訊會話設定失敗: \(error.localizedDescription)")
    }
}

Package Metadata

Repository: william-weng/wwsimplevideoplayerviewui

Default branch: main

README: README.md