@applicaster/quick-brick-player 16.0.0-alpha.6174143047 → 16.0.0-alpha.6409114856

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/quick-brick-player",
-  "version": "16.0.0-alpha.6174143047",
+  "version": "16.0.0-alpha.6409114856",
   "description": "Quick Brick Player",
   "main": "./src/index.ts",
   "types": "index.d.ts",
@@ -35,11 +35,11 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/quick-brick-mobile-transport-controls": "16.0.0-rc.2",
-    "@applicaster/quick-brick-tv-transport-controls": "16.0.0-rc.9",
-    "@applicaster/zapp-react-native-tvos-app": "16.0.0-alpha.6174143047",
-    "@applicaster/zapp-react-native-ui-components": "16.0.0-alpha.6174143047",
-    "@applicaster/zapp-react-native-utils": "16.0.0-alpha.6174143047",
+    "@applicaster/quick-brick-mobile-transport-controls": "16.0.0-alpha.6409114856",
+    "@applicaster/quick-brick-tv-transport-controls": "16.0.0-rc.52",
+    "@applicaster/zapp-react-native-tvos-app": "16.0.0-alpha.6409114856",
+    "@applicaster/zapp-react-native-ui-components": "16.0.0-alpha.6409114856",
+    "@applicaster/zapp-react-native-utils": "16.0.0-alpha.6409114856",
     "query-string": "7.1.3",
     "shaka-player": "4.3.5",
     "typeface-montserrat": "^0.0.54",

package/src/Player/AudioLayer/Layout/Controls/__tests__/utils.test.ts

@@ -0,0 +1,66 @@
+import {
+  nextTrackButton,
+  previousTrackButton,
+  usesPlaylistControls,
+} from "../utils";
+
+describe("usesPlaylistControls", () => {
+  const configuredAs = (layout?: unknown): GetValue =>
+    ((key: string) =>
+      key === "player_controls_layout" ? layout : null) as unknown as GetValue;
+
+  it("opts in only for the playlist controls value", () => {
+    expect(usesPlaylistControls(configuredAs("playlist_controls"))).toBe(true);
+  });
+
+  it("keeps the original controls for the default value", () => {
+    expect(
+      usesPlaylistControls(configuredAs("playback_speed_and_sleep_timer"))
+    ).toBe(false);
+  });
+
+  it.each([
+    ["an undeclared key", undefined],
+    ["a null value", null],
+    ["an empty string", ""],
+    ["an unrecognised value", "something_else"],
+  ])("keeps the original controls for %s", (_label, layout) => {
+    expect(usesPlaylistControls(configuredAs(layout))).toBe(false);
+  });
+});
+
+describe("track control buttons", () => {
+  it("builds a previous button using the previous_track icon", () => {
+    const onPress = jest.fn();
+
+    expect(previousTrackButton({ isTablet: false, onPress })).toMatchObject({
+      size: "small",
+      icon: "previous_track",
+      onPress,
+    });
+  });
+
+  it("builds a next button using the next_track icon", () => {
+    const onPress = jest.fn();
+
+    expect(nextTrackButton({ isTablet: false, onPress })).toMatchObject({
+      size: "small",
+      icon: "next_track",
+      onPress,
+    });
+  });
+
+  it("propagates the disabled flag", () => {
+    expect(
+      nextTrackButton({ isTablet: false, onPress: jest.fn(), disabled: true })
+    ).toMatchObject({ disabled: true });
+
+    expect(
+      previousTrackButton({
+        isTablet: false,
+        onPress: jest.fn(),
+        disabled: true,
+      })
+    ).toMatchObject({ disabled: true });
+  });
+});

package/src/Player/AudioLayer/Layout/Controls/index.tsx

@@ -18,14 +18,18 @@ import { VerticalGutter } from "./VerticalGutter";
 
 import {
   forwardButton,
+  nextTrackButton,
   playbackButton,
+  previousTrackButton,
   rewindButton,
   skipToLiveButton,
   skipToStartButton,
   sleepButton,
   speedButton,
+  usesPlaylistControls,
 } from "./utils";
 import { useSleepTimerModal } from "../../useSleepTimerModal";
