rx-player 4.5.0-dev.2026012302 → 4.5.0-dev.2026021900

package/src/core/stream/representation/__tests__/encryption_data_notifier.test.ts

@@ -0,0 +1,531 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { IRepresentationProtectionData } from "../../../../manifest/classes";
+import type { IProtectionDataInfo } from "../../../../transports";
+import EncryptionDataNotifier from "../encryption_data_notifier";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+
+vi.mock("../../../../manifest/classes", () => ({
+  Representation: vi.fn(),
+}));
+
+describe("EncryptionDataNotifier", () => {
+  let mockRepresentation: any;
+  let mockNotify: any;
+
+  beforeEach(() => {
+    mockNotify = vi.fn();
+    mockRepresentation = {
+      getEncryptionData: vi.fn(() => []),
+      addProtectionData: vi.fn(),
+      getAllEncryptionData: vi.fn(() => []),
+    };
+  });
+
+  describe("constructor - early notification", () => {
+    it("should send notification immediately when drmSystemId is provided and encryption data is complete", () => {
+      const mockEncryptionData: IRepresentationProtectionData[] = [
+        {
+          keyIds: [new Uint8Array([5, 6, 7, 8]), new Uint8Array([8, 7, 6, 5])],
+          values: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([1, 2, 3]),
+            },
+          ],
+          type: "cenc",
+        },
+      ];
+
+      mockRepresentation.getEncryptionData.mockReturnValue(mockEncryptionData);
+
+      new EncryptionDataNotifier({
+        drmSystemId: "edef8ba979d64acea3c827dcd51d21ed",
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      expect(mockRepresentation.getEncryptionData).toHaveBeenCalledWith(
+        "edef8ba979d64acea3c827dcd51d21ed",
+      );
+      expect(mockNotify).toHaveBeenCalledWith(mockEncryptionData);
+      expect(mockNotify).toHaveBeenCalledTimes(1);
+    });
+
+    it("should NOT send notification when encryption data exists but keyIds are undefined", () => {
+      const mockEncryptionData: IRepresentationProtectionData[] = [
+        {
+          keyIds: undefined,
+          values: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([1, 2, 3]),
+            },
+          ],
+          type: "cenc",
+        },
+      ];
+
+      mockRepresentation.getEncryptionData.mockReturnValue(mockEncryptionData);
+
+      new EncryptionDataNotifier({
+        drmSystemId: "edef8ba979d64acea3c827dcd51d21ed",
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      expect(mockRepresentation.getEncryptionData).toHaveBeenCalledWith(
+        "edef8ba979d64acea3c827dcd51d21ed",
+      );
+      expect(mockNotify).not.toHaveBeenCalled();
+    });
+
+    it("should NOT send notification when some items have keyIds and others don't", () => {
+      const mockEncryptionData: IRepresentationProtectionData[] = [
+        {
+          keyIds: [new Uint8Array([5, 6, 7, 8])],
+          values: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([1, 2, 3]),
+            },
+          ],
+          type: "cenc",
+        },
+        {
+          keyIds: undefined,
+          values: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([1, 2, 3]),
+            },
+          ],
+          type: "cenc",
+        },
+      ];
+
+      mockRepresentation.getEncryptionData.mockReturnValue(mockEncryptionData);
+
+      new EncryptionDataNotifier({
+        drmSystemId: "edef8ba979d64acea3c827dcd51d21ed",
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      expect(mockNotify).not.toHaveBeenCalled();
+    });
+
+    it("should NOT send notification when encryption data array is empty", () => {
+      new EncryptionDataNotifier({
+        drmSystemId: "edef8ba979d64acea3c827dcd51d21ed",
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      expect(mockNotify).not.toHaveBeenCalled();
+    });
+
+    it("should NOT send notification when drmSystemId is undefined", () => {
+      new EncryptionDataNotifier({
+        drmSystemId: undefined,
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      expect(mockRepresentation.getEncryptionData).not.toHaveBeenCalled();
+      expect(mockNotify).not.toHaveBeenCalled();
+    });
+
+    it("should handle empty keyIds array as valid", () => {
+      const mockEncryptionData: IRepresentationProtectionData[] = [
+        {
+          keyIds: [],
+          values: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([1, 2, 3]),
+            },
+          ],
+          type: "cenc",
+        },
+      ];
+
+      mockRepresentation.getEncryptionData.mockReturnValue(mockEncryptionData);
+
+      new EncryptionDataNotifier({
+        drmSystemId: "edef8ba979d64acea3c827dcd51d21ed",
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      expect(mockNotify).toHaveBeenCalledWith(mockEncryptionData);
+    });
+  });
+
+  describe("onNewProtectionData - deferred notification", () => {
+    it("should add protection data to representation and send notification", () => {
+      const notifier = new EncryptionDataNotifier({
+        drmSystemId: undefined,
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      const protectionData: IProtectionDataInfo[] = [
+        {
+          keyId: new Uint8Array([1, 2, 3]),
+          initDataType: "cenc",
+          initData: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([4, 5, 6]),
+            },
+          ],
+        },
+      ];
+
+      const allEncryptionData: IRepresentationProtectionData[] = [
+        {
+          keyIds: [new Uint8Array([5, 6, 7, 8])],
+          values: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([4, 5, 6]),
+            },
+          ],
+          type: "cenc",
+        },
+      ];
+      mockRepresentation.getAllEncryptionData.mockReturnValue(allEncryptionData);
+
+      notifier.onNewProtectionData(protectionData);
+
+      expect(mockRepresentation.addProtectionData).toHaveBeenCalledWith(
+        "cenc",
+        new Uint8Array([1, 2, 3]),
+        [
+          {
+            systemId: "edef8ba979d64acea3c827dcd51d21ed",
+            data: new Uint8Array([4, 5, 6]),
+          },
+        ],
+      );
+      expect(mockRepresentation.getAllEncryptionData).toHaveBeenCalled();
+      expect(mockNotify).toHaveBeenCalledWith(allEncryptionData);
+    });
+
+    it("should add multiple protection data items to representation", () => {
+      const notifier = new EncryptionDataNotifier({
+        drmSystemId: undefined,
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      const protectionData: IProtectionDataInfo[] = [
+        {
+          initDataType: "cenc",
+          keyId: new Uint8Array([1, 2, 3]),
+          initData: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([4, 5, 6]),
+            },
+          ],
+        },
+        {
+          initDataType: "cenc",
+          keyId: new Uint8Array([7, 8, 9]),
+          initData: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([10, 11, 12]),
+            },
+          ],
+        },
+      ];
+
+      const allEncryptionData: IRepresentationProtectionData[] = [
+        {
+          type: "cenc",
+          keyIds: [new Uint8Array([5, 6, 7, 8]), new Uint8Array([8, 7, 6, 5])],
+          values: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([4, 5, 6]),
+            },
+          ],
+        },
+      ];
+
+      mockRepresentation.getAllEncryptionData.mockReturnValue(allEncryptionData);
+
+      notifier.onNewProtectionData(protectionData);
+
+      expect(mockRepresentation.addProtectionData).toHaveBeenCalledTimes(2);
+      expect(mockRepresentation.addProtectionData).toHaveBeenNthCalledWith(
+        1,
+        "cenc",
+        new Uint8Array([1, 2, 3]),
+        [
+          {
+            systemId: "edef8ba979d64acea3c827dcd51d21ed",
+            data: new Uint8Array([4, 5, 6]),
+          },
+        ],
+      );
+      expect(mockRepresentation.addProtectionData).toHaveBeenNthCalledWith(
+        2,
+        "cenc",
+        new Uint8Array([7, 8, 9]),
+        [
+          {
+            systemId: "edef8ba979d64acea3c827dcd51d21ed",
+            data: new Uint8Array([10, 11, 12]),
+          },
+        ],
+      );
+      expect(mockNotify).toHaveBeenCalledWith(allEncryptionData);
+    });
+
+    it("should NOT send notification if no encryption data is available after adding", () => {
+      const notifier = new EncryptionDataNotifier({
+        drmSystemId: undefined,
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      const protectionData: IProtectionDataInfo[] = [
+        {
+          initDataType: "cenc",
+          keyId: new Uint8Array([1, 2, 3]),
+          initData: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([4, 5, 6]),
+            },
+          ],
+        },
+      ];
+      notifier.onNewProtectionData(protectionData);
+
+      expect(mockRepresentation.addProtectionData).toHaveBeenCalled();
+      expect(mockRepresentation.getAllEncryptionData).toHaveBeenCalled();
+      expect(mockNotify).not.toHaveBeenCalled();
+    });
+
+    it("should handle empty protection data array", () => {
+      const notifier = new EncryptionDataNotifier({
+        drmSystemId: undefined,
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+      notifier.onNewProtectionData([]);
+      expect(mockRepresentation.addProtectionData).not.toHaveBeenCalled();
+      expect(mockRepresentation.getAllEncryptionData).toHaveBeenCalled();
+      expect(mockNotify).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("notification sent only once", () => {
+    it("should NOT send notification again after early notification", () => {
+      const mockEncryptionData: IRepresentationProtectionData[] = [
+        {
+          keyIds: [new Uint8Array([5, 6, 7, 8])],
+          values: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([1, 2, 3]),
+            },
+          ],
+          type: "cenc",
+        },
+      ];
+      mockRepresentation.getEncryptionData.mockReturnValue(mockEncryptionData);
+
+      const notifier = new EncryptionDataNotifier({
+        drmSystemId: "edef8ba979d64acea3c827dcd51d21ed",
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      // Early notification should have been sent
+      expect(mockNotify).toHaveBeenCalledTimes(1);
+
+      // Now call onNewProtectionData
+      const protectionData: IProtectionDataInfo[] = [
+        {
+          initDataType: "cenc",
+          keyId: new Uint8Array([4, 5, 6]),
+          initData: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([7, 8, 9]),
+            },
+          ],
+        },
+      ];
+
+      mockRepresentation.getAllEncryptionData.mockReturnValue([
+        ...mockEncryptionData,
+        {
+          keyIds: [new Uint8Array([8, 7, 6, 5])],
+          systemId: "edef8ba979d64acea3c827dcd51d21ed",
+          initData: new Uint8Array([7, 8, 9]),
+          initDataType: "cenc",
+        },
+      ]);
+
+      notifier.onNewProtectionData(protectionData);
+
+      // Should still be called only once
+      expect(mockNotify).toHaveBeenCalledTimes(1);
+      expect(mockRepresentation.addProtectionData).toHaveBeenCalled();
+    });
+
+    it("should NOT send notification again on subsequent onNewProtectionData calls", () => {
+      const notifier = new EncryptionDataNotifier({
+        drmSystemId: undefined,
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      const protectionData1: IProtectionDataInfo[] = [
+        {
+          initDataType: "cenc",
+          keyId: new Uint8Array([1, 2, 3]),
+          initData: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([4, 5, 6]),
+            },
+          ],
+        },
+      ];
+      const allEncryptionData: IRepresentationProtectionData[] = [
+        {
+          type: "cenc",
+          keyIds: [new Uint8Array([5, 6, 7, 8])],
+          values: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([4, 5, 6]),
+            },
+          ],
+        },
+      ];
+      mockRepresentation.getAllEncryptionData.mockReturnValue(allEncryptionData);
+
+      // First call should trigger notification
+      notifier.onNewProtectionData(protectionData1);
+      expect(mockNotify).toHaveBeenCalledTimes(1);
+
+      // Second call should NOT trigger notification
+      const protectionData2: IProtectionDataInfo[] = [
+        {
+          initDataType: "cenc",
+          keyId: new Uint8Array([7, 8, 9]),
+          initData: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([10, 11, 12]),
+            },
+          ],
+        },
+      ];
+
+      notifier.onNewProtectionData(protectionData2);
+      expect(mockNotify).toHaveBeenCalledTimes(1);
+      expect(mockRepresentation.addProtectionData).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle multiple encryption data items with all keyIds defined", () => {
+      const mockEncryptionData: IRepresentationProtectionData[] = [
+        {
+          type: "cenc",
+          keyIds: [new Uint8Array([5, 6, 7, 8])],
+          values: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([1, 2, 3]),
+            },
+          ],
+        },
+        {
+          type: "cenc",
+          keyIds: [new Uint8Array([8, 7, 6, 5]), new Uint8Array([8, 8, 8, 8])],
+          values: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([4, 5, 6]),
+            },
+          ],
+        },
+      ];
+
+      mockRepresentation.getEncryptionData.mockReturnValue(mockEncryptionData);
+
+      new EncryptionDataNotifier({
+        drmSystemId: "edef8ba979d64acea3c827dcd51d21ed",
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      expect(mockNotify).toHaveBeenCalledWith(mockEncryptionData);
+    });
+
+    it("should add protection data even when notification was already sent", () => {
+      const mockEncryptionData: IRepresentationProtectionData[] = [
+        {
+          type: "cenc",
+          keyIds: [new Uint8Array([5, 6, 7, 8])],
+          values: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([1, 2, 3]),
+            },
+          ],
+        },
+      ];
+
+      mockRepresentation.getEncryptionData.mockReturnValue(mockEncryptionData);
+
+      const notifier = new EncryptionDataNotifier({
+        drmSystemId: "edef8ba979d64acea3c827dcd51d21ed",
+        representation: mockRepresentation,
+        notify: mockNotify,
+      });
+
+      expect(mockNotify).toHaveBeenCalledTimes(1);
+
+      const protectionData: IProtectionDataInfo[] = [
+        {
+          initDataType: "cenc",
+          keyId: new Uint8Array([7, 8, 9]),
+          initData: [
+            {
+              systemId: "edef8ba979d64acea3c827dcd51d21ed",
+              data: new Uint8Array([10, 11, 12]),
+            },
+          ],
+        },
+      ];
+
+      notifier.onNewProtectionData(protectionData);
+
+      // Data should still be added even though notification won't be sent again
+      expect(mockRepresentation.addProtectionData).toHaveBeenCalledWith(
+        "cenc",
+        new Uint8Array([7, 8, 9]),
+        [
+          {
+            systemId: "edef8ba979d64acea3c827dcd51d21ed",
+            data: new Uint8Array([10, 11, 12]),
+          },
+        ],
+      );
+    });
+  });
+});

