API Documentation - MKS2508/MKS-IPTV-App GitHub Wiki
Home > Architecture > API Documentation
Comprehensive API reference for MKS-IPTV-App's core components and public interfaces.
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()
}
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
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
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
}
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
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?
}
isRunning
-
Type:
Bool
- Description: Indicates whether the HTTP server is currently running
serverPort
-
Type:
Int
- Description: The port number the server is listening on
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
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
}
init(content:)
-
Parameters:
content: () -> Content
- ViewBuilder closure for navigation content - Description: Creates a platform-adaptive navigation view
navigationStyle
-
Type:
NavigationStyle
- Description: The navigation style used based on current platform
-
Values:
-
.sidebar
(macOS) -
.splitView
(iPad) -
.tabBar
(iPhone) -
.focus
(tvOS)
-
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 }
}
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 }
}
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 }
}
Represents the current state of media playback.
enum PlaybackState: CaseIterable {
case stopped
case loading
case playing
case paused
case buffering
case error(PlaybackError)
}
Represents the status of a download operation.
enum DownloadStatus: String, CaseIterable {
case pending
case downloading
case paused
case completed
case failed
case cancelled
}
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 }
}
Errors related to stream operations.
enum StreamError: LocalizedError {
case invalidURL
case networkError(Error)
case unsupportedFormat
case authenticationFailed
case serverError(Int)
var errorDescription: String? { get }
}
Errors related to download operations.
enum DownloadError: LocalizedError {
case networkError(Error)
case insufficientStorage
case fileSystemError
case invalidURL
case downloadCancelled
var errorDescription: String? { get }
}
Errors related to the HTTP server.
enum ServerError: LocalizedError {
case portUnavailable
case permissionDenied
case serverStartupFailed
case fileNotFound
var errorDescription: String? { get }
}
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()
}
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()
}
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)")
}
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)")
}
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)")
}
- 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 >}}