+import { usePlaylistNavigation } from "../../usePlaylistNavigation";
 
 const styles = StyleSheet.create({
   flex: {
@@ -107,6 +111,13 @@ export const Controls = (props: Props) => {
     configuration
   );
 
+  const { hasNext, hasPrevious, goNext, goPrevious } = usePlaylistNavigation(
+    entry,
+    playerState
+  );
+
+  const isPlaylistControlsLayout = usesPlaylistControls(value);
+
   const timerRemaining =
     sleepTimerState.timerDate !== 0 && +sleepTimerState.timerDate > Date.now()
       ? sleepTimerState.timerDate
@@ -203,6 +214,22 @@ export const Controls = (props: Props) => {
       return [skipToStart, rewind, play, forward, skipToLive];
     }
 
+    if (isPlaylistControlsLayout) {
+      const previous = previousTrackButton({
+        isTablet,
+        onPress: goPrevious,
+        disabled: !hasPrevious,
+      });
+
+      const next = nextTrackButton({
+        isTablet,
+        onPress: goNext,
+        disabled: !hasNext,
+      });
+
+      return [previous, rewind, play, forward, next];
+    }
+
     return [speed, rewind, play, forward, sleep];
   }, [
     playerState,
@@ -220,6 +247,11 @@ export const Controls = (props: Props) => {
     playbackSleepName,
     controller,
     isLiveShowFullControls,
+    isPlaylistControlsLayout,
+    hasNext,
+    hasPrevious,
+    goNext,
+    goPrevious,
   ]);
 
   return (

package/src/Player/AudioLayer/Layout/Controls/utils.ts

@@ -103,3 +103,29 @@ export const speedButton = (props: ButtonsProps): ControlsButton =>
 
 export const sleepButton = (props: ButtonsProps): ControlsButton =>
   sleepButtonByName(props);
+
+// Opt-in: a player plugin that does not declare this key returns undefined,
+// which has to read as the default rather than as an opt-in.
+export const usesPlaylistControls = (value: GetValue): boolean =>
+  value("player_controls_layout") === "playlist_controls";
+
+type TrackButtonProps = ButtonsProps & { disabled?: boolean };
+
+const trackButtonByName = ({
+  name,
+  onPress,
+  style,
+  disabled,
+}: TrackButtonProps & { name: string }): ControlsButton => ({
+  size: "small",
+  icon: name,
+  onPress,
+  style,
+  disabled,
+});
+
+export const previousTrackButton = (props: TrackButtonProps): ControlsButton =>
+  trackButtonByName({ ...props, name: "previous_track" });
+
+export const nextTrackButton = (props: TrackButtonProps): ControlsButton =>
+  trackButtonByName({ ...props, name: "next_track" });

package/src/Player/AudioLayer/__tests__/usePlaylistNavigation.test.ts

@@ -0,0 +1,376 @@
+import { renderHook, act } from "@testing-library/react-native";
+import { useNavigation } from "@applicaster/zapp-react-native-utils/reactHooks";
+import { usePlayer } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/usePlayer";
+import { loadFeedEntry } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/OverlayObserver/utils";
+
+import { usePlaylistNavigation } from "../usePlaylistNavigation";
+
+jest.mock("@applicaster/zapp-react-native-utils/reactHooks", () => ({
+  useNavigation: jest.fn(),
+}));
+
+jest.mock(
+  "@applicaster/zapp-react-native-utils/appUtils/playerManager/usePlayer",
+  () => ({ usePlayer: jest.fn() })
+);
+
+jest.mock(
+  "@applicaster/zapp-react-native-utils/appUtils/playerManager/OverlayObserver/utils",
+  () => ({
+    loadFeedEntry: jest.fn(),
+    retrieveFeedUrl: (entry) => entry?.extensions?.play_next_feed_url,
+    retrievePlayPreviousFeedUrl: (entry) =>
+      entry?.extensions?.play_previous_feed_url,
+  })
+);
+
+const useNavigationMock = useNavigation as jest.Mock;
+const loadFeedEntryMock = loadFeedEntry as jest.Mock;
+const usePlayerMock = usePlayer as jest.Mock;
+
+const NEXT_URL = "https://feeds/next.json";
+const PREV_URL = "https://feeds/prev.json";
+
+const entryWith = (extensions: Record<string, unknown>): ZappEntry =>
+  ({ id: "current", type: { value: "audio" }, extensions }) as ZappEntry;
+
+/** Seekable VOD by default; pass 0 for a live stream with no seek window. */
+const stateAt = (
+  currentTime: number,
+  seekableDuration = 600
+): QuickBrickPlayer.PlayerState =>
+  ({ currentTime, seekableDuration }) as QuickBrickPlayer.PlayerState;
+
+const NOT_SEEKABLE = 0;
+
+describe("usePlaylistNavigation", () => {
+  let replaceTop: jest.Mock;
+  let seekTo: jest.Mock;
+
+  beforeEach(() => {
+    replaceTop = jest.fn();
+    seekTo = jest.fn();
+
+    useNavigationMock.mockReturnValue({ replaceTop });
+
+    usePlayerMock.mockReturnValue({ seekTo });
+
+    loadFeedEntryMock.mockReset();
+  });
+
+  describe("availability", () => {
+    it("reports both directions when both extensions are present", () => {
+      const entry = entryWith({
+        play_next_feed_url: NEXT_URL,
+        play_previous_feed_url: PREV_URL,
+      });
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entry, stateAt(0))
+      );
+
+      expect(result.current.hasNext).toBe(true);
+      expect(result.current.hasPrevious).toBe(true);
+    });
+
+    it("keeps previous available at the head of a chain when the track is seekable", () => {
+      const entry = entryWith({ play_next_feed_url: NEXT_URL });
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entry, stateAt(0))
+      );
+
+      expect(result.current.hasNext).toBe(true);
+      expect(result.current.hasPrevious).toBe(true);
+    });
+
+    it("reports no previous only when the track cannot seek either", () => {
+      const entry = entryWith({ play_next_feed_url: NEXT_URL });
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entry, stateAt(0, NOT_SEEKABLE))
+      );
+
+      expect(result.current.hasNext).toBe(true);
+      expect(result.current.hasPrevious).toBe(false);
+    });
+
+    it("reports neither direction for a non-seekable entry with no extensions", () => {
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entryWith({}), stateAt(0, NOT_SEEKABLE))
+      );
+
+      expect(result.current.hasNext).toBe(false);
+      expect(result.current.hasPrevious).toBe(false);
+    });
+  });
+
+  describe("goNext", () => {
+    it("plays the entry resolved from the next feed url", async () => {
+      const target = { id: "next" } as ZappEntry;
+      loadFeedEntryMock.mockResolvedValue(target);
+      const entry = entryWith({ play_next_feed_url: NEXT_URL });
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entry, stateAt(0))
+      );
+
+      await act(async () => result.current.goNext());
+
+      expect(loadFeedEntryMock).toHaveBeenCalledWith(NEXT_URL, entry);
+      expect(replaceTop).toHaveBeenCalledWith(target);
+    });
+
+    it("does nothing when there is no next url", async () => {
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entryWith({}), stateAt(0))
+      );
+
+      await act(async () => result.current.goNext());
+
+      expect(loadFeedEntryMock).not.toHaveBeenCalled();
+      expect(replaceTop).not.toHaveBeenCalled();
+    });
+
+    it("leaves playback untouched when the feed fails to load", async () => {
+      loadFeedEntryMock.mockRejectedValue(new Error("network down"));
+      const entry = entryWith({ play_next_feed_url: NEXT_URL });
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entry, stateAt(0))
+      );
+
+      await act(async () => result.current.goNext());
+
+      expect(replaceTop).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("goPrevious", () => {
+    it("restarts the current track when past the threshold", async () => {
+      const entry = entryWith({ play_previous_feed_url: PREV_URL });
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entry, stateAt(10))
+      );
+
+      await act(async () => result.current.goPrevious());
+
+      expect(seekTo).toHaveBeenCalledWith(0);
+      expect(replaceTop).not.toHaveBeenCalled();
+    });
+
+    it("plays the previous entry when before the threshold", async () => {
+      const target = { id: "prev" } as ZappEntry;
+      loadFeedEntryMock.mockResolvedValue(target);
+      const entry = entryWith({ play_previous_feed_url: PREV_URL });
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entry, stateAt(1))
+      );
+
+      await act(async () => result.current.goPrevious());
+
+      expect(seekTo).not.toHaveBeenCalled();
+      expect(replaceTop).toHaveBeenCalledWith(target);
+    });
+
+    it("restarts the track when there is no previous entry to move to", async () => {
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(
+          entryWith({ play_next_feed_url: NEXT_URL }),
+          stateAt(390)
+        )
+      );
+
+      await act(async () => result.current.goPrevious());
+
+      expect(seekTo).toHaveBeenCalledWith(0);
+      expect(replaceTop).not.toHaveBeenCalled();
+    });
+
+    it("restarts even before the threshold when there is no previous entry", async () => {
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entryWith({}), stateAt(1))
+      );
+
+      await act(async () => result.current.goPrevious());
+
+      expect(seekTo).toHaveBeenCalledWith(0);
+      expect(replaceTop).not.toHaveBeenCalled();
+    });
+
+    // usePlayer, not playerManager.getActivePlayer — the latter is always the
+    // local player, so restarting would be lost while casting.
+    it("restarts through the player that owns playback, not the local one", async () => {
+      const receiverSeekTo = jest.fn();
+      usePlayerMock.mockReturnValue({ seekTo: receiverSeekTo });
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(
+          entryWith({ play_previous_feed_url: PREV_URL }),
+          stateAt(10)
+        )
+      );
+
+      await act(async () => result.current.goPrevious());
+
+      expect(receiverSeekTo).toHaveBeenCalledWith(0);
+    });
+
+    it("does nothing when there is neither a previous entry nor a seek window", async () => {
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entryWith({}), stateAt(10, NOT_SEEKABLE))
+      );
+
+      await act(async () => result.current.goPrevious());
+
+      expect(seekTo).not.toHaveBeenCalled();
+      expect(replaceTop).not.toHaveBeenCalled();
+    });
+
+    it("navigates to the previous entry past the threshold when the stream cannot seek", async () => {
+      const target = { id: "prev" } as ZappEntry;
+      loadFeedEntryMock.mockResolvedValue(target);
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(
+          entryWith({ play_previous_feed_url: PREV_URL }),
+          stateAt(10, NOT_SEEKABLE)
+        )
+      );
+
+      await act(async () => result.current.goPrevious());
+
+      expect(seekTo).not.toHaveBeenCalled();
+      expect(replaceTop).toHaveBeenCalledWith(target);
+    });
+
+    it("restarts past the threshold when the stream is seekable", async () => {
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(
+          entryWith({ play_previous_feed_url: PREV_URL }),
+          stateAt(10)
+        )
+      );
+
+      await act(async () => result.current.goPrevious());
+
+      expect(seekTo).toHaveBeenCalledWith(0);
+      expect(replaceTop).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("double tap guard", () => {
+    const bothDirections = {
+      play_next_feed_url: NEXT_URL,
+      play_previous_feed_url: PREV_URL,
+    };
+
+    /**
+     * Makes the next feed request hang until the returned function is called,
+     * so a test can fire a second tap while the first is still in flight.
+     */
+    const deferredFeed = () => {
+      const deferred: { complete?: (entry: ZappEntry) => void } = {};
+
+      loadFeedEntryMock.mockReturnValue(
+        new Promise<ZappEntry>((resolve) => {
+          deferred.complete = resolve;
+        })
+      );
+
+      return (entry: ZappEntry) => deferred.complete(entry);
+    };
+
+    it("ignores a second tap while the first request is still in flight", async () => {
+      const complete = deferredFeed();
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entryWith(bothDirections), stateAt(0))
+      );
+
+      await act(async () => {
+        const first = result.current.goNext();
+        const second = result.current.goNext();
+
+        complete({ id: "next" } as ZappEntry);
+
+        await Promise.all([first, second]);
+      });
+
+      expect(loadFeedEntryMock).toHaveBeenCalledTimes(1);
+      expect(replaceTop).toHaveBeenCalledTimes(1);
+    });
+
+    it("stops Previous racing an in-flight Next", async () => {
+      const complete = deferredFeed();
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entryWith(bothDirections), stateAt(0))
+      );
+
+      await act(async () => {
+        const next = result.current.goNext();
+        const previous = result.current.goPrevious();
+
+        complete({ id: "next" } as ZappEntry);
+
+        await Promise.all([next, previous]);
+      });
+
+      expect(loadFeedEntryMock).toHaveBeenCalledTimes(1);
+
+      expect(loadFeedEntryMock).toHaveBeenCalledWith(
+        NEXT_URL,
+        expect.anything()
+      );
+    });
+
+    it("allows a new navigation once the previous one has completed", async () => {
+      loadFeedEntryMock.mockResolvedValue({ id: "next" } as ZappEntry);
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entryWith(bothDirections), stateAt(0))
+      );
+
+      await act(async () => result.current.goNext());
+      await act(async () => result.current.goNext());
+
+      expect(loadFeedEntryMock).toHaveBeenCalledTimes(2);
+      expect(replaceTop).toHaveBeenCalledTimes(2);
+    });
+
+    it("releases the guard after a failed request so the control can retry", async () => {
+      loadFeedEntryMock
+        .mockRejectedValueOnce(new Error("network down"))
+        .mockResolvedValueOnce({ id: "next" } as ZappEntry);
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entryWith(bothDirections), stateAt(0))
+      );
+
+      await act(async () => result.current.goNext());
+
+      expect(replaceTop).not.toHaveBeenCalled();
+
+      await act(async () => result.current.goNext());
+
+      expect(replaceTop).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not guard the Previous restart, which is local and instant", async () => {
+      loadFeedEntryMock.mockResolvedValue({ id: "prev" } as ZappEntry);
+
+      const { result } = renderHook(() =>
+        usePlaylistNavigation(entryWith(bothDirections), stateAt(10))
+      );
+
+      await act(async () => result.current.goPrevious());
+      await act(async () => result.current.goPrevious());
+
+      expect(seekTo).toHaveBeenCalledTimes(2);
+      expect(loadFeedEntryMock).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/Player/AudioLayer/usePlaylistNavigation.ts

