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

package/cpp/AlphaDemuxer.h

@@ -0,0 +1,123 @@
+#pragma once
+
+#include <cstdint>
+#include <memory>
+#include <vector>
+
+namespace webm {
+
+class ByteSource;
+
+/**
+ * Reads an alpha WebM's colour and alpha bitstreams as packets, without decoding them, for
+ * decoders that take one bitstream each: the core's libvpx and dav1d decoders, MediaCodec, and on
+ * the web WebCodecs and the software decoders in Workers.
+ *
+ * The colour stream is the first VP8, VP9 or AV1 track. The alpha stream is the second, or, for a
+ * single VP8 or VP9 track, the stream in each block's BlockAdditional (ID 1), which is how libvpx
+ * writes a standard `yuva420p` WebM.
+ *
+ * Built on libwebm's webm_parser. Android, iOS and the web (compiled to WebAssembly) all use it;
+ * tests/core/demuxer_compare checks it against FFmpeg's reading of each file.
+ */
+class AlphaDemuxer {
+public:
+    enum Codec { VP8 = 0, VP9 = 1, AV1 = 2 };
+
+    /** Colour numbers are H.273's, as in YuvToRgb.h (and FFmpeg's AVColor* enums). */
+    struct StreamInfo {
+        Codec codec = VP9;
+        int profile = 0;   // From the bitstream
+        int bitDepth = 8;
+        int colorRange = 0;  // ColorRange
+        int colorSpace = 2;  // ColorMatrix (2 = unspecified)
+        int colorPrimaries = 2;
+        int colorTrc = 2;
+        std::vector<uint8_t> codecPrivate;  // Matroska CodecPrivate: av1C for AV1, empty for VP8 and VP9
+    };
+
+    struct Info {
+        int width = 0;
+        int height = 0;
+        int totalFrames = 0;
+        double frameRate = 30.0;
+        int64_t durationUs = 0;
+        int64_t startUs = 0;  // The first colour packet's ptsUs
+        bool hasAlpha = false;
+        bool alphaInBlockAdditional = false;
+        StreamInfo color;
+        StreamInfo alpha;  // Valid when hasAlpha
+    };
+
+    struct Packet {
+        int stream = 0;  // 0 colour, 1 alpha
+        const uint8_t* data = nullptr;  // Valid until the next read, seek or destruction
+        int size = 0;
+        int64_t ptsUs = 0;
+        int frameIndex = 0;
+        bool key = false;
+    };
+
+    enum class Progress { kDone, kPending, kFailed };
+
+    /** Opens `source` as a WebM. Returns null if it can't be read or has no VP8, VP9 or AV1 track. */
+    static std::unique_ptr<AlphaDemuxer> open(std::unique_ptr<ByteSource> source);
+
+    /**
+     * A demuxer for a source that may answer ByteSource::kPending, not yet open: call tryOpen()
+     * until it no longer returns kPending. Null if `source` is.
+     */
+    static std::unique_ptr<AlphaDemuxer> create(std::unique_ptr<ByteSource> source);
+
+    /**
+     * Reads the headers and the first packets. kPending: the source didn't have the bytes yet;
+     * call again once it has. kFailed: not a WebM with a VP8, VP9 or AV1 track, or unreadable.
+     * info() is valid once it returns kDone.
+     */
+    Progress tryOpen();
+
+    /**
+     * The colour and alpha bitstreams of `source`, as (codec, profile) pairs, colour first: two
+     * pairs for an alpha WebM, fewer otherwise.
+     */
+    static std::vector<int> colorAlphaTracks(std::unique_ptr<ByteSource> source);
+
+    ~AlphaDemuxer();
+    AlphaDemuxer(const AlphaDemuxer&) = delete;
+    AlphaDemuxer& operator=(const AlphaDemuxer&) = delete;
+
+    const Info& info() const;
+
+    /** The next colour or alpha packet; false at the end of the file or when reading fails. */
+    bool readPacket(Packet* out);
+
+    /** Whether the last readPacket() returned false because reading failed (an I/O error, a
+     *  failed or aborted download), rather than at the end of the file. */
+    bool failed() const;
+
+    /**
+     * Whether the last readPacket() or seekToTimeUs() stopped because the source answered
+     * ByteSource::kPending. Call it again once the bytes are there: a read carries on where it
+     * stopped, and a seek starts over (seeking elsewhere instead is fine too).
+     */
+    bool pending() const;
+
+    /** Back to the first packet, with frameIndex counting from 0 again. */
+    void seekToStart();
+    /** To the keyframe at or before `timeUs`, in the timebase of the packets' ptsUs. Keeps the
+     *  frameIndex counters going. May read the Cues, or scan for keyframes, so may be pending(). */
+    void seekToTimeUs(int64_t timeUs);
+
+private:
+    class Impl;
+    explicit AlphaDemuxer(std::unique_ptr<Impl> impl);
+    std::unique_ptr<Impl> impl_;
+};
+
+/** Whether a VP9 frame (or superframe) starts with a keyframe, from its uncompressed header. */
+bool isVp9Keyframe(const uint8_t* data, int size);
+
+/** Whether a VP8 frame is a keyframe, from its frame tag. */
+bool isVp8Keyframe(const uint8_t* data, int size);
+
+} // namespace webm

