A media player engine for Apple platforms.
FFmpeg demuxes. VideoToolbox decodes. AVPlayer handles Dolby Atmos.
Video, live TV with DVR timeshift, or a lean audio-only path with system Now-Playing. You ship the UI.
AetherEngine is a video and audio player engine for iOS, tvOS, macOS and visionOS. It plays almost any file or stream and keeps Apple's own HDR, Dolby Vision and Dolby Atmos handling intact.
- FFmpeg opens the file. VideoToolbox decodes in hardware. AVPlayer presents the picture and passes Dolby Atmos through.
- Formats Apple cannot decode go to the engine's own software decoder (dav1d, libavcodec).
- You get one view and a few
asyncmethods. You build the controls.
- Plays nearly everything: MKV, MP4, WebM, MPEG-TS, AVI, WMV, DVD and Blu-ray ISOs, on-demand MPEG-DASH, and every codec FFmpeg knows. Full list
- HDR done right: HDR10, HDR10+, HLG, and Dolby Vision Profiles 5, 7, 8 and AV1 Profile 10, with the real display switch on Apple TV.
- Dolby Atmos: E-AC-3 Atmos is passed through untouched, to HDMI receivers and to AirPods with spatial audio.
- Lossless height channels from TrueHD and DTS:X as an optional component.
- Subtitles of every kind: text, ASS, PGS, DVB, DVD, teletext, closed captions, external files, and subtitles that survive Picture in Picture and AirPlay.
- Live TV: HLS ingest, DVR timeshift, recording over the same connection, and recovery when a channel breaks.
- Any source: URLs, your own byte reader (
IOReader), and SMB shares. - No UI, no analytics, no surprises. Nothing leaves the device.
Add the package:
.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.62.1")Play a video:
import AetherEngine
import SwiftUI
let player = try AetherEngine()
struct PlayerView: View {
var body: some View { AetherPlayerSurface(engine: player) }
}
try await player.load(url: videoURL)
player.play()Read the state from the published properties (player.$state, player.clock.$currentTime, player.audioTracks, player.$subtitleCues, ...). The host guide walks through everything a real player needs, and Examples/MinimalPlayer is a complete single-file player to copy.
On tvOS, read tvOS host setup before you ship HDR content.
Also available as a searchable site: aetherengine.superuser404.de.
| Document | What is in it |
|---|---|
| Installation | Adding the package, requirements, optional components, versioning |
| Host guide | Building a player: loading, state, tracks, subtitles, live TV, tvOS setup, logging |
| Features | What the engine plays and does, area by area |
| API reference | Every public API, and the contracts your app has to answer |
| Formats | Codecs, containers, HDR, audio, subtitles, discs, known limits, in depth |
| Architecture | How the playback pipelines work, and which file does what |
| Dolby Vision FEL | How Profile 7 FEL is played |
| aetherctl | The command-line tool that runs the real engine on a Mac |
| How it compares | AetherEngine next to AVPlayer, KSPlayer, VLCKit and libmpv, with measurements |
| Licensing | What you need to do to ship the engine and its dependencies |
| Changelog | Every release |
| Min | |
|---|---|
| iOS | 18.0 |
| tvOS | 18.0 |
| macOS | 15.0 |
| visionOS | 1.0 |
| Swift | 6.4 |
| Xcode | 27.0 |
Details on toolchains, CI and older OS versions: Installation › Requirements.
Five components are only built when you turn on their package trait: height channels from TrueHD (TrueHDObjectAudio) and DTS:X (DTSXObjectAudio), the Dolby Vision FEL curve fold (DolbyVisionFelCurves), the FEL dual-layer composer (DualLayerDolbyVision), and Dolby Vision stills (DolbyVisionStillReshaping). They may need third-party patent licences. How to turn them on and which FEL option to choose: Installation › Optional components.
AVPlayer has the best OS integration but plays only Apple's formats. VLCKit and libmpv play everything but bypass Apple's Dolby Vision, Atmos and HDR handling. AetherEngine combines both. Feature table and power, CPU and memory measurements: How it compares.
- Sodalite: native Jellyfin client for Apple TV.
- AetherPlayer: native macOS media player.
- NowSeen: IPTV / Manifest app for tvOS.
- KSKPix: KSKPix is a premium IPTV player for Live TV, Movies & Series.
- Syravo: Xtream Codes, Jellyfin and radio client for iPhone, iPad and Apple TV.
- KIPTV: Premium, cross-platform IPTV Player.
- Silo: native iOS, tvOS and macOS client for the Silo self-hosted media server.
- File Box: File Box is a simple and practical local file manager on iPhone and iPad.
- Moonfin: A multi-platform third party Jellyfin client.
- Snappier IPTV: IPTV App for iOS/iPadOS and tvOS.
- stashy: iOS/tvOS native player for stash.
- Gflix: A flawless media app for your media.
- Melon Video: Video Player for Vision Pro.
- WUW IPTV Player: Watch U Want — or simply WUW — your IPTV player for iPhone, iPad, Mac, Apple TV and Apple Vision Pro.
- GiVo Stream: media player for iPhone, iPad and Apple TV with bring-your-own playlists, live timeshift, DVR and VOD.
- LillyPlayer: The all-in-one IPTV and media player for Apple TV, iPhone and iPad (live TV, EPG, replay, Jellyfin, Plex, SMB...).
- Plozz: Free forever open source native app for iPhone, iPad, and Apple TV. Supports Jellyfin, Plex, Emby, Silo, IPTV, SMB, WebDAV and more.
- Crivid IPTV Player: IPTV player for M3U and Xtream on Apple TV.
- HipTV: A cross-platform, synchronized IPTV player.
- ZeoPlayer: Modern media player for iPhone, iPad, Mac, Apple TV and Apple Vision Pro with HDR, Dolby Vision, spatial audio and SMB support.
- Theamo: IPTV player and TV guide for iPhone, iPad and Apple TV.
- Lume: SwiftUI native open source IPTV and media player for iOS, tvOS and macOS.
- Prowlogue: Native Apple TV client for the Jellyfin media server.
- BoraMin: A native, minimal, iCloud-syncing SMB and HTTP(S) video player for tvOS, iPhone, and Mac.
Shipping something on AetherEngine? Submit it to get listed here and on aetherengine.superuser404.de.
AetherEngine follows Semantic Versioning. Every public declaration in Sources/AetherEngine/ is part of the contract: a major version breaks it, a minor version adds to it, a patch fixes bugs. Details: Installation › Stability and versioning.
LGPL-3.0 with an App Store exception: you can ship the engine in App Store apps, and changes to the engine itself stay LGPL. FFmpeg and the other dependencies keep their own licences. What you need to do: Licensing.
If the engine is useful to you, you can support its development on Ko-fi. Questions and chat: Discord.
AetherEngine is vibe-coded, designed and shipped by Vincent Herbst in close pair-programming with Claude (Anthropic). Nearly every commit carries a Co-Authored-By: Claude trailer.