@@ -0,0 +1,108 @@
+import * as React from "react";
+
+import { useNavigation } from "@applicaster/zapp-react-native-utils/reactHooks";
+import { usePlayer } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/usePlayer";
+import {
+  loadFeedEntry,
+  retrieveFeedUrl,
+  retrievePlayPreviousFeedUrl,
+} from "@applicaster/zapp-react-native-utils/appUtils/playerManager/OverlayObserver/utils";
+import { createLogger } from "@applicaster/zapp-react-native-utils/logger";
+
+const { log_error, log_info } = createLogger({
+  subsystem: "Player",
+  category: "usePlaylistNavigation",
+});
+
+const RESTART_THRESHOLD_SECONDS = 3;
+
+export type PlaylistNavigation = {
+  hasNext: boolean;
+  hasPrevious: boolean;
+  goNext: () => Promise<void>;
+  goPrevious: () => Promise<void>;
+};
+
+/**
+ * Each entry points at the feed holding its neighbour, so the chain walks
+ * itself and needs no client-side queue.
+ */
+export const usePlaylistNavigation = (
+  entry: ZappEntry,
+  playerState: QuickBrickPlayer.PlayerState
+): PlaylistNavigation => {
+  const navigator = useNavigation();
+  // Not playerManager.getActivePlayer(): that is always the local player, so
+  // seeking would miss the receiver while casting.
+  const player = usePlayer();
+
+  const nextUrl = retrieveFeedUrl(entry);
+  const previousUrl = retrievePlayPreviousFeedUrl(entry);
+  const currentTime = playerState?.currentTime ?? 0;
+
+  const canRestart = (playerState?.seekableDuration ?? 0) > 0;
+
+  const isNavigatingRef = React.useRef(false);
+
+  const navigateTo = React.useCallback(
+    async (feedUrl: string) => {
+      // A second tap mid-flight resolves to the same target, since `entry` has
+      // not been replaced yet.
+      if (isNavigatingRef.current) {
+        return;
+      }
+
+      isNavigatingRef.current = true;
+
+      try {
+        const target = await loadFeedEntry(feedUrl, entry);
+
+        log_info(`navigateTo: playing "${target.title}", id: ${target.id}`, {
+          feedUrl,
+          targetId: target.id,
+        });
+
+        navigator.replaceTop(target);
+      } catch (error) {
+        log_error("navigateTo: could not play the neighbouring entry", {
+          error,
+          feedUrl,
+        });
+      } finally {
+        // Released on failure too, so one bad request cannot latch the control.
+        isNavigatingRef.current = false;
+      }
+    },
+    [entry, navigator]
+  );
+
+  const goNext = React.useCallback(async () => {
+    if (!nextUrl) return;
+
+    await navigateTo(nextUrl);
+  }, [nextUrl, navigateTo]);
+
+  const goPrevious = React.useCallback(async () => {
+    // Restarting belongs to the stream, not the chain — so it stays available
+    // at the head, where there is nothing to step back to.
+    const shouldRestart =
+      canRestart && (currentTime > RESTART_THRESHOLD_SECONDS || !previousUrl);
+
+    if (shouldRestart) {
+      player?.seekTo(0);
+
+      return;
+    }
+
+    if (!previousUrl) return;
+
+    await navigateTo(previousUrl);
+  }, [previousUrl, currentTime, canRestart, navigateTo, player]);
+
+  return {
+    hasNext: Boolean(nextUrl),
+    hasPrevious: Boolean(previousUrl) || canRestart,
+    goNext,
+    goPrevious,
+  };
+};

package/src/Player/index.tsx

@@ -52,7 +52,7 @@ import { TVPlayerView } from "./PlayerView/TVPlayerView";
 import PlayerModal, { VideoPlayerModal } from "./PlayerModal";
 import { DockedControls } from "./AudioLayer/Layout/DockedControls";
 import { FlexImage } from "./AudioLayer/Layout/PlayerImage/FlexImage";
-import { PlayerError } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/conts";
+import { PlayerError } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/const";
 
 const isTvOS = isTvOSPlatform();