package/cpp/AlphaVideoDecoderPlugin.h

@@ -0,0 +1,84 @@
+/*
+ * The interface between the player's core and a software decoder: libvpx in the vpx codec module,
+ * dav1d in the av1 module, or a third party's. A module provides a list of plugins, one per codec,
+ * and the app (or the platform's discovery) registers them with the core.
+ *
+ * C, not C++: on Android each module is its own .so with its own static libc++, and on iOS a
+ * module may be built apart from the core. A plugin built for another ABI is refused.
+ */
+#ifndef ALPHA_VIDEO_DECODER_PLUGIN_H
+#define ALPHA_VIDEO_DECODER_PLUGIN_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define ALPHA_VIDEO_DECODER_ABI 1
+
+/* AlphaDemuxer::Codec */
+#define ALPHA_VIDEO_CODEC_VP8 0
+#define ALPHA_VIDEO_CODEC_VP9 1
+#define ALPHA_VIDEO_CODEC_AV1 2
+
+/* A bitstream to decode, as the demuxer read it. Colour numbers are H.273's. */
+typedef struct AlphaVideoStreamInfo {
+    int codec;
+    int profile;
+    int bitDepth;
+    int width;
+    int height;
+    const uint8_t* codecPrivate; /* Matroska CodecPrivate (av1C for AV1); may be null */
+    size_t codecPrivateSize;
+} AlphaVideoStreamInfo;
+
+/* A decoded frame, in the decoder's own buffers: valid until its next call. */
+typedef struct AlphaVideoPicture {
+    const uint8_t* planes[3]; /* Y, U, V; G, B, R when rgb. U and V null when monochrome. */
+    int strides[3];
+    int width;
+    int height;
+    int chromaShiftX; /* 4:2:0 is 1, 1; 4:2:2 is 1, 0; 4:4:4 is 0, 0 */
+    int chromaShiftY;
+    int bitDepth;     /* Deeper samples are 16 bits each */
+    int colorRange;   /* 1 limited, 2 full */
+    int rgb;
+    int monochrome;
+    int64_t ptsUs;
+} AlphaVideoPicture;
+
+/*
+ * One codec's decoder. Each decoder `open` returns is used from one thread at a time. send() a
+ * packet, then receive() until it returns 0. Frames come out in order, perhaps some packets late;
+ * drain() at the end of the stream lets receive() return the frames still held.
+ */
+typedef struct AlphaVideoDecoderPlugin {
+    uint32_t abi;        /* ALPHA_VIDEO_DECODER_ABI */
+    uint32_t structSize; /* sizeof(AlphaVideoDecoderPlugin) */
+    const char* name;    /* "libvpx" */
+    const char* version; /* "v1.14.0" */
+    int codec;           /* ALPHA_VIDEO_CODEC_* */
+    /* 1 if it decodes this stream (libvpx here: 8-bit only) */
+    int (*supports)(const AlphaVideoStreamInfo* stream);
+    /* Null, with a message in `error`, if it can't open. threads: 0 for the decoder's choice. */
+    void* (*open)(const AlphaVideoStreamInfo* stream, int threads, char* error, size_t errorSize);
+    /* 0 if the packet can't be decoded */
+    int (*send)(void* decoder, const uint8_t* data, int size, int64_t ptsUs);
+    /* 1 with a frame in `out`, 0 when none is ready */
+    int (*receive)(void* decoder, AlphaVideoPicture* out);
+    void (*drain)(void* decoder);
+    /* Drops the frames held and in progress, for a seek */
+    void (*flush)(void* decoder);
+    void (*close)(void* decoder);
+} AlphaVideoDecoderPlugin;
+
+/* A codec module's entry point: its plugins, `*count` of them, valid for the process's life. */
+typedef const AlphaVideoDecoderPlugin* const* (*AlphaVideoDecoderPluginList)(int* count);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

