API Documentation - MKS2508/MKS-IPTV-App GitHub Wiki

<style> body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; line-height: 1.6; color: #333; max-width: 960px; margin: 0 auto; padding: 20px; } h1, h2, h3, h4, h5, h6 { font-weight: 600; color: #111; } a { color: #0366d6; text-decoration: none; } a:hover { text-decoration: underline; } code { font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace; background-color: #f6f8fa; padding: .2em .4em; margin: 0; font-size: 85%; border-radius: 3px; } pre { background-color: #f6f8fa; padding: 16px; overflow: auto; line-height: 1.45; border-radius: 3px; } pre code { padding: 0; margin: 0; font-size: 100%; background-color: transparent; border: 0; } footer { margin-top: 40px; padding-top: 20px; border-top: 1px solid #eee; font-size: 12px; color: #586069; } </style>

Home > Architecture > API Documentation

📖 API Documentation

Comprehensive API reference for MKS-IPTV-App's core components and public interfaces.


🏗️ Core Architecture Components

StreamManager

The central component for managing IPTV streams and video playback.

@MainActor
class StreamManager: ObservableObject {
    @Published var currentStream: IPTVStream?
    @Published var playbackState: PlaybackState
    @Published var isLoading: Bool
    
    func loadStream(_ url: URL) async throws
    func startPlayback() async
    func pausePlayback()
    func stopPlayback()
}

Methods

loadStream(_:)

  • Parameters: url: URL - The IPTV stream URL to load
  • Returns: Void
  • Throws: StreamError if the URL is invalid or stream cannot be loaded
  • Description: Asynchronously loads and prepares an IPTV stream for playback

startPlayback()

  • Returns: Void
  • Description: Begins playback of the currently loaded stream

pausePlayback()

  • Returns: Void
  • Description: Pauses the current stream playback

stopPlayback()

  • Returns: Void
  • Description: Stops playback and clears the current stream

Published Properties

currentStream

  • Type: IPTVStream?
  • Description: The currently loaded stream, nil if no stream is loaded

playbackState

  • Type: PlaybackState
  • Description: Current state of playback (playing, paused, stopped, buffering)

isLoading

  • Type: Bool
  • Description: Indicates whether a stream is currently being loaded

DownloadManager

Manages download operations with progress tracking and HTTP server integration.

actor DownloadManager {
    @Published var activeDownloads: [Download]
    @Published var completedDownloads: [Download]
    
    func startDownload(for item: DownloadableItem) async throws -> Download
    func pauseDownload(_ downloadId: UUID) async
    func resumeDownload(_ downloadId: UUID) async
    func cancelDownload(_ downloadId: UUID) async
    func deleteDownload(_ downloadId: UUID) async
}

Methods

startDownload(for:)

  • Parameters: item: DownloadableItem - The item to download
  • Returns: Download - The created download instance
  • Throws: DownloadError if download cannot be started
  • Description: Initiates a new download with progress tracking

pauseDownload(_:)

  • Parameters: downloadId: UUID - The ID of the download to pause
  • Returns: Void
  • Description: Pauses an active download

resumeDownload(_:)

  • Parameters: downloadId: UUID - The ID of the download to resume
  • Returns: Void
  • Description: Resumes a paused download

cancelDownload(_:)

  • Parameters: downloadId: UUID - The ID of the download to cancel
  • Returns: Void
  • Description: Cancels an active download and removes temporary files

deleteDownload(_:)

  • Parameters: downloadId: UUID - The ID of the download to delete
  • Returns: Void
  • Description: Deletes a completed download and its files

HTTPStreamServer

Local HTTP server for streaming downloaded content.

actor HTTPStreamServer {
    var isRunning: Bool { get }
    var serverPort: Int { get }
    
    func startServer() async throws
    func stopServer() async
    func serveFile(at path: String) -> URL
    func getStreamingURL(for download: Download) -> URL?
}

Properties

isRunning

  • Type: Bool
  • Description: Indicates whether the HTTP server is currently running

serverPort

  • Type: Int
  • Description: The port number the server is listening on

Methods

startServer()

  • Returns: Void
  • Throws: ServerError if server cannot start
  • Description: Starts the local HTTP server for streaming

stopServer()

  • Returns: Void
  • Description: Stops the HTTP server

serveFile(at:)

  • Parameters: path: String - File path to serve
  • Returns: URL - Local streaming URL for the file
  • Description: Creates a streaming URL for a local file

getStreamingURL(for:)

  • Parameters: download: Download - The download to get streaming URL for
  • Returns: URL? - Streaming URL if available
  • Description: Gets the streaming URL for a downloaded file

PlatformNavigationView

Adaptive navigation component that adjusts based on platform.

struct PlatformNavigationView<Content: View>: View {
    let content: Content
    let navigationStyle: NavigationStyle
    
