Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.prism.byescaleira.com/llms.txt

Use this file to discover all available pages before exploring further.

​
PrismVideo

PrismVideo provides an actor-based video downloader with progress streaming, video metadata modeling, and resolution detection — all built on AVFoundation with zero third-party dependencies.

Video Entity

Type-safe metadata model with URL, title, duration, resolution, and thumbnail.

Async Downloader

Actor-isolated download with AsyncStream progress updates and export session management.

Resolution Detection

Automatic resolution classification — 4K, 1080p, 720p, SD — from pixel dimensions.

​
Video Entity

PrismVideoEntity models video metadata:
Video Entity
import PrismVideo

let video = PrismVideoEntity(
    url: URL(string: "https://example.com/video.mp4")!,
    title: "WWDC Keynote 2025",
    duration: 7200,
    resolution: .fullHD,
    type: .mp4,
    thumb: URL(string: "https://example.com/thumb.jpg")
)

print(video.title)          // "WWDC Keynote 2025"
print(video.resolution)     // .fullHD
print(video.duration ?? 0)  // 7200.0

​
Properties

PropertyTypeDescription
idUUIDUnique identifier
urlURLVideo source URL
titleStringDisplay title
durationTimeInterval?Duration in seconds
resolutionPrismVideoResolution?Detected resolution
typeAVFileTypeContainer format (default: .mp4)
thumbURL?Thumbnail image URL

​
Video Resolution

PrismVideoResolution auto-classifies from pixel height:
Resolution Detection
let resolution = PrismVideoResolution(rawValue: 1080)
// .fullHD

let res4k = PrismVideoResolution(rawValue: 2160)
// ._4K
CaseLabelPixel Range
._4K4K2160+
.fullHD1080p HD1080–2159
.HD720p HD720–1079
.SDSD0–719

​
Video Downloader

PrismVideoDownloader is an actor that downloads and exports video with real-time progress via AsyncStream:
Download Video with Progress
let downloader = PrismVideoDownloader(
    video: URL(string: "https://example.com/video.mp4")!,
    with: "keynote",
    for: .mp4
)

for await status in downloader.download() {
    switch status {
    case .downloading(let progress, _):
        print("Progress: \(Int(progress * 100))%")
        
    case .completed(let fileURL):
        print("Downloaded to: \(fileURL)")
        
    case .error(let error):
        print("Failed: \(error.errorDescription ?? "")")
    }
}

​
Download Status

StatusDescription
.downloading(progress:session:)Download in progress — progress is 0.0–1.0, session is the underlying AVAssetExportSession
.completed(URL)Download finished — URL points to the exported file in the temp directory
.error(PrismVideoError)Download failed with a typed error

​
How It Works

  1. Loads the remote AVURLAsset and verifies it’s playable
  2. Extracts video and audio tracks into an AVMutableComposition
  3. Exports using AVAssetExportSession with highest quality preset
  4. Streams progress at 100ms intervals via a Timer publisher
  5. Yields the final file URL on completion
The exported file lands in the system temp directory. Move it to a permanent location if you need to keep it beyond the current session.

​
Video Errors

PrismVideoError conforms to PrismError with descriptions, failure reasons, and recovery suggestions:
ErrorDescriptionRecovery Suggestion
.assetNotPlayableThe AVAsset could not be prepared for playbackTry reloading or verifying the video source
.missingTracksSource file lacks valid video or audio tracksEnsure the file has at least one video or audio track
.failedToCreateExportSessionAVAssetExportSession could not be initializedCheck export configurations or try different parameters
.custom(message:)Custom error with user-provided message—
Error Handling
for await status in downloader.download() {
    if case .error(let error) = status {
        error.log()  // Logs via PrismFoundation's os.Logger
        
        if let suggestion = error.recoverySuggestion {
            print("Try: \(suggestion)")
        }
    }
}