
UPlayer – MPEG-DASH playback using native AVPlayer
UPlayer is a modular streaming pipeline that enables MPEG-DASH playback on iOS by dynamically converting MPD manifests into HLS playlists compatible with AVPlayer.
以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。
UPlayer is a modular streaming pipeline that enables MPEG-DASH playback on iOS by dynamically converting MPD manifests into HLS playlists compatible with AVPlayer.
🎥 Playback
Works with AVPlayer Seamless DASH playback via HLS translation
VOD MPD (static)
Live MPD (dynamic)
SegmentTemplate (duration / timeline)
SegmentBase (SIDX / byte-range)
Multi-representation (adaptive bitrate)
🔄 Live Streaming
MPD polling (minimumUpdatePeriod)
Sliding HLS window generation
Live edge control (stay N segments behind)
Playlist merge strategy for continuity
🖼 Thumbnail Scrubbing
Parses DASH image adaptation sets
Supports tiled JPEG sprites
Efficient caching (sprite + cropped image)
Custom preview rendering for scrub UI
🏗 Architecture
Pipeline is built using Combine processors:
URL ↓ UPlayerMetadataDownloader ↓ UPlayerMPDParser ↓ UPlayerThumbnailDownloader ↓ UPlayerHLSGenerator / UPlayerSegmentBaseHLSGenerator / UPlayerMPDToMP4Resolver (fallback) ↓ UPlayerAVAssetResourceLoader (uplayer://) ↓ AVPlayer
Each processor implements:
protocol UPlayerAssetProcessorProtocol { func process(asset: UPlayerAssetProtocol) -> AnyPublisher<UPlayerAssetProtocol, Error> }
📦 Core Components
🧩 Processors
Processor Purpose
UPlayerMetadataDownloader Downloads MPD or detects media type
UPlayerMPDParser Parses DASH manifest
UPlayerThumbnailDownloader Extracts + downloads thumbnail sprites
UPlayerHLSGenerator Generates HLS (SegmentTemplate)
UPlayerSegmentBaseHLSGenerator Generates byte-range HLS
UPlayerMPDToMP4Resolver Fallback to MP4
🎞 Playback Layer
AVPlayer AVPlayerItem UPlayerAVAssetResourceLoader
uplayer://...
🧠 Live Controller
Handles:
Create player
let player = UPlayer()
Optionally assign a delegate (UPlayerDelegate) to monitor playback activity, and provide a rendering view when using a custom player controller.
player.delegate = self
Play DASH URL
uPlayer.play(url: URL(string: "https://example.com/manifest.mpd")!)
Stop playback
uPlayer.stop()
🖼 Thumbnail Preview Example
if let cue = asset.thumbnailMetadata?.cue(for: scrubTime), let image = asset.thumbnailMetadata?.image(for: cue) { previewImageView.image = image }
📥 Media Download & MP4 Export
UPlayerMediaExporter provides a unified download/export API for processed MPD, native HLS, and MP4 sources.
MPD — uses HLS metadata generated by the UPlayer processing pipeline, downloads the selected fragmented-MP4 video and audio tracks, and muxes them into a regular MP4 file.
HLS — parses HLS playlists, selects the video representation and associated audio rendition, downloads initialization and media fragments, and muxes the tracks into MP4.
MP4 — downloads the source MP4 directly without unnecessary remuxing or transcoding.
G.711 audio — uses UPlayerG711ToAACTranscoder to convert G.711 audio to AAC before the final mux.
Photos — the resulting MP4 can be saved directly to the user's Photos library.
Download Pipeline
MPD ↓ UPlayer processing pipeline ↓ generated HLS ───────────────┐ │ native HLS ──────────────────┼─→ UPlayerMediaExporter │ ↓ │ parse playlists │ ↓ │ select video/audio │ ↓ │ download init + segments │ ↓ │ G.711 → AAC when required │ ↓ │ mux local tracks │ ↓ └────→ output.mp4
MP4 ─→ direct download ───────────→ output.mp4
MPD-specific parsing remains in the processing pipeline. Once an MPD asset has been converted to HLS metadata, the exporter uses the same HLS download path as a native HLS source.
Pass the processed asset returned by UPlayerAssetProcessorsQueue to UPlayerMediaExporter:
func didFinishProcessing( source: any UPlayerAssetProcessorsQueueProtocol, sessionId: UPlayerAssetProcessingID, asset: any UPlayerAssetProtocol ) { Task { let exporter = UPlayerMediaExporter()
exporter.progressHandler = { progress in print("Export: (Int(progress * 100))%") }
do { let outputURL = FileManager.default.temporaryDirectory .appendingPathComponent(UUID().uuidString) .appendingPathExtension("mp4")
let fileURL = try await exporter.export( asset: asset, to: outputURL )
print("Exported:", fileURL) } catch { print("Export failed:", error) } } }
Save Directly to Photos
let exporter = UPlayerMediaExporter()
exporter.progressHandler = { progress in print("Export: (Int(progress * 100))%") }
try await exporter.exportToPhotoLibrary(asset: asset)
Add the Photos permission description to the application Info.plist:
<key>NSPhotoLibraryAddUsageDescription</key> <string>Save downloaded videos to your photo library.</string>
Video Quality Selection
By default, the exporter selects the highest-bandwidth video rendition. Use maximumVideoBandwidth to limit the selected representation:
let exporter = UPlayerMediaExporter() exporter.maximumVideoBandwidth = 4_000_000
HTTP Request Headers
Custom HTTP headers can be supplied for authenticated media:
let exporter = UPlayerMediaExporter()
exporter.requestHeaders = [ "Authorization": "Bearer <token>" ]
let fileURL = try await exporter.export( asset: asset, to: outputURL )
Cancellation
Cancel active downloads and the final export with:
exporter.cancel()
Progress
progressHandler reports normalized progress from 0.0 to 1.0:
exporter.progressHandler = { progress in print("Download: (Int(progress * 100))%") }
HLS Export Support
The segmented export path is designed for fragmented-MP4 HLS, including HLS generated internally from MPD sources.
MPEG-TS HLS without an #EXT-X-MAP initialization segment is not currently remuxed by the exporter.
Compatible AAC audio is passed through without re-encoding. When G.711 audio requires conversion, the exporter uses the existing transcoder:
G.711 fMP4 ↓ UPlayerG711ToAACTranscoder ↓ AAC fMP4 ↓ final MP4 mux
This keeps compatible streams as pass-through and transcodes only audio that requires conversion.
AVPlayer Behavior AVPlayerViewController does NOT guarantee thumbnail preview Use custom UI for scrubbing thumbnails Live Streams Must continuously update playlists Otherwise you get: Playlist File unchanged for longer than 1.5 * target duration Pause Handling
Short pause → keep refreshing MPD Long pause → detach player: player.replaceCurrentItem(with: nil)
✅ SegmentTemplate
✅ SegmentBase
✅ Live MPD
✅ Thumbnail Tracks
UPlayer supports automatic audio transcoding for DASH streams when the original audio codec is not compatible with AVPlayer.
This is critical because iOS AVPlayer supports only a limited set of audio codecs, primarily:
Audio representations are analyzed Codec is normalized (e.g. mp4a.40.02 → mp4a.40.2) If unsupported → transcoding is enabled
Unsupported audio segments are rewritten to a custom scheme:
uplayer://example.com/audio/seg_1.m4s?mode=audio-transcode&codec=ec-3
This allows interception by:
Converts URL → original HTTPS URL Downloads original segment Extracts audio samples (if needed) Transcodes audio → AAC Returns data to AVPlayer
Original segment (m4s/mp4) ↓ (optional) MP4 demux ↓ Audio samples (e.g. G.711 / EC-3) ↓ Decode → PCM ↓ Encode → AAC (LC) ↓ Wrap → ADTS ↓ Return to AVPlayer
- HLS Master Playlist Adjustment
UPlayerHLSGenerator UPlayerSegmentBaseHLSGenerator
detecting unsupported audio rewriting URLs to uplayer://
🔹 Resource Loader UPlayerAVAssetResourceLoader
intercepting custom scheme downloading original media invoking transcoder returning transformed data
🔹 Transcoder UPlayerG711ToAACTranscoder UPlayerAACADTSEncoder
❌ Do NOT include #EXT-X-MAP ✅ Use .aac segments
The codec declared in HLS must match transcoder output:
happens per segment may increase startup latency may require caching
cache transcoded segments reuse decoded PCM when possible
transcoding happens continuously ensure: sliding window HLS playlists segment caching stable timestamps
Codec Action
mp4a.40.2 pass-through
mp4a.40.5 pass-through
mp4a.40.29 pass-through
ec-3 transcode
ac-3 transcode
pcma / pcmu transcode
unknown pass-through
🧠 Summary
UPlayer ensures compatibility by:
Detecting unsupported audio codecs Routing them through a custom pipeline Transcoding to AAC Presenting a clean HLS stream to AVPlayer
No DRM support (CENC) No subtitles yet No native AVPlayer thumbnail rendering Requires custom UI for scrubbing preview
LL-HLS support DRM (FairPlay / Widevine mapping) Subtitle tracks Smart bitrate selection Disk cache for thumbnails & segments
UPlayer is designed to work seamlessly with Apple’s native AVPlayerViewController, allowing you to play MPEG-DASH streams as if they were standard HLS.
Below is a minimal example of integrating UPlayer into a UIViewController:
private let playerViewController = AVPlayerViewController()
override func viewDidLoad() { super.viewDidLoad()
playerViewController.showsPlaybackControls = true playerViewController.allowsPictureInPicturePlayback = true playerViewController.canStartPictureInPictureAutomaticallyFromInline = true
playerViewController.player = player.avPlayer
// Optional custom UI overlays playerViewController.contentOverlayView?.addSubview(customScrubber) playerViewController.contentOverlayView?.addSubview(preview)
addChild(playerViewController) view.addSubview(playerViewController.view) playerViewController.didMove(toParent: self)
playerViewController.view.translatesAutoresizingMaskIntoConstraints = false NSLayoutConstraint.activate([ playerViewController.view.topAnchor.constraint(equalTo: view.topAnchor), playerViewController.view.bottomAnchor.constraint(equalTo: view.bottomAnchor), playerViewController.view.leadingAnchor.constraint(equalTo: view.leadingAnchor), playerViewController.view.trailingAnchor.constraint(equalTo: view.trailingAnchor) ]) }
⚙️ Configure UPlayer Pipeline
// Register audio transcoder (example: G711 → AAC) player.registerAudioTranscoder( UPlayerG711ToAACTranscoder(), forCodec: .g711 )
// Setup processing pipeline player.assetProcessorsQueue = UPlayerAssetProcessorsQueue() player.delegate = self
player.assetProcessorsQueue?.add( processor: UPlayerMetadataDownloader(id: "downloadAssetProcessor") )
player.assetProcessorsQueue?.add( processor: UPlayerMPDParser(id: "mpdParserAssetProcessor") )
player.assetProcessorsQueue?.add( processor: UPlayerThumbnailDownloader(id: "thumbnailDownloaderProcessor") )
player.assetProcessorsQueue?.add( processor: UPlayerSegmentBaseHLSGenerator(id: "hlsSegmentBaseAssetProcessor") )
player.assetProcessorsQueue?.add( processor: UPlayerMPDToMP4Resolver(id: "MPDToMP4ResolverAssetProcessor") )
player.assetProcessorsQueue?.add( processor: UPlayerHLSGenerator(id: "hlsGeneratorAssetProcessor") )
▶️ Start Playback
player.play(url: mpdURL)
That’s it — UPlayer will:
Native playback UI via AVPlayerViewController
Picture-in-Picture support
Custom scrubbing with thumbnail previews
Automatic DASH compatibility layer
Audio transcoding (e.g., G711 → AAC)
💡 Tip
You can attach custom UI (scrubber, preview thumbnails) using:
playerViewController.contentOverlayView
This allows building advanced playback experiences without replacing the native player.
MPEG-DASH, HLS, AVPlayer, iOS video player, DASH to HLS, adaptive streaming, Swift media player, video streaming engine, AVFoundation, SegmentTemplate, SegmentBase, SIDX, live streaming, audio transcoding
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。