    init(@ViewBuilder content: () -> Content)
    
    var body: some View
}

Initializers

init(content:)

  • Parameters: content: () -> Content - ViewBuilder closure for navigation content
  • Description: Creates a platform-adaptive navigation view

Properties

navigationStyle

  • Type: NavigationStyle
  • Description: The navigation style used based on current platform
  • Values:
    • .sidebar (macOS)
    • .splitView (iPad)
    • .tabBar (iPhone)
    • .focus (tvOS)

🎯 Data Models

IPTVStream

Represents an IPTV stream with metadata.

struct IPTVStream: Codable, Identifiable {
    let id: UUID
    let name: String
    let url: URL
    let category: StreamCategory
    let logo: URL?
    let epgId: String?
    
    var isLive: Bool { get }
    var quality: StreamQuality { get }
}

Download

Represents a download operation with progress tracking.

struct Download: Identifiable, Codable {
    let id: UUID
    let originalURL: URL
    let localPath: URL
    let title: String
    let thumbnail: URL?
    
    var progress: Double
    var status: DownloadStatus
    var bytesDownloaded: Int64
    var totalBytes: Int64
    var estimatedTimeRemaining: TimeInterval?
    
    var downloadSpeed: Double { get }
    var isCompleted: Bool { get }
}

DownloadableItem

Protocol for items that can be downloaded.

protocol DownloadableItem {
    var id: UUID { get }
    var title: String { get }
    var downloadURL: URL { get }
    var thumbnailURL: URL? { get }
    var estimatedSize: Int64? { get }
}

🔄 Enumerations

PlaybackState

Represents the current state of media playback.

enum PlaybackState: CaseIterable {
    case stopped
    case loading
    case playing
    case paused
    case buffering
    case error(PlaybackError)
}

DownloadStatus

Represents the status of a download operation.

enum DownloadStatus: String, CaseIterable {
    case pending
    case downloading
    case paused
    case completed
    case failed
    case cancelled
}

StreamQuality

Represents stream quality levels.

enum StreamQuality: String, CaseIterable {
    case auto
    case sd480
    case hd720
    case hd1080
    case uhd4k
    
    var displayName: String { get }
    var bitrate: Int? { get }
}

⚠️ Error Types

StreamError

Errors related to stream operations.

enum StreamError: LocalizedError {
    case invalidURL
    case networkError(Error)
    case unsupportedFormat
    case authenticationFailed
    case serverError(Int)
    
    var errorDescription: String? { get }
}

DownloadError

Errors related to download operations.

enum DownloadError: LocalizedError {
    case networkError(Error)
    case insufficientStorage
    case fileSystemError
    case invalidURL
    case downloadCancelled
    
    var errorDescription: String? { get }
}

ServerError

Errors related to the HTTP server.

enum ServerError: LocalizedError {
    case portUnavailable
    case permissionDenied
    case serverStartupFailed
    case fileNotFound
    
    var errorDescription: String? { get }
}

🔧 Configuration

IPTVConfiguration

Central configuration for IPTV services.

struct IPTVConfiguration {
    static let shared = IPTVConfiguration()
    
    let baseURL: URL
    let apiKey: String?
    let userAgent: String
    let timeout: TimeInterval
    let maxConcurrentDownloads: Int
    let defaultQuality: StreamQuality
    
    private init()
}

ServerConfiguration

Configuration for the local HTTP server.

struct ServerConfiguration {
    static let shared = ServerConfiguration()
    
    let defaultPort: Int
    let allowedOrigins: [String]
    let maxConnections: Int
    let bufferSize: Int
    
    private init()
}

🎬 Usage Examples

Starting a Stream

let streamManager = StreamManager()
let streamURL = URL(string: "https://example.com/stream.m3u8")!

do {
    try await streamManager.loadStream(streamURL)
    await streamManager.startPlayback()
} catch {
    print("Failed to start stream: \(error)")
}

Managing Downloads

let downloadManager = DownloadManager()
let item = MovieItem(title: "Example Movie", downloadURL: movieURL)

do {
    let download = try await downloadManager.startDownload(for: item)
    print("Download started: \(download.id)")
} catch {
    print("Failed to start download: \(error)")
}

Using the HTTP Server

let server = HTTPStreamServer()

do {
    try await server.startServer()
    let streamURL = server.getStreamingURL(for: download)
    print("Streaming at: \(streamURL)")
} catch {
    print("Failed to start server: \(error)")
}

📝 Notes

  • All API methods marked with async should be called from an asynchronous context
  • Actor-isolated methods require proper isolation handling
  • Published properties are automatically updated on the main thread
  • Error handling should be implemented for all async operations
  • The HTTP server automatically handles file serving and CORS headers

For more detailed implementation examples, see the Architecture Overview and Development Setup guides.


{{< include _Footer.md >}}

⚠️ **GitHub.com Fallback** ⚠️