package/cpp/Av1SequenceHeader.cpp

@@ -0,0 +1,175 @@
+#include "Av1SequenceHeader.h"
+
+namespace {
+
+const int kObuSequenceHeader = 1;
+
+// Reads bits most significant first; past the end it reads zeros and sets `overrun`.
+struct Bits {
+    const uint8_t* data;
+    size_t size;
+    size_t pos = 0;  // in bits
+    bool overrun = false;
+
+    uint32_t f(int n) {
+        uint32_t v = 0;
+        for (; n > 0; n--, pos++) {
+            int bit = 0;
+            if (pos < size * 8) {
+                bit = (data[pos >> 3] >> (7 - (pos & 7))) & 1;
+            } else {
+                overrun = true;
+            }
+            v = (v << 1) | static_cast<uint32_t>(bit);
+        }
+        return v;
+    }
+
+    bool flag() { return f(1) != 0; }
+
+    // uvlc() (4.10.3)
+    void skipUvlc() {
+        int leadingZeros = 0;
+        while (!flag() && !overrun) leadingZeros++;
+        if (leadingZeros < 32) f(leadingZeros);
+    }
+};
+
+// leb128() (4.10.5); false if it runs past `end` or over 8 bytes
+bool readLeb128(const uint8_t*& p, const uint8_t* end, uint64_t* value) {
+    *value = 0;
+    for (int i = 0; i < 8; i++) {
+        if (p >= end) return false;
+        const uint8_t byte = *p++;
+        *value |= static_cast<uint64_t>(byte & 0x7f) << (i * 7);
+        if (!(byte & 0x80)) return true;
+    }
+    return false;
+}
+
+// color_config() (5.5.2)
+void readColorConfig(Bits& b, Av1SequenceHeader* out) {
+    const bool highBitdepth = b.flag();
+    if (out->profile == 2 && highBitdepth) {
+        out->bitDepth = b.flag() ? 12 : 10;
+    } else {
+        out->bitDepth = highBitdepth ? 10 : 8;
+    }
+    out->monochrome = out->profile == 1 ? false : b.flag();
+    if (b.flag()) {  // color_description_present_flag
+        out->colorPrimaries = static_cast<int>(b.f(8));
+        out->transferCharacteristics = static_cast<int>(b.f(8));
+        out->matrixCoefficients = static_cast<int>(b.f(8));
+    }
+    if (out->monochrome) {
+        out->fullRange = b.flag();
+        out->subsamplingX = out->subsamplingY = 1;
+        return;
+    }
+    // sRGB: BT.709 primaries, the sRGB transfer, the identity matrix
+    if (out->colorPrimaries == 1 && out->transferCharacteristics == 13 && out->matrixCoefficients == 0) {
+        out->fullRange = true;
+        out->subsamplingX = out->subsamplingY = 0;
+    } else {
+        out->fullRange = b.flag();
+        if (out->profile == 0) {
+            out->subsamplingX = out->subsamplingY = 1;
+        } else if (out->profile == 1) {
+            out->subsamplingX = out->subsamplingY = 0;
+        } else if (out->bitDepth == 12) {
+            out->subsamplingX = static_cast<int>(b.f(1));
+            out->subsamplingY = out->subsamplingX ? static_cast<int>(b.f(1)) : 0;
+        } else {
+            out->subsamplingX = 1;
+            out->subsamplingY = 0;
+        }
+        if (out->subsamplingX && out->subsamplingY) b.f(2);  // chroma_sample_position
+    }
+    b.f(1);  // separate_uv_delta_q
+}
+
+// sequence_header_obu() (5.5.1)
+bool readSequenceHeader(Bits& b, Av1SequenceHeader* out) {
+    *out = Av1SequenceHeader();
+    out->profile = static_cast<int>(b.f(3));
+    if (out->profile > 2) return false;
+    const bool stillPicture = b.flag();
+    const bool reducedStillPictureHeader = b.flag();
+    if (reducedStillPictureHeader && !stillPicture) return false;
+    if (reducedStillPictureHeader) {
+        b.f(5);  // seq_level_idx[0]
+    } else {
+        bool decoderModelInfoPresent = false;
+        int bufferDelayLength = 0;
+        if (b.flag()) {  // timing_info_present_flag
+            b.f(32);     // num_units_in_display_tick
+            b.f(32);     // time_scale
+            if (b.flag()) b.skipUvlc();  // equal_picture_interval, num_ticks_per_picture_minus_1
+            decoderModelInfoPresent = b.flag();
+            if (decoderModelInfoPresent) {
+                bufferDelayLength = static_cast<int>(b.f(5)) + 1;
+                b.f(32);  // num_units_in_decoding_tick
+                b.f(5);   // buffer_removal_time_length_minus_1
+                b.f(5);   // frame_presentation_time_length_minus_1
+            }
+        }
+        const bool initialDisplayDelayPresent = b.flag();
+        const int operatingPoints = static_cast<int>(b.f(5)) + 1;
+        for (int i = 0; i < operatingPoints; i++) {
+            b.f(12);  // operating_point_idc
+            if (b.f(5) > 7) b.f(1);  // seq_level_idx, seq_tier
+            if (decoderModelInfoPresent && b.flag()) {
+                b.f(bufferDelayLength);  // decoder_buffer_delay
+                b.f(bufferDelayLength);  // encoder_buffer_delay
+                b.f(1);                  // low_delay_mode_flag
+            }
+            if (initialDisplayDelayPresent && b.flag()) b.f(4);  // initial_display_delay_minus_1
+        }
+    }
+    const int widthBits = static_cast<int>(b.f(4)) + 1;
+    const int heightBits = static_cast<int>(b.f(4)) + 1;
+    out->maxWidth = static_cast<int>(b.f(widthBits)) + 1;
+    out->maxHeight = static_cast<int>(b.f(heightBits)) + 1;
+    if (!reducedStillPictureHeader && b.flag()) b.f(7);  // frame_id_numbers_present_flag, its lengths
+    b.f(3);  // use_128x128_superblock, enable_filter_intra, enable_intra_edge_filter
+    if (!reducedStillPictureHeader) {
+        b.f(4);  // enable_interintra_compound, enable_masked_compound, enable_warped_motion, enable_dual_filter
+        const bool enableOrderHint = b.flag();
+        if (enableOrderHint) b.f(2);  // enable_jnt_comp, enable_ref_frame_mvs
+        int forceScreenContentTools = 2;  // SELECT_SCREEN_CONTENT_TOOLS
+        if (!b.flag()) forceScreenContentTools = static_cast<int>(b.f(1));
+        if (forceScreenContentTools > 0 && !b.flag()) b.f(1);  // seq_choose_integer_mv, seq_force_integer_mv
+        if (enableOrderHint) b.f(3);  // order_hint_bits_minus_1
+    }
+    b.f(3);  // enable_superres, enable_cdef, enable_restoration
+    readColorConfig(b, out);
+    b.f(1);  // film_grain_params_present
+    return !b.overrun;
+}
+
+} // namespace
+
+bool parseAv1SequenceHeader(const uint8_t* data, size_t size, Av1SequenceHeader* out) {
+    if (!data || !out) return false;
+    const uint8_t* p = data;
+    const uint8_t* const end = data + size;
+    while (p < end) {
+        // obu_header() (5.3.2)
+        const uint8_t header = *p++;
+        if (header & 0x80) return false;  // obu_forbidden_bit
+        const int type = (header >> 3) & 0xf;
+        const bool hasExtension = header & 0x04;
+        const bool hasSizeField = header & 0x02;
+        if (hasExtension && p++ >= end) return false;
+        uint64_t obuSize = static_cast<uint64_t>(end - p);
+        if (hasSizeField && (!readLeb128(p, end, &obuSize) || obuSize > static_cast<uint64_t>(end - p))) {
+            return false;
+        }
+        if (type == kObuSequenceHeader) {
+            Bits bits{p, static_cast<size_t>(obuSize)};
+            return readSequenceHeader(bits, out);
+        }
+        p += obuSize;
+    }
+    return false;
+}

