@npaw/forge-react-native 9.6.1

package/ios/ForgeApple/Sources/ForgeKernelUniFFI/forge_kernelFFI.modulemap

@@ -0,0 +1,7 @@
+module forge_kernelFFI {
+    header "forge_kernelFFI.h"
+    export *
+    use "Darwin"
+    use "_Builtin_stdbool"
+    use "_Builtin_stdint"
+}

package/ios/ForgeApple/Sources/NPAWForgeAVPlayerAdapter/AVPlayerAccessLogFacts.swift

@@ -0,0 +1,152 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Pure resolution rules turning AVPlayerItem access-log events into Forge media-bitrate and QoS facts, keeping the media bitrate strictly separate from the observed network throughput.
+ */
+
+import AVFoundation
+import Foundation
+
+/// One access-log event reduced to the fields Forge derives facts from.
+///
+/// `AVPlayerItemAccessLogEvent` cannot be constructed in tests, so the adapter
+/// maps every event through this struct and the resolution rules below operate
+/// on it. That makes the rules deterministically testable without a live
+/// `AVPlayer`.
+///
+/// Field semantics are quoted from `AVFoundation/AVPlayerItem.h`; every one of
+/// them is documented as **negative if unknown**, which is why the rules filter
+/// on `> 0` and not merely on `isFinite`.
+struct AVPlayerAccessLogSample: Equatable {
+    /// `c-duration-downloaded` — "The accumulated duration of the media
+    /// downloaded", in **media** seconds. Combined with the transferred byte
+    /// count this yields a media bitrate, not a transfer rate.
+    let segmentsDownloadedDuration: Double
+    /// `c-bytes` — accumulated bytes transferred for the item.
+    let numberOfBytesTransferred: Int64
+    /// `sc-indicated-bitrate` — "The throughput required to play the stream,
+    /// as advertised by the server". Despite the header's wording this is the
+    /// **declared media bitrate** of the selected variant.
+    let indicatedBitrate: Double
+    /// `c-avg-video-bitrate` — the average video bitrate actually observed for
+    /// the item. Unambiguously a media bitrate, and the only tier that covers
+    /// progressive (non-HLS) assets, which advertise no variant bitrate.
+    let averageVideoBitrate: Double
+    /// `c-observed-bitrate` — "The empirical throughput across all media
+    /// downloaded". This is **network throughput**, never a media bitrate.
+    /// Forge reports it as `throughput`; publishing it as `bitrate` was the
+    /// defect this file exists to prevent.
+    let observedBitrate: Double
+    /// Dropped video frames reported for this event.
+    let numberOfDroppedVideoFrames: Int
+
+    init(
+        segmentsDownloadedDuration: Double,
+        numberOfBytesTransferred: Int64,
+        indicatedBitrate: Double,
+        averageVideoBitrate: Double,
+        observedBitrate: Double,
+        numberOfDroppedVideoFrames: Int
+    ) {
+        self.segmentsDownloadedDuration = segmentsDownloadedDuration
+        self.numberOfBytesTransferred = numberOfBytesTransferred
+        self.indicatedBitrate = indicatedBitrate
+        self.averageVideoBitrate = averageVideoBitrate
+        self.observedBitrate = observedBitrate
+        self.numberOfDroppedVideoFrames = numberOfDroppedVideoFrames
+    }
+
+    init(_ event: AVPlayerItemAccessLogEvent) {
+        self.init(
+            segmentsDownloadedDuration: event.segmentsDownloadedDuration,
+            numberOfBytesTransferred: event.numberOfBytesTransferred,
+            indicatedBitrate: event.indicatedBitrate,
+            averageVideoBitrate: event.averageVideoBitrate,
+            observedBitrate: event.observedBitrate,
+            numberOfDroppedVideoFrames: event.numberOfDroppedVideoFrames
+        )
+    }
+}
+
+/// Stateless resolution rules over access-log samples.
+///
+/// Kept free of adapter state so each rule is independently testable and so the
+/// bitrate path cannot accidentally reach for the throughput field.
+enum AVPlayerAccessLogFacts {
+    /// A finite, strictly positive reading, or `nil`. AVFoundation documents
+    /// every access-log metric as negative when unknown, and a `0` reading is
+    /// equally meaningless as a published fact.
+    private static func positive(_ value: Double) -> Double? {
+        guard value.isFinite, value > 0 else { return nil }
+        return value
+    }
+
+    /// The media bitrate of the content being played, resolved by tiers. The
+    /// first tier that yields a finite positive value wins; `nil` means unknown
+    /// and the caller must keep the last known-good value rather than publish
+    /// a zero.
+    ///
+    /// Tier 1 mirrors the v7 iOS plugin exactly (bytes * 8 / downloaded media
+    /// duration) so migrating integrations keep metric continuity. Tier 2 is
+    /// v7's own fallback and matches Forge's Flutter access-log enricher. Tier 3
+    /// covers progressive assets, which declare no variant bitrate at all.
+    ///
+    /// `observedBitrate` is deliberately absent from every tier: it is network
+    /// throughput, and reporting it here overstates the bitrate by orders of
+    /// magnitude and swings run-to-run on byte-identical content.
+    static func mediaBitrate(from sample: AVPlayerAccessLogSample) -> Int64? {
+        if sample.numberOfBytesTransferred > 0,
+           let duration = positive(sample.segmentsDownloadedDuration) {
+            let derived = Double(sample.numberOfBytesTransferred) * 8.0 / duration
+            if let value = positive(derived) {
+                return Int64(value)
+            }
+        }
+        if let indicated = positive(sample.indicatedBitrate) {
+            return Int64(indicated)
+        }
+        if let average = positive(sample.averageVideoBitrate) {
+            return Int64(average)
+        }
+        return nil
+    }
+
+    /// The empirical network throughput, which is what `observedBitrate`
+    /// actually measures.
+    static func observedThroughput(from sample: AVPlayerAccessLogSample) -> Double? {
+        positive(sample.observedBitrate)
+    }
+
+    /// Total dropped video frames across the item's access log. Returns `nil`
+    /// when no event reported a non-negative count, so "unknown" stays distinct
+    /// from a genuine zero.
+    static func droppedFrames(in samples: [AVPlayerAccessLogSample]) -> Int64? {
+        var total: Int64 = 0
+        var sawValue = false
+        for sample in samples where sample.numberOfDroppedVideoFrames >= 0 {
+            total += Int64(sample.numberOfDroppedVideoFrames)
+            sawValue = true
+        }
+        return sawValue ? total : nil
+    }
+
+    /// Total bytes transferred across the item's access log, or `nil` when no
+    /// event reported a non-negative count.
+    static func totalBytes(in samples: [AVPlayerAccessLogSample]) -> Int64? {
+        var total: Int64 = 0
+        var sawValue = false
+        for sample in samples where sample.numberOfBytesTransferred >= 0 {
+            total += sample.numberOfBytesTransferred
+            sawValue = true
+        }
+        return sawValue ? total : nil
+    }
+}