streamyfin/docs/ks-player/GettingStarted.md

Getting Started with KSPlayer

KSPlayer is a powerful media playback framework for iOS, tvOS, macOS, xrOS, and visionOS. It supports both AVPlayer and FFmpeg-based playback with AppKit/UIKit/SwiftUI support.

Requirements

• iOS 13+
• macOS 10.15+
• tvOS 13+
• xrOS 1+

Troubleshooting

Missing Metal Toolchain (CocoaPods builds)

If your build fails compiling Shaders.metal with:

cannot execute tool 'metal' due to missing Metal Toolchain

Install the component:

xcodebuild -downloadComponent MetalToolchain

Then verify:

xcrun --find metal
xcrun metal -v

Installation

Swift Package Manager

Add KSPlayer to your Package.swift:

dependencies: [
    .package(url: "https://github.com/kingslay/KSPlayer.git", .branch("main"))
]

Or in Xcode: File → Add Packages → Enter the repository URL.

CocoaPods

Add to your Podfile:

target 'YourApp' do
    use_frameworks!
    pod 'KSPlayer', :git => 'https://github.com/kingslay/KSPlayer.git', :branch => 'main'
    pod 'DisplayCriteria', :git => 'https://github.com/kingslay/KSPlayer.git', :branch => 'main'
    pod 'FFmpegKit', :git => 'https://github.com/kingslay/FFmpegKit.git', :branch => 'main'
    pod 'Libass', :git => 'https://github.com/kingslay/FFmpegKit.git', :branch => 'main'
end

Then run:

pod install

Initial Setup

Configure Player Type

KSPlayer supports two player backends:

• KSAVPlayer - Uses AVPlayer (default first player)
• KSMEPlayer - Uses FFmpeg for decoding

Configure the player type before creating any player views:

import KSPlayer

// Use KSMEPlayer as the secondary/fallback player
KSOptions.secondPlayerType = KSMEPlayer.self

// Or set KSMEPlayer as the primary player
KSOptions.firstPlayerType = KSMEPlayer.self

Player Type Selection Strategy

The player uses firstPlayerType initially. If playback fails, it automatically switches to secondPlayerType.

// Default configuration
KSOptions.firstPlayerType = KSAVPlayer.self   // Uses AVPlayer first
KSOptions.secondPlayerType = KSMEPlayer.self  // Falls back to FFmpeg

Quick Start

UIKit

import KSPlayer

class VideoViewController: UIViewController {
    private var playerView: IOSVideoPlayerView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        KSOptions.secondPlayerType = KSMEPlayer.self
        
        playerView = IOSVideoPlayerView()
        view.addSubview(playerView)
        
        playerView.translatesAutoresizingMaskIntoConstraints = false
        NSLayoutConstraint.activate([
            playerView.topAnchor.constraint(equalTo: view.topAnchor),
            playerView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            playerView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            playerView.bottomAnchor.constraint(equalTo: view.bottomAnchor),
        ])
        
        let url = URL(string: "https://example.com/video.mp4")!
        playerView.set(url: url, options: KSOptions())
    }
}

SwiftUI (iOS 16+)

import KSPlayer
import SwiftUI

struct VideoPlayerScreen: View {
    let url: URL
    
    var body: some View {
        KSVideoPlayerView(url: url, options: KSOptions())
    }
}

Key Imports

import KSPlayer
import AVFoundation  // For AVMediaType, etc.

Next Steps

• UIKit Usage - Detailed UIKit integration
• SwiftUI Usage - SwiftUI views and modifiers
• KSOptions - Configuration options
• Types and Protocols - Core types reference