package/cpp/Av1SequenceHeader.h

@@ -0,0 +1,25 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+// What the core reads from an AV1 sequence header (AV1 spec 5.5), so that the demuxer and the
+// MediaCodec path know a track's format without an AV1 decoder linked in. The fields and their
+// defaults are dav1d_parse_sequence_header's.
+struct Av1SequenceHeader {
+    int profile = 0;
+    int bitDepth = 8;
+    bool monochrome = false;
+    int subsamplingX = 1;
+    int subsamplingY = 1;
+    int colorPrimaries = 2;           // 2: unspecified
+    int transferCharacteristics = 2;
+    int matrixCoefficients = 2;
+    bool fullRange = false;
+    int maxWidth = 0;
+    int maxHeight = 0;
+};
+
+// Parses the first sequence header OBU in `data`, a run of OBUs (av1C's configOBUs, or a packet).
+// False when there is none, or it is cut short or invalid.
+bool parseAv1SequenceHeader(const uint8_t* data, size_t size, Av1SequenceHeader* out);

package/cpp/ByteSource.cpp

@@ -0,0 +1,116 @@
+#include "ByteSource.h"
+
+
+#include <algorithm>
+#include <cerrno>
+#include <cstring>
+#include <fcntl.h>
+#include <sys/stat.h>
+#include <unistd.h>
+#include <vector>
+
+namespace webm {
+
+namespace {
+
+class FileRangeSource : public ByteSource {
+public:
+    // Takes ownership of fd
+    FileRangeSource(int fd, int64_t offset, int64_t length) : fd_(fd), offset_(offset), length_(length) {}
+
+    ~FileRangeSource() override { close(fd_); }
+
+    int64_t read(int64_t pos, uint8_t* out, int64_t size) override {
+        const int64_t remaining = length_ - pos;
+        if (remaining <= 0 || size <= 0) return 0;
+
+        const size_t toRead = static_cast<size_t>(std::min(size, remaining));
+        ssize_t n;
+        do {
+            n = pread(fd_, out, toRead, offset_ + pos);
+        } while (n < 0 && errno == EINTR);
+        return n < 0 ? -1 : n;
+    }
+
+    int64_t size() const override { return length_; }
+
+private:
+    const int fd_;
+    const int64_t offset_;
+    const int64_t length_;
+};
+
+class ReaderSource : public ByteSource {
+public:
+    ReaderSource(std::shared_ptr<SourceReader> reader, const AbortFlag* abort)
+        : reader_(std::move(reader)), abort_(abort) {}
+
+    int64_t read(int64_t pos, uint8_t* out, int64_t size) override { return reader_->read(pos, out, size, abort_); }
+
+    int64_t size() const override { return reader_->size(); }
+
+private:
+    const std::shared_ptr<SourceReader> reader_;
+    const AbortFlag* const abort_;
+};
+
+class MemorySource : public ByteSource {
+public:
+    MemorySource(const uint8_t* data, size_t size) : bytes_(data, data + size) {}
+
+    int64_t read(int64_t pos, uint8_t* out, int64_t size) override {
+        const int64_t remaining = static_cast<int64_t>(bytes_.size()) - pos;
+        if (pos < 0 || remaining <= 0 || size <= 0) return 0;
+        const int64_t n = std::min(size, remaining);
+        std::memcpy(out, bytes_.data() + pos, static_cast<size_t>(n));
+        return n;
+    }
+
+    int64_t size() const override { return static_cast<int64_t>(bytes_.size()); }
+
+private:
+    const std::vector<uint8_t> bytes_;
+};
+
+int openReadOnly(const std::string& path) {
+    int fd;
+    do {
+        fd = open(path.c_str(), O_RDONLY | O_CLOEXEC);
+    } while (fd < 0 && errno == EINTR);
+    return fd;
+}
+
+} // namespace
+
+std::unique_ptr<ByteSource> openFileRange(int fd, int64_t offset, int64_t length) {
+    if (fd < 0 || offset < 0) return nullptr;
+
+    if (length < 0) {
+        struct stat st;
+        if (fstat(fd, &st) != 0 || st.st_size < offset) return nullptr;
+        length = st.st_size - offset;
+    }
+
+    int ownFd = dup(fd);
+    if (ownFd < 0) return nullptr;
+    return std::make_unique<FileRangeSource>(ownFd, offset, length);
+}
+
+std::unique_ptr<ByteSource> openFile(const std::string& path) {
+    int fd = openReadOnly(path);
+    if (fd < 0) return nullptr;
+    std::unique_ptr<ByteSource> source = openFileRange(fd, 0, -1);
+    close(fd);
+    return source;
+}
+
+std::unique_ptr<ByteSource> openReader(std::shared_ptr<SourceReader> reader, const AbortFlag* abort) {
+    if (!reader) return nullptr;
+    return std::make_unique<ReaderSource>(std::move(reader), abort);
+}
+
+std::unique_ptr<ByteSource> openMemory(const uint8_t* data, size_t size) {
+    return std::make_unique<MemorySource>(data, size);
+}
+
+} // namespace webm

