huge rewrite

guides/integrations.md

@@ -0,0 +1,213 @@
+# Client Integration Guide
+
+<p class="page-description">Frontend and native player implementation patterns for integrating Vyla Stream API with HLS.js, React, Vue, Android ExoPlayer, and iOS AVPlayer.</p>
+
+## Overview
+
+Stream API exposes standard HTTP and Server-Sent Events (SSE) interfaces, allowing it to integrate with any modern video player library. This guide provides copyable, production-ready integration patterns across multiple platforms and frameworks.
+
+---
+
+## Pattern 1: React Player Hook
+
+Below is a complete custom React hook (`useVylaStream`) managing SSE event consumption, fallback candidate queuing, and playback state:
+
+```tsx
+import { useState, useEffect, useRef } from 'react';
+
+interface StreamSource {
+  source: string;
+  label: string;
+  url: string;
+  quality: string;
+  type: 'hls' | 'mp4';
+}
+
+interface StreamMeta {
+  title: string;
+  year: number;
+  poster: string;
+}
+
+export function useVylaStream(apiBase: string, tmdbId: number, season?: number, episode?: number) {
+  const [meta, setMeta] = useState<StreamMeta | null>(null);
+  const [activeSource, setActiveSource] = useState<StreamSource | null>(null);
+  const [subtitles, setSubtitles] = useState<any[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const fallbackQueue = useRef<StreamSource[]>([]);
+  const eventSourceRef = useRef<EventSource | null>(null);
+
+  useEffect(() => {
+    setIsLoading(true);
+    setError(null);
+    fallbackQueue.current = [];
+
+    const endpoint = season != null && episode != null
+      ? `${apiBase}/tv?id=${tmdbId}&season=${season}&episode=${episode}`
+      : `${apiBase}/movie?id=${tmdbId}`;
+
+    const es = new EventSource(endpoint);
+    eventSourceRef.current = es;
+
+    es.onmessage = (event) => {
+      const data = JSON.parse(event.data);
+
+      if (data.type === 'meta') {
+        setMeta(data.meta);
+        if (data.subtitles) setSubtitles(data.subtitles);
+      } 
+      else if (data.type === 'source') {
+        if (!activeSource) {
+          setActiveSource(data);
+          setIsLoading(false);
+        } else {
+          fallbackQueue.current.push(data);
+        }
+      } 
+      else if (data.type === 'done') {
+        es.close();
+        if (!activeSource && fallbackQueue.current.length === 0) {
+          setError('No available streaming sources found.');
+          setIsLoading(false);
+        }
+      }
+    };
+
+    es.onerror = () => {
+      es.close();
+      if (!activeSource) {
+        setError('Failed to connect to Stream API.');
+        setIsLoading(false);
+      }
+    };
+
+    return () => {
+      es.close();
+    };
+  }, [apiBase, tmdbId, season, episode]);
+
+  const triggerNextFallback = () => {
+    if (fallbackQueue.current.length > 0) {
+      const next = fallbackQueue.current.shift()!;
+      console.warn(`Switching to fallback candidate: ${next.label}`);
+      setActiveSource(next);
+    } else {
+      setError('All provider stream candidates exhausted.');
+    }
+  };
+
+  return { meta, activeSource, subtitles, isLoading, error, triggerNextFallback };
+}
+```
+
+---
+
+## Pattern 2: Vue 3 Composable Component
+
+```vue
+<template>
+  <div class="player-wrapper">
+    <video ref="videoRef" controls playsinline></video>
+    <div v-if="isLoading" class="loading-overlay">Discovering streams...</div>
+    <div v-if="error" class="error-banner">{{ error }}</div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted, watch } from 'vue';
+import Hls from 'hls.js';
+
+const props = defineProps<{
+  apiBase: string;
+  tmdbId: number;
+}>();
+
+const videoRef = ref<HTMLVideoElement | null>(null);
+const isLoading = ref(true);
+const error = ref<string | null>(null);
+let hls: Hls | null = null;
+let es: EventSource | null = null;
+
+function loadStream(url: string) {
+  if (!videoRef.value) return;
+
+  if (Hls.isSupported()) {
+    if (hls) hls.destroy();
+    hls = new Hls({ maxBufferLength: 30 });
+    hls.loadSource(url);
+    hls.attachMedia(videoRef.value);
+    hls.on(Hls.Events.MANIFEST_PARSED, () => videoRef.value?.play());
+  } else if (videoRef.value.canPlayType('application/vnd.apple.mpegurl')) {
+    videoRef.value.src = url;
+    videoRef.value.play();
+  }
+}
+
+onMounted(() => {
+  es = new EventSource(`${props.apiBase}/movie?id=${props.tmdbId}`);
+  let firstSourceReceived = false;
+
+  es.onmessage = (e) => {
+    const data = JSON.parse(e.data);
+    if (data.type === 'source' && !firstSourceReceived) {
+      firstSourceReceived = true;
+      isLoading.value = false;
+      loadStream(data.url);
+    } else if (data.type === 'done') {
+      es?.close();
+    }
+  };
+});
+
+onUnmounted(() => {
+  es?.close();
+  hls?.destroy();
+});
+</script>
+```
+
+---
+
+## Pattern 3: Android Native (Kotlin & ExoPlayer)
+
+In Android applications, connect to the Stream API proxy using Google's `MediaItem`:
+
+```kotlin
+import androidx.media3.common.MediaItem
+import androidx.media3.common.MimeTypes
+import androidx.media3.exoplayer.ExoPlayer
+
+fun playStream(player: ExoPlayer, proxiedHlsUrl: String) {
+    val mediaItem = MediaItem.Builder()
+        .setUri(proxiedHlsUrl)
+        .setMimeType(MimeTypes.APPLICATION_M3U8)
+        .build()
+
+    player.setMediaItem(mediaItem)
+    player.prepare()
+    player.playWhenReady = true
+}
+```
+
+---
+
+## Pattern 4: iOS / macOS Native (Swift & AVPlayer)
+
+Because iOS AVPlayer natively handles HLS streams and respects cookies/redirects, assigning the proxied URL is straightforward:
+
+```swift
+import AVKit
+
+func playVylaStream(proxiedUrlString: String) {
+    guard let url = URL(string: proxiedUrlString) else { return }
+    let player = AVPlayer(url: url)
+    let playerViewController = AVPlayerViewController()
+    playerViewController.player = player
+    
+    present(playerViewController, animated: true) {
+        player.play()
+    }
+}
+```