package/src/core/stream/representation/encryption_data_notifier.ts

@@ -0,0 +1,122 @@
+import type {
+  Representation,
+  IRepresentationProtectionData,
+} from "../../../manifest/classes";
+import type { IProtectionDataInfo } from "../../../transports";
+
+/**
+ * Manages the one-time notification of encryption/DRM data for a Representation.
+ *
+ * This class collects encryption data from parsed segments and ensures that
+ * the encryption notification callback is triggered exactly once, as soon as
+ * sufficient data is available.
+ *
+ * The notification may occur in two ways:
+ * 1. **Early notification** (constructor): If the DRM system ID is known and
+ *    complete encryption data (with all key IDs) is already available, the
+ *    notification is sent immediately to enable faster license negotiation.
+ * 2. **Deferred notification** (onNewProtectionData): If early notification
+ *    doesn't occur, encryption data is collected from parsed segments and
+ *    the notification is sent once any encryption data becomes available.
+ *
+ * @example
+ * const notifier = new EncryptionDataNotifier({
+ *   drmSystemId: "edef8ba979d64acea3c827dcd51d21ed",
+ *   representation,
+ *   notify: (data) => callbacks.encryptionDataEncountered(data),
+ * });
+ *
+ * // Later, when a segment is parsed:
+ * notifier.onNewProtectionData(parsedSegmentEvent.protectionData);
+ */
+export default class EncryptionDataNotifier {
+  /**
+   * If `true` encryption data has already been sent through this
+   * `EncryptionDataNotifier`.
+   *
+   * For now we only send encryption data once per notifier at most as it was
+   * historically the only encountered case (encryption data in initialization
+   * segment).
+   * TODO: remove rule?
+   */
+  private _hasSentEncryptionData: boolean;
+  /**
+   * `Representation` linked to that `EncryptionDataNotifier`. Might be mutated
+   * to add encryption data information.
+   */
+  private _representation: Representation;
+  /** Callback to call when encryption information is first encountered. */
+  private _notify: (contentProtections: IRepresentationProtectionData[]) => void;
+
+  /**
+   * Create a new `EncryptionDataNotifier`.
+   * @param {Object} param0
+   * @param {string|undefined} param0.drmSystemId - If known the ID in hex
+   * format of the used DRM system (playready, widevine etc.).
+   * @param {Object} param0.representation - Object describing the
+   * Representation (including protection-related information). New encryption
+   * data might be added to it by this class.
+   * @param {Function} param0.notify - Function that will be called once new
+   * protection data has been detected.
+   */
+  constructor({
+    drmSystemId,
+    representation,
+    notify,
+  }: {
+    drmSystemId: string | undefined;
+    representation: Representation;
+    notify: (contentProtections: IRepresentationProtectionData[]) => void;
+  }) {
+    this._hasSentEncryptionData = false;
+    this._representation = representation;
+    this._notify = notify;
+
+    // If the DRM system id is already known, and if we already have encryption data
+    // for it, we may not need to wait until the initialization segment is loaded to
+    // signal required protection data, thus performing License negotiations sooner
+    if (drmSystemId !== undefined) {
+      const encryptionData = representation.getEncryptionData(drmSystemId);
+
+      // If some key ids are not known yet, it may be safer to wait for this initialization
+      // segment to be loaded first
+      if (
+        encryptionData.length > 0 &&
+        encryptionData.every((e) => e.keyIds !== undefined)
+      ) {
+        this._hasSentEncryptionData = true;
+        notify(encryptionData);
+      }
+    }
+  }
+
+  /**
+   * Signal that new protection data information is available.
+   * If necessary, that data will be added to the Representation and sent
+   * through the `notifiy` callback passed in constructor.
+   * @param {Array.<Object>} data - The new protection data encountered.
+   */
+  public onNewProtectionData(data: IProtectionDataInfo[]): void {
+    // Supplementary encryption information might have been parsed.
+    for (const protInfo of data) {
+      // TODO better handle use cases like key rotation by not always grouping
+      // every protection data together? To check.
+      this._representation.addProtectionData(
+        protInfo.initDataType,
+        protInfo.keyId,
+        protInfo.initData,
+      );
+    }
+
+    // Now that the initialization segment has been parsed - which may have
+    // included encryption information - take care of the encryption event
+    // if not already done.
+    if (!this._hasSentEncryptionData) {
+      const allEncryptionData = this._representation.getAllEncryptionData();
+      if (allEncryptionData.length > 0) {
+        this._notify(allEncryptionData);
+        this._hasSentEncryptionData = true;
+      }
+    }
+  }
+}