package/cpp/ByteSource.h

@@ -0,0 +1,59 @@
+#pragma once
+
+#include "RangeSourceClient.h"
+
+#include <cstdint>
+#include <memory>
+#include <string>
+
+namespace webm {
+
+/**
+ * The bytes of a video, read at any position: a file, a range of one, a URL or an app's data
+ * source read through a SourceReader, or memory. The demuxer reads through one of these.
+ */
+class ByteSource {
+public:
+    /** What read() returns when the bytes at `pos` aren't there yet and it won't wait for them. */
+    static constexpr int64_t kPending = -2;
+
+    virtual ~ByteSource() = default;
+
+    /**
+     * Reads up to `size` bytes at `pos` into `out` and returns how many it read: fewer near the
+     * end, 0 at or past the end, -1 on an error. A range reader returns once some bytes at `pos`
+     * have arrived. A source that can't wait (the web's, which fetches asynchronously) returns
+     * kPending instead; the demuxer then stops, and carries on when called again.
+     */
+    virtual int64_t read(int64_t pos, uint8_t* out, int64_t size) = 0;
+
+    /** The total size, or -1 while it isn't known (a response without a Content-Length). */
+    virtual int64_t size() const = 0;
+};
+
+/**
+ * Bytes [offset, offset + length) of a file descriptor: a video stored inside an APK
+ * (AssetManager.openFd) or behind a content:// URI, read in place. The descriptor is duplicated,
+ * so the caller still owns and closes the one it passed. A negative length means "to end of file".
+ *
+ * Returns nullptr if the range can't be opened.
+ */
+std::unique_ptr<ByteSource> openFileRange(int fd, int64_t offset, int64_t length);
+
+/** A whole file. Returns nullptr if it can't be opened. */
+std::unique_ptr<ByteSource> openFile(const std::string& path);
+
+/**
+ * A URL or an app's data source, through a SourceReader: the range-source add-on's reader, or the
+ * basic input's download.
+ *
+ * Reads wait for bytes being fetched. They fail if the fetch fails, or once `abort` (may be null;
+ * must outlive the source) is raised, so a player can unload without waiting for the network.
+ * The reader may be shared, by a probe and then the player.
+ */
+std::unique_ptr<ByteSource> openReader(std::shared_ptr<SourceReader> reader, const AbortFlag* abort);
+
+/** A copy of `size` bytes at `data`. */
+std::unique_ptr<ByteSource> openMemory(const uint8_t* data, size_t size);
+
+} // namespace webm

