react-native-alpha-video 0.0.0-stage → 1.0.0

package/ios/Sources/AlphaVideo/AlphaVideoView.mm

@@ -0,0 +1,374 @@
+/**
+ * AlphaVideoView.mm
+ * The player view: source resolving, playback mode, the global decode queue and the Metal view.
+ */
+
+#import "AlphaVideoInternal.h"
+
+#define WEBM_VLOG(...) do { if (self.verbose) NSLog(__VA_ARGS__); } while (0)
+
+#pragma mark - Global Decode Queue
+
+// Serializes preload decoding across all views, so many views spawned at once don't saturate
+// the CPU.
+static dispatch_queue_t _globalDecodeQueue = nil;
+static NSInteger _globalDecodeQueueRefCount = 0;
+static dispatch_semaphore_t _globalDecodeQueueLock = nil;
+
+static dispatch_queue_t getGlobalDecodeQueue(void) {
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        _globalDecodeQueueLock = dispatch_semaphore_create(1);
+    });
+    
+    dispatch_semaphore_wait(_globalDecodeQueueLock, DISPATCH_TIME_FOREVER);
+    if (!_globalDecodeQueue) {
+        _globalDecodeQueue = dispatch_queue_create("dev.mediacache.alphavideo.decode", DISPATCH_QUEUE_SERIAL);
+    }
+    _globalDecodeQueueRefCount++;
+    dispatch_semaphore_signal(_globalDecodeQueueLock);
+    
+    return _globalDecodeQueue;
+}
+
+static void releaseGlobalDecodeQueue(void) {
+    dispatch_semaphore_wait(_globalDecodeQueueLock, DISPATCH_TIME_FOREVER);
+    _globalDecodeQueueRefCount--;
+    if (_globalDecodeQueueRefCount <= 0 && _globalDecodeQueue) {
+        _globalDecodeQueue = nil;
+        _globalDecodeQueueRefCount = 0;
+    }
+    dispatch_semaphore_signal(_globalDecodeQueueLock);
+}
+
+#pragma mark - AlphaVideoView
+
+static const int64_t AlphaVideoDefaultMaxStorageBytes = 512LL * 1024 * 1024;
+
+static void AlphaVideoWarnWithoutAddOn(void) {
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+        NSLog(@"[AlphaVideo] range-source isn't installed (the RangeSource SwiftPM product, the alpha-video pod's "
+              @"Source subspec, or for React Native npm i react-native-range-source): URLs are downloaded whole for "
+              @"each play, without range requests, storage, maxStorageBytes or cacheKey");
+    });
+}
+
+@interface AlphaVideoView () <AlphaVideoPlayerDelegate>
+@end
+
+@implementation AlphaVideoView {
+    // Bumped on every source, so a slow open can't load over a newer source. Main queue only.
+    NSUInteger _sourceGeneration;
+    // The reader of the current source, for URLs and data sources. Main queue only.
+    AlphaVideoSourceReader *_reader;
+    // Loads that read over the network, in order and off the main queue
+    dispatch_queue_t _loadQueue;
+}
+
+- (instancetype)initWithFrame:(CGRect)frame {
+    self = [super initWithFrame:frame];
+    if (self) {
+        [self setup];
+    }
+    return self;
+}
+
+- (instancetype)initWithCoder:(NSCoder *)coder {
+    self = [super initWithCoder:coder];
+    if (self) {
+        [self setup];
+    }
+    return self;
+}
+
+- (void)setup {
+    self.backgroundColor = [UIColor clearColor];
+    
+    _autoPlay = YES;
+    _loop = YES;
+    _paused = NO;
+    _playbackSpeed = 1.0;
+    _mode = @"stream";
+    _streamPrefetchAhead = 8;
+    _useDecodeQueue = YES;
+    _storage = @"auto";
+    _maxStorageBytes = AlphaVideoDefaultMaxStorageBytes;
+    _loadQueue = dispatch_queue_create("dev.mediacache.alphavideo.load", DISPATCH_QUEUE_SERIAL);
+    
+    _metalView = [[AlphaVideoMetalView alloc] initWithFrame:self.bounds config:[AlphaVideoConfig defaultConfig]];
+    _metalView.playerDelegate = self;
+    _metalView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+    _metalView.translatesAutoresizingMaskIntoConstraints = YES;
+    
+    [self addSubview:_metalView];
+}
+
+- (void)layoutSubviews {
+    [super layoutSubviews];
+    self.metalView.frame = self.bounds;
+}
+
+#pragma mark - Properties
+
+- (NSString *)loadedDecoder {
+    return [NSString stringWithFormat:@"software (%@)", self.metalView.player.decoderName];
+}
+
+- (void)setSource:(NSString *)source {
+    if (source == _source || [source isEqualToString:_source]) return;
+    _source = [source copy];
+    [self scheduleLoad];
+}
+
+// What a source is read with: a change reloads it
+- (void)setHeaders:(NSDictionary<NSString *, NSString *> *)headers {
+    if (headers == _headers || [headers isEqualToDictionary:_headers]) return;
+    _headers = [headers copy];
+    if (_source) [self scheduleLoad];
+}
+
+- (void)setDataSource:(NSString *)dataSource {
+    if (dataSource == _dataSource || [dataSource isEqualToString:_dataSource]) return;
+    _dataSource = [dataSource copy];
+    if (_source) [self scheduleLoad];
+}
+
+/** Loads on the next turn, once the other properties set in this turn have been applied. */
+- (void)scheduleLoad {
+    NSUInteger generation = ++_sourceGeneration;
+    __weak AlphaVideoView *weakSelf = self;
+    dispatch_async(dispatch_get_main_queue(), ^{
+        AlphaVideoView *strongSelf = weakSelf;
+        if (strongSelf && generation == strongSelf->_sourceGeneration) [strongSelf loadSource];
+    });
+}
+
+- (void)setStorage:(NSString *)storage {
+    if ([storage isEqualToString:@"disk"] || [storage isEqualToString:@"memory"] || [storage isEqualToString:@"none"]) {
+        _storage = [storage copy];
+    } else {
+        _storage = @"auto";
+    }
+}
+
+- (void)setMaxStorageBytes:(int64_t)maxStorageBytes {
+    _maxStorageBytes = maxStorageBytes > 0 ? maxStorageBytes : AlphaVideoDefaultMaxStorageBytes;
+}
+
+- (void)setAutoPlay:(BOOL)autoPlay {
+    _autoPlay = autoPlay;
+    self.metalView.autoPlay = autoPlay && !_paused;
+}
+
+- (void)setLoop:(BOOL)loop {
+    _loop = loop;
+    self.metalView.loop = loop;
+}
+
+- (void)setPaused:(BOOL)paused {
+    _paused = paused;
+    // A view paused before it loads must not start on load
+    self.metalView.autoPlay = _autoPlay && !paused;
+    if (paused) {
+        [self.metalView pause];
+    } else if (self.autoPlay) {
+        [self.metalView play];
+    }
+}
+
+- (void)setPlaybackSpeed:(double)playbackSpeed {
+    _playbackSpeed = playbackSpeed;
+    self.metalView.playbackSpeed = playbackSpeed;
+}
+
+- (void)setVerbose:(BOOL)verbose {
+    _verbose = verbose;
+    self.metalView.verbose = verbose;
+}
+
+- (void)setMode:(NSString *)mode {
+    if ([mode isEqualToString:@"preload"] || [mode isEqualToString:@"streamAndPreload"]) {
+        _mode = [mode copy];
+    } else {
+        _mode = @"stream";
+    }
+    [self updatePlayerConfig];
+}
+
+- (void)setStreamPrefetchAhead:(int)streamPrefetchAhead {
+    _streamPrefetchAhead = streamPrefetchAhead > 0 ? streamPrefetchAhead : 8;
+    [self updatePlayerConfig];
+}
+
+- (void)updatePlayerConfig {
+    AlphaVideoConfig *config = [self.metalView.player getConfig];
+    config.mode = _mode;
+    config.stream = [_mode isEqualToString:@"stream"];
+    config.streamPrefetchAhead = _streamPrefetchAhead;
+    [self.metalView.player setConfig:config];
+    
+    WEBM_VLOG(@"AlphaVideoView mode: %@, prefetchAhead=%d", _mode, _streamPrefetchAhead);
+}
+
+#pragma mark - Source Loading
+
+- (void)loadSource {
+    NSString *sourceUri = self.source;
+    if (sourceUri.length == 0) return;
+    
+    [self updatePlayerConfig];
+    _reader = nil;
+    
+    WEBM_VLOG(@"AlphaVideoView loading: %@ (mode=%@, useDecodeQueue=%d)", sourceUri, _mode, _useDecodeQueue);
+    
+    BOOL appSource = self.dataSource.length > 0;
+    BOOL remote = [sourceUri hasPrefix:@"https://"] || [sourceUri hasPrefix:@"http://"];
+    if (!appSource && !remote) {
+        NSString *path = AlphaVideoLocalPathForSource(sourceUri);
+        if (!path) {
+            [self playerDidEncounterError:[NSString stringWithFormat:
+                @"Unsupported source '%@'. Use https://, file://, an absolute path or asset://", sourceUri] code:nil];
+        } else if (![[NSFileManager defaultManager] fileExistsAtPath:path]) {
+            [self playerDidEncounterError:[NSString stringWithFormat:@"File not found: %@", sourceUri] code:nil];
+        } else {
+            [self loadWithQueue:^(AlphaVideoView *view) { [view.metalView loadFromPath:path]; } offMain:NO];
+        }
+        return;
+    }
+    
+    if (!AlphaVideoRangeSourcePlugin()) {
+        if (appSource) {
+            [self playerDidEncounterError:[NSString stringWithFormat:
+                @"The data source \"%@\" needs the range-source add-on (the RangeSource SwiftPM product, the "
+                @"alpha-video pod's Source subspec, or for React Native react-native-range-source), which the "
+                @"app doesn't include", self.dataSource]
+                                     code:AlphaVideoErrorNoSourceModule];
+            return;
+        }
+        AlphaVideoWarnWithoutAddOn();
+    }
+
+    NSString *dataSource = appSource ? [self.dataSource copy] : nil;
+    NSURL *url = [NSURL URLWithString:sourceUri];
+    if (!url) {
+        [self playerDidEncounterError:[NSString stringWithFormat:@"Invalid URL: %@", sourceUri] code:nil];
+        return;
+    }
+    NSString *storage = [_storage isEqualToString:@"auto"] ? (appSource ? @"none" : @"disk") : _storage;
+    NSString *key = self.cacheKey.length > 0 ? self.cacheKey : sourceUri;
+    NSDictionary<NSString *, NSString *> *headers = self.headers ?: @{};
+    int64_t maxStorageBytes = _maxStorageBytes;
+    // The stream modes start on the first bytes. Preload decodes the whole clip before showing
+    // anything, and would hold the global decode queue for the whole transfer.
+    BOOL fetchFirst = [_mode isEqualToString:@"preload"];
+    NSUInteger generation = _sourceGeneration;
+    __weak AlphaVideoView *weakSelf = self;
+    dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
+        NSString *error = nil;
+        AlphaVideoSourceReader *reader = [AlphaVideoSourceReader openURL:url
+                                                              dataSource:dataSource
+                                                                 headers:headers
+                                                                 storage:storage
+                                                                     key:key
+                                                         maxStorageBytes:maxStorageBytes
+                                                                   error:&error];
+        if (reader && fetchFirst && ![reader fetchAll:&error]) reader = nil;
+        dispatch_async(dispatch_get_main_queue(), ^{
+            AlphaVideoView *strongSelf = weakSelf;
+            if (!strongSelf || generation != strongSelf->_sourceGeneration) return;
+            if (!reader) {
+                [strongSelf playerDidEncounterError:[NSString stringWithFormat:@"Loading %@ failed: %@", sourceUri, error] code:nil];
+                return;
+            }
+            strongSelf->_reader = reader;
+            [strongSelf loadWithQueue:^(AlphaVideoView *view) { [view.metalView loadFromReader:reader]; } offMain:YES];
+        });
+    });
+}
+
+/**
+ * Preload and streamAndPreload go through the global decode queue when useDecodeQueue is on;
+ * stream mode is light enough to load directly, on the main queue for a local file and on this
+ * view's load queue (`offMain`) for one that reads its header over the network.
+ */
+- (void)loadWithQueue:(void (^)(AlphaVideoView *view))load offMain:(BOOL)offMain {
+    BOOL shouldUseQueue = ![_mode isEqualToString:@"stream"] && _useDecodeQueue;
+    __weak AlphaVideoView *weakSelf = self;
+    
+    if (shouldUseQueue) {
+        WEBM_VLOG(@"Using global decode queue for: %@", self.source);
+        dispatch_queue_t queue = getGlobalDecodeQueue();
+        dispatch_async(queue, ^{
+            AlphaVideoView *strongSelf = weakSelf;
+            // Blocks until decodeAllFrames completes
+            if (strongSelf) load(strongSelf);
+            releaseGlobalDecodeQueue();
+        });
+    } else if (offMain) {
+        dispatch_async(_loadQueue, ^{
+            AlphaVideoView *strongSelf = weakSelf;
+            if (strongSelf) load(strongSelf);
+        });
+    } else {
+        load(self);
+    }
+}
+
+#pragma mark - Playback Control
+
+- (void)play {
+    [self.metalView play];
+}
+
+- (void)pause {
+    [self.metalView pause];
+}
+
+- (void)stop {
+    [self.metalView stop];
+}
+
+- (void)seekToFrame:(int)frame {
+    [self.metalView seekToFrame:frame];
+}
+
+- (void)seekToTime:(double)seconds {
+    [self.metalView seekToTime:seconds];
+}
+
+#pragma mark - AlphaVideoPlayerDelegate
+
+- (void)playerDidLoad:(int)totalFrames width:(int)width height:(int)height {
+    WEBM_VLOG(@"AlphaVideoView loaded: %d frames, %dx%d", totalFrames, width, height);
+    id<AlphaVideoViewDelegate> delegate = self.delegate;
+    if ([delegate respondsToSelector:@selector(alphaVideoView:didLoadFrames:width:height:)]) {
+        [delegate alphaVideoView:self didLoadFrames:totalFrames width:width height:height];
+    }
+}
+
+- (void)playerDidReceiveFrame:(AlphaVideoFrame *)frame {
+    // The Metal view draws the frame
+}
+
+- (void)playerDidEncounterError:(NSString *)error code:(nullable NSString *)code {
+    NSLog(@"AlphaVideoView error: %@", error);
+    id<AlphaVideoViewDelegate> delegate = self.delegate;
+    if ([delegate respondsToSelector:@selector(alphaVideoView:didFailWithError:code:)]) {
+        [delegate alphaVideoView:self didFailWithError:error ?: @"Unknown error" code:code];
+    }
+}
+
+- (void)playerDidEnd {
+    WEBM_VLOG(@"AlphaVideoView ended");
+    id<AlphaVideoViewDelegate> delegate = self.delegate;
+    if ([delegate respondsToSelector:@selector(alphaVideoViewDidEnd:)]) {
+        [delegate alphaVideoViewDidEnd:self];
+    }
+}
+
+- (void)playerPreloadComplete:(int)totalFrames timeMs:(double)timeMs {
+    WEBM_VLOG(@"AlphaVideoView preload complete: %d frames in %.1fms", totalFrames, timeMs);
+}
+
+@end

