From 316f9dc6053620865f4871f928c38197e7bda56c Mon Sep 17 00:00:00 2001
From: David Whitlark <dawhitla@twitch.tv>
Date: Mon, 26 Feb 2024 14:20:34 -0500
Subject: [PATCH] chore: creating preload docs

---
 docs/ivs-player-reference.md | 130 +++++++++++++++++++++++++++++++++++
 docs/prefetch-guide.md       |   1 +
 docs/types.md                |   9 +++
 3 files changed, 140 insertions(+)
 create mode 100644 docs/prefetch-guide.md

diff --git a/docs/ivs-player-reference.md b/docs/ivs-player-reference.md
index 603590d..5ae6d18 100644
--- a/docs/ivs-player-reference.md
+++ b/docs/ivs-player-reference.md
@@ -432,3 +432,133 @@ function App() {
   );
 }
 ```
+
+### preload
+
+Creates a loadable source from the given url. This affords preloading the manifest the player uses for playback.
+
+type: `(url: string) => Source`
+
+```tsx
+import IVSPlayer, { IVSPlayerRef } from 'amazon-ivs-react-native-player';
+
+const URL0 = 'https://fcc3ddae59ed.us-west-2.playback.live-video.net/api/video/v1/us-west-2.893648527354.channel.DmumNckWFTqz.m3u8';
+const URL1 = 'https://3d26876b73d7.us-west-2.playback.live-video.net/api/video/v1/us-west-2.913157848533.channel.rkCBS9iD1eyd.m3u8';
+const URL2 = 'https://fcc3ddae59ed.us-west-2.playback.live-video.net/api/video/v1/us-west-2.893648527354.channel.DmumNckWFTqz.m3u8';
+
+function App() {
+  const mediaPlayerRef = React.useRef<IVSPlayerRef>(null);
+  const [sources, setSources] = React.useState<Source[]>([]);
+
+  useEffect(() => {
+    const { current } = mediaPlayerRef;
+    if (!current) {
+      return
+    }
+    // this will preload the given 3 urls for playback
+    const prefetch = [
+      current.preload(URL0),
+      current.preload(URL1),
+      current.preload(URL2)
+    ];
+    setSources(prefetch);
+  },[]);
+
+  return (
+    <>
+      <IVSPlayer ref={mediaPlayerRef} />
+    </>
+  );
+}
+```
+
+### loadSource
+
+Instructs the player to begin playing the given source.
+
+type: `(source: Source) => void`
+
+```tsx
+import IVSPlayer, { IVSPlayerRef } from 'amazon-ivs-react-native-player';
+
+const URL0 = 'https://fcc3ddae59ed.us-west-2.playback.live-video.net/api/video/v1/us-west-2.893648527354.channel.DmumNckWFTqz.m3u8';
+const URL1 = 'https://3d26876b73d7.us-west-2.playback.live-video.net/api/video/v1/us-west-2.913157848533.channel.rkCBS9iD1eyd.m3u8';
+const URL2 = 'https://fcc3ddae59ed.us-west-2.playback.live-video.net/api/video/v1/us-west-2.893648527354.channel.DmumNckWFTqz.m3u8';
+
+function App() {
+  const mediaPlayerRef = React.useRef<IVSPlayerRef>(null);
+  const [sources, setSources] = React.useState<Source[]>([]);
+
+  useEffect(() => {
+    const { current } = mediaPlayerRef;
+    if (!current) {
+      return
+    }
+
+    const prefetch = [
+      current.preload(URL0),
+      current.preload(URL1),
+      current.preload(URL2)
+    ];
+
+    setSources(prefetch);
+  },[]);
+
+  return (
+    <>
+      <IVSPlayer ref={mediaPlayerRef} />
+      {sources.map((source, i) => {
+        return <Button key={i} onPress={() => mediaPlayerRef.current?.loadSource(source)} title={`URL${i}`} />;
+      })}
+    </>
+  );
+}
+
+```
+
+### releaseSource
+
+Frees a source created by `preload`
+
+type: `(source: Source) => void`
+
+```tsx
+import IVSPlayer, { IVSPlayerRef } from 'amazon-ivs-react-native-player';
+
+const URL0 = 'https://fcc3ddae59ed.us-west-2.playback.live-video.net/api/video/v1/us-west-2.893648527354.channel.DmumNckWFTqz.m3u8';
+const URL1 = 'https://3d26876b73d7.us-west-2.playback.live-video.net/api/video/v1/us-west-2.913157848533.channel.rkCBS9iD1eyd.m3u8';
+const URL2 = 'https://fcc3ddae59ed.us-west-2.playback.live-video.net/api/video/v1/us-west-2.893648527354.channel.DmumNckWFTqz.m3u8';
+
+function App() {
+  const mediaPlayerRef = React.useRef<IVSPlayerRef>(null);
+  const [sources, setSources] = React.useState<Source[]>([]);
+
+  useEffect(() => {
+    const { current } = mediaPlayerRef;
+    if (!current) {
+      return
+    }
+
+    const prefetch = [
+      current.preload(URL0),
+      current.preload(URL1),
+      current.preload(URL2)
+    ];
+    setSources(prefetch);
+
+    return () => {
+      prefetch.forEach((source) => current.releaseSource(source));
+    };
+  },[]);
+
+  return (
+    <>
+      <IVSPlayer ref={mediaPlayerRef} />
+      {sources.map((source, i) => {
+        return <Button key={i} onPress={() => mediaPlayerRef.current?.loadSource(source)} title={`URL${i}`} />;
+      })}
+    </>
+  );
+}
+```
+
diff --git a/docs/prefetch-guide.md b/docs/prefetch-guide.md
new file mode 100644
index 0000000..1fcaa83
--- /dev/null
+++ b/docs/prefetch-guide.md
@@ -0,0 +1 @@
+# IVSPlayer PREFETCH USAGE GUIDE
diff --git a/docs/types.md b/docs/types.md
index feb6a4d..4aa058d 100644
--- a/docs/types.md
+++ b/docs/types.md
@@ -74,3 +74,12 @@ export type TextMetadataCue = {
 ```ts
 export type ResizeMode = 'aspectFill' | 'aspectFit' | 'aspectZoom';
 ```
+
+## Source
+
+```ts
+export type Source = {
+  getId: () => void;
+  getUri: () => void;
+};
+```
\ No newline at end of file