package/cpp/RangeSourceClient.h

@@ -0,0 +1,40 @@
+#pragma once
+
+// URLs and data sources are read through the range-source add-on, by its C table, or without it
+// through the basic input: a download into a temporary file. Both are a SourceReader.
+#define RANGE_SOURCE_CLIENT_NAMESPACE webm_rs
+#include "range_source.h"
+#include "range_source_download.h"
+
+#include <atomic>
+#include <cstddef>
+#include <cstdint>
+#include <string>
+
+namespace webm {
+
+using SourceReader = webm_rs::Reader;
+using SourceInfo = webm_rs::SourceInfo;
+using Upstream = webm_rs::Upstream;
+/** What a read waiting on the network checks to give up; the add-on's C table reads it too. */
+using AbortFlag = std::atomic<int32_t>;
+
+/**
+ * `plugin` if this player can use it: the same ABI, and every function it calls. Otherwise null,
+ * with `why` set.
+ */
+inline const RangeSourcePlugin* usablePlugin(const RangeSourcePlugin* plugin, std::string& why) {
+    if (!plugin) return nullptr;
+    if (plugin->abi != RANGE_SOURCE_ABI) {
+        why = "the range-source add-on has ABI " + std::to_string(plugin->abi) + ", and this player needs " +
+              std::to_string(RANGE_SOURCE_ABI);
+        return nullptr;
+    }
+    if (plugin->structSize < offsetof(RangeSourcePlugin, releaseReader) + sizeof(plugin->releaseReader)) {
+        why = "the range-source add-on is older than this player";
+        return nullptr;
+    }
+    return plugin;
+}
+
+} // namespace webm