package/ios/Sources/AlphaVideo/include/AlphaVideo.h

@@ -0,0 +1,303 @@
+/**
+ * AlphaVideo.h
+ * Transparent video for iOS: VP8, VP9 or AV1 WebM with alpha, decoded by the C++ core's codec modules
+ * (libvpx, dav1d) and drawn with Metal. AlphaVideoView is the view to use; the rest is the
+ * lower-level API.
+ */
+
+#import <Foundation/Foundation.h>
+#import <Metal/Metal.h>
+#import <MetalKit/MetalKit.h>
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * The error code when no linked codec module decodes the file: the message names the module to
+ * add (AlphaVideoVPX for VP8 and VP9, AlphaVideoAV1 for AV1).
+ */
+extern NSString *const AlphaVideoErrorNoDecoder;
+
+/**
+ * The error code for a data source without the range-source add-on, which reads them (the
+ * RangeSource SwiftPM product, the alpha-video pod's Source subspec, or for React Native
+ * react-native-range-source).
+ */
+extern NSString *const AlphaVideoErrorNoSourceModule;
+
+/**
+ * The software decoders the player plays with. The codec modules register themselves when the
+ * app links them, nothing to call: SwiftPM products AlphaVideoVPX (libvpx, VP8, VP9) and AlphaVideoAV1
+ * (dav1d, AV1), or pods alpha-video/VPX and alpha-video/AV1.
+ */
+@interface AlphaVideoCodecs : NSObject
+
+/**
+ * Registers another software decoder: `pluginList` is a native AlphaVideoDecoderPluginList
+ * (cpp/AlphaVideoDecoderPlugin.h). Registered decoders come after the modules', which a stream
+ * tries first. NO, with `error`, for a decoder built for another plugin ABI.
+ */
++ (BOOL)registerPluginList:(const void *)pluginList error:(NSError **)error;
+
+/** The registered software decoders, e.g. @[@"libvpx v1.15.2", @"dav1d 1.5.1"]; empty with none. */
+@property (class, nonatomic, readonly) NSArray<NSString *> *softwareDecoders;
+
+@end
+
+/**
+ * Frame data structure for Metal rendering
+ */
+@interface AlphaVideoFrame : NSObject
+
+@property (nonatomic, readonly) NSData *yPlane;
+@property (nonatomic, readonly) NSData *uPlane;
+@property (nonatomic, readonly) NSData *vPlane;
+@property (nonatomic, readonly) NSData *aPlane;
+
+@property (nonatomic, readonly) int width;
+@property (nonatomic, readonly) int height;
+@property (nonatomic, readonly) int frameIndex;
+@property (nonatomic, readonly) double timestamp;
+
+// Raw pointers for direct Metal texture upload (faster than NSData copy)
+@property (nonatomic, readonly) const uint8_t *yPlanePtr;
+@property (nonatomic, readonly) const uint8_t *uPlanePtr;
+@property (nonatomic, readonly) const uint8_t *vPlanePtr;
+@property (nonatomic, readonly) const uint8_t *aPlanePtr;
+
+@property (nonatomic, readonly) int yStride;
+@property (nonatomic, readonly) int uvStride;
+@property (nonatomic, readonly) int aStride;
+
+@end
+
+/**
+ * Player statistics
+ */
+@interface AlphaVideoStats : NSObject
+
+@property (nonatomic, readonly) int64_t framesDecoded;
+@property (nonatomic, readonly) int64_t cacheHits;
+@property (nonatomic, readonly) int64_t cacheMisses;
+@property (nonatomic, readonly) double avgDecodeTimeMs;
+@property (nonatomic, readonly) double cacheHitRate;
+
+@end
+
+/**
+ * Delegate for player events
+ */
+@protocol AlphaVideoPlayerDelegate <NSObject>
+
+@optional
+- (void)playerDidLoad:(int)totalFrames width:(int)width height:(int)height;
+- (void)playerDidReceiveFrame:(AlphaVideoFrame *)frame;
+- (void)playerDidStartPlaying;
+- (void)playerDidPause;
+- (void)playerDidStop;
+- (void)playerDidLoop;
+- (void)playerDidEnd;
+// `code`: AlphaVideoErrorNoDecoder, AlphaVideoErrorNoSourceModule, or nil
+- (void)playerDidEncounterError:(NSString *)error code:(nullable NSString *)code;
+- (void)playerPreloadProgress:(int)loaded total:(int)total;
+- (void)playerPreloadComplete:(int)totalFrames timeMs:(double)timeMs;
+
+@end
+
+/**
+ * Configuration for the player
+ */
+@interface AlphaVideoConfig : NSObject
+
+@property (nonatomic) int decodeThreads;      // Default: 4
+@property (nonatomic) int cacheSize;          // Default: 250
+@property (nonatomic) BOOL preloadAllFrames;  // Default: YES
+@property (nonatomic) BOOL loopPlayback;      // Default: YES
+@property (nonatomic) double playbackSpeed;   // Default: 1.0
+
+// Playback mode: "preload", "stream", or "streamAndPreload"
+// - preload: decode all frames upfront, then play
+// - stream (default): decode on-demand with sliding window cache
+// - streamAndPreload: start playing immediately, cache all frames for smooth looping
+@property (nonatomic, copy) NSString *mode;   // Default: "stream"
+
+// Legacy stream property (deprecated, use mode instead)
+@property (nonatomic) BOOL stream;            // Default: YES
+@property (nonatomic) int streamPrefetchAhead; // Default: 8 (frames decoded ahead; all stream mode keeps)
+
++ (instancetype)defaultConfig;
+
+@end
+
+/**
+ * Main Objective-C++ wrapper for WebMAlphaPlayer C++ core
+ */
+@interface AlphaVideoPlayer : NSObject
+
+@property (nonatomic, weak, nullable) id<AlphaVideoPlayerDelegate> delegate;
+@property (nonatomic, readonly) BOOL isLoaded;
+@property (nonatomic, readonly) BOOL isPlaying;
+@property (nonatomic, readonly) int currentFrame;
+@property (nonatomic, readonly) double currentTime;
+@property (nonatomic, readonly) double duration;
+@property (nonatomic, readonly) int totalFrames;
+@property (nonatomic, readonly) int width;
+@property (nonatomic, readonly) int height;
+@property (nonatomic, readonly) double frameRate;
+// The decoder for the loaded clip: "libvpx", or "dav1d" (AV1)
+@property (nonatomic, readonly) NSString *decoderName;
+
+// Initialization
+- (instancetype)init;
+- (instancetype)initWithConfig:(AlphaVideoConfig *)config;
+
+// Configuration
+- (void)setConfig:(AlphaVideoConfig *)config;
+- (AlphaVideoConfig *)getConfig;
+// C++ core info logging; errors are always logged
+- (void)setVerbose:(BOOL)verbose;
+
+// Loading. AlphaVideoView also plays URLs and data sources, read by range as they play.
+- (BOOL)loadFromFile:(NSString *)path;
+- (BOOL)loadFromData:(NSData *)data;
+- (void)unload;
+
+// Playback
+- (void)play;
+- (void)pause;
+- (void)stop;
+- (void)seekToTime:(double)seconds;
+- (void)seekToFrame:(int)frameIndex;
+
+/**
+ * Changes playback rate live, without moving the playhead.
+ *
+ * Distinct from setting `playbackSpeed` in the config, which only takes effect at load: this
+ * reaches the running playback loop, so a rate swapped on hover applies to the next frame.
+ */
+- (void)setPlaybackSpeed:(double)speed;
+- (double)playbackSpeed;
+
+// Direct frame access (for manual rendering)
+- (nullable AlphaVideoFrame *)getFrame:(int)index;
+- (nullable AlphaVideoFrame *)getCurrentFrame;
+
+// Statistics
+- (AlphaVideoStats *)getStats;
+- (void)resetStats;
+
+// The decoder libraries, e.g. "libvpx v1.14.0, dav1d 1.5.1"
++ (NSString *)libraryVersions;
+
+@end
+
+/**
+ * Metal-based view that uses the C++ player
+ * High-performance GPU-accelerated YUV→RGB conversion
+ */
+@interface AlphaVideoMetalView : MTKView
+
+@property (nonatomic, strong, readonly) AlphaVideoPlayer *player;
+@property (nonatomic, weak, nullable) id<AlphaVideoPlayerDelegate> playerDelegate;
+
+// Source management
+@property (nonatomic, copy, nullable) NSString *sourcePath;
+
+// Playback configuration
+@property (nonatomic) BOOL autoPlay;
+@property (nonatomic) BOOL loop;
+@property (nonatomic) double playbackSpeed;
+
+// Log lifecycle and per-frame events; errors and warnings are always logged
+@property (nonatomic) BOOL verbose;
+
+// Initialization
+- (instancetype)initWithFrame:(CGRect)frame;
+- (instancetype)initWithFrame:(CGRect)frame config:(AlphaVideoConfig *)config;
+
+// Loading
+- (BOOL)loadFromPath:(NSString *)path;
+- (void)unloadVideo;
+
+// Playback control
+- (void)play;
+- (void)pause;
+- (void)stop;
+- (void)seekToFrame:(int)frame;
+- (void)seekToTime:(double)seconds;
+
+// Rendering
+- (void)renderFrame:(AlphaVideoFrame *)frame;
+- (void)renderCurrentFrame;
+
+@end
+
+@class AlphaVideoView;
+
+/** AlphaVideoView events, delivered on the main queue. */
+@protocol AlphaVideoViewDelegate <NSObject>
+@optional
+- (void)alphaVideoView:(AlphaVideoView *)view didLoadFrames:(int)totalFrames width:(int)width height:(int)height;
+// `code`: AlphaVideoErrorNoDecoder, or nil
+- (void)alphaVideoView:(AlphaVideoView *)view didFailWithError:(NSString *)error code:(nullable NSString *)code;
+- (void)alphaVideoViewDidEnd:(AlphaVideoView *)view;
+@end
+
+/**
+ * The player view: resolves a source, loads it in the chosen mode and draws it with Metal.
+ *
+ * `source` takes an https:// or http:// URL (read by range requests as it plays, or without the
+ * range-source add-on downloaded whole),
+ * asset://path inside the app bundle, a file:// URL or an absolute path, or with `dataSource` any
+ * URL that data source reads. A new source loads on the next main-queue turn, so set the other
+ * properties in the same turn and they apply to it.
+ */
+@interface AlphaVideoView : UIView
+
+@property (nonatomic, weak, nullable) id<AlphaVideoViewDelegate> delegate;
+
+@property (nonatomic, copy, nullable) NSString *source;
+// Sent with every request for an http(s) source, and given to a data source
+@property (nonatomic, copy, nullable) NSDictionary<NSString *, NSString *> *headers;
+// Reads the source through the data source registered under this name with range-source's
+// RangeDataSources (the range-source add-on)
+@property (nonatomic, copy, nullable) NSString *dataSource;
+// What the store keeps the source under, instead of its URL (for presigned URLs that change)
+@property (nonatomic, copy, nullable) NSString *cacheKey;
+// Where a URL's or data source's bytes are kept between plays: "disk" (Caches/alpha-video),
+// "memory" (for the app's lifetime) or "none". "auto" (default) is disk for URLs and none for a
+// data source. The store is partial: it keeps what has been played, and a clip held whole plays
+// again offline.
+@property (nonatomic, copy) NSString *storage;
+// The store's cap over every clip in it, least recently played out first. Default: 512 MB
+@property (nonatomic) int64_t maxStorageBytes;
+
+// "stream" (default) decodes a few frames ahead while playing; "preload" decodes every frame
+// before playing; "streamAndPreload" starts like stream and keeps every frame after the first
+// pass. The stream modes play URLs as they arrive; preload fetches the whole file first.
+@property (nonatomic, copy) NSString *mode;
+@property (nonatomic) int streamPrefetchAhead;  // Frames decoded ahead while streaming, all it keeps. Default: 8
+// Preload and streamAndPreload decode one clip at a time across all views. Default: YES
+@property (nonatomic) BOOL useDecodeQueue;
+
+@property (nonatomic) BOOL autoPlay;      // Default: YES
+@property (nonatomic) BOOL loop;          // Default: YES
+@property (nonatomic) BOOL paused;
+@property (nonatomic) double playbackSpeed;  // Default: 1.0, changeable while playing
+// Log lifecycle and per-frame events; errors are always logged
+@property (nonatomic) BOOL verbose;
+
+@property (nonatomic, strong, readonly) AlphaVideoMetalView *metalView;
+// The engine and decoder playing the loaded clip, as Android's onLoad names it: "software (dav1d)"
+@property (nonatomic, readonly) NSString *loadedDecoder;
+
+- (void)play;
+- (void)pause;
+- (void)stop;
+// Both clamp to the clip and keep playing or stay paused; a paused view shows the frame.
+- (void)seekToFrame:(int)frame;
+- (void)seekToTime:(double)seconds;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Sources/AlphaVideoAV1/AlphaVideoAV1Codec.mm

@@ -0,0 +1,16 @@
+/**
+ * AlphaVideoAV1Codec.mm
+ * The av1 codec module (dav1d: AV1, 8- to 12-bit) on iOS. AlphaVideoCodecs finds this class by
+ * name and registers its plugin list.
+ */
+
+#import "AlphaVideoAV1.h"
+#include "Dav1dDecoderPlugin.h"
+
+@implementation AlphaVideoAV1Codec
+
++ (const void *)pluginList {
+    return reinterpret_cast<const void *>(&alpha_video_av1_plugins);
+}
+
+@end