@dialtribe/react-sdk 0.1.0-alpha.8 → 0.1.4

package/dist/dialtribe-streamer-C16mRqha.d.ts

@@ -0,0 +1,567 @@
+import './dialtribe-player-CNriUtNi.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1, { RefObject } from 'react';
+
+/**
+ * Props for the DialtribeStreamer component.
+ *
+ * @example
+ * ```tsx
+ * // Inside DialtribeProvider (recommended)
+ * <DialtribeProvider sessionToken={token}>
+ *   <DialtribeStreamer
+ *     streamKey={keyFromBackend}
+ *     onDone={() => window.close()}
+ *   />
+ * </DialtribeProvider>
+ *
+ * // Standalone (e.g., popup window)
+ * <DialtribeStreamer
+ *   sessionToken={token}
+ *   streamKey={keyFromBackend}
+ *   onDone={() => window.close()}
+ * />
+ * ```
+ */
+interface DialtribeStreamerProps {
+    /**
+     * Session token for API authentication.
+     *
+     * Required for permission checks. Can be provided via:
+     * 1. DialtribeProvider context (recommended for main app)
+     * 2. This prop (required for popup windows)
+     *
+     * Must include `broadcasts:stream` permission.
+     */
+    sessionToken?: string;
+    /**
+     * Stream key for broadcasting.
+     *
+     * **Production apps should always provide this from their backend.**
+     * The stream key authenticates the broadcaster with the encoder server.
+     *
+     * If omitted, a manual input form is shown. This is intended for
+     * development/testing only - end users should never see or handle stream keys.
+     *
+     * @example "w1_abc123def456..."
+     */
+    streamKey?: string;
+    /**
+     * Called when streaming ends (user stops, terminates, or clicks Done).
+     * Use this to close the popup or navigate away.
+     *
+     * @example () => window.close()
+     */
+    onDone?: () => void;
+    /**
+     * Called when the stream key changes (e.g., user edits it in preview mode).
+     * Useful for persisting the key or updating parent state.
+     */
+    onStreamKeyChange?: (key: string) => void;
+    /**
+     * Custom encoder server URL. Defaults to Dialtribe's production encoder.
+     * Only change this for self-hosted encoder deployments.
+     *
+     * @default "https://broadcastapi.dialtribe.com"
+     */
+    encoderServerUrl?: string;
+    /**
+     * Custom API base URL for broadcast availability checks.
+     * Only change this for self-hosted API deployments.
+     *
+     * @default "https://dialtribe.com/api/public/v1"
+     */
+    apiBaseUrl?: string;
+    /**
+     * When true, the streamer fills its parent container instead of the viewport.
+     * Use this when embedding the streamer inline within a page.
+     *
+     * @default false
+     */
+    inline?: boolean;
+}
+declare function DialtribeStreamer({ sessionToken: propSessionToken, streamKey: initialStreamKey, onDone, onStreamKeyChange, encoderServerUrl, apiBaseUrl, inline, }: DialtribeStreamerProps): react_jsx_runtime.JSX.Element;
+
+interface StreamingPreviewProps {
+    videoRef: RefObject<HTMLVideoElement>;
+    isVideoKey: boolean;
+    isVideoEnabled: boolean;
+    mediaStream: MediaStream | null;
+    facingMode: "user" | "environment";
+}
+declare function StreamingPreview({ videoRef, isVideoKey, isVideoEnabled, mediaStream, facingMode, }: StreamingPreviewProps): react_jsx_runtime.JSX.Element;
+
+type StreamingControlState = "previewing" | "connecting" | "live" | "stopping";
+interface MediaDeviceInfo {
+    deviceId: string;
+    label: string;
+}
+interface StreamingControlsProps {
+    state: StreamingControlState;
+    isVideoKey: boolean;
+    isMuted: boolean;
+    isVideoEnabled: boolean;
+    facingMode: "user" | "environment";
+    hasMultipleCameras: boolean;
+    startTime: Date | null;
+    bytesSent: number;
+    showStopConfirm: boolean;
+    streamKey: string;
+    onStreamKeyChange?: (newKey: string) => void;
+    onStart: () => void;
+    onStop: () => void;
+    onConfirmStop: () => void;
+    onCancelStop: () => void;
+    onToggleMute: () => void;
+    onToggleVideo: () => void;
+    onFlipCamera: () => void;
+    onClose?: () => void;
+    showCloseConfirm?: boolean;
+    onConfirmClose?: () => void;
+    onCancelClose?: () => void;
+    videoDevices?: MediaDeviceInfo[];
+    audioDevices?: MediaDeviceInfo[];
+    selectedVideoDeviceId?: string;
+    selectedAudioDeviceId?: string;
+    onVideoDeviceChange?: (deviceId: string) => void;
+    onAudioDeviceChange?: (deviceId: string) => void;
+    mediaStream?: MediaStream | null;
+}
+declare function StreamingControls({ state, isVideoKey, isMuted, isVideoEnabled, facingMode: _facingMode, // Reserved for future use (e.g., showing camera direction)
+hasMultipleCameras, startTime, bytesSent, showStopConfirm, streamKey, onStreamKeyChange, onStart, onStop, onConfirmStop, onCancelStop, onToggleMute, onToggleVideo, onFlipCamera, onClose, showCloseConfirm, onConfirmClose, onCancelClose, videoDevices, audioDevices, selectedVideoDeviceId, selectedAudioDeviceId, onVideoDeviceChange, onAudioDeviceChange, mediaStream, }: StreamingControlsProps): react_jsx_runtime.JSX.Element;
+
+interface StreamKeyDisplayProps {
+    streamKey: string;
+    className?: string;
+    showLabel?: boolean;
+    showCopy?: boolean;
+    editable?: boolean;
+    onChange?: (newKey: string) => void;
+    size?: 'sm' | 'md' | 'lg';
+    layout?: 'vertical' | 'horizontal';
+    darkMode?: boolean;
+}
+/**
+ * Shared component for displaying stream keys with reveal/copy functionality
+ * Obscures the stream key by default, showing only first 6 and last 6 characters
+ * When revealed and editable, becomes an input field for editing
+ */
+declare function StreamKeyDisplay({ streamKey, className, showLabel, showCopy, editable, onChange, size, layout, darkMode, }: StreamKeyDisplayProps): react_jsx_runtime.JSX.Element;
+
+interface StreamKeyInputProps {
+    onSubmit: (key: string) => void;
+    /**
+     * When true, the input fills its parent container instead of the viewport.
+     * Use this when embedding inline within a page.
+     */
+    inline?: boolean;
+}
+/**
+ * Stream key input form for manual entry
+ * Validates stream key format before submission
+ */
+declare function StreamKeyInput({ onSubmit, inline }: StreamKeyInputProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * WebSocket streaming client for sending media chunks to encoder server
+ * Based on prankcast reference implementation
+ */
+/** Default encoder server URL */
+declare const DEFAULT_ENCODER_SERVER_URL = "https://broadcastapi.dialtribe.com";
+interface StreamDiagnostics {
+    mimeType: string | undefined;
+    chunksSent: number;
+    bytesSent: number;
+    elapsedMs: number;
+    closeCode?: number;
+    closeReason?: string;
+    lastError?: string;
+}
+interface WebSocketStreamerOptions {
+    streamKey: string;
+    mediaStream: MediaStream;
+    isVideo: boolean;
+    /** Optional custom encoder server URL (defaults to DEFAULT_ENCODER_SERVER_URL) */
+    encoderServerUrl?: string;
+    /** Disable canvas rendering (for debugging HLS issues). Disables seamless camera flips. */
+    disableCanvasRendering?: boolean;
+    onBytesUpdate?: (bytes: number) => void;
+    onStateChange?: (state: "connecting" | "live" | "stopped" | "terminated" | "error") => void;
+    onError?: (error: string, diagnostics?: StreamDiagnostics) => void;
+}
+declare class WebSocketStreamer {
+    private streamKey;
+    private mediaStream;
+    private isVideo;
+    private encoderServerUrl;
+    private disableCanvasRendering;
+    private websocket;
+    private mediaRecorder;
+    private bytesSent;
+    private chunksSent;
+    private userStopped;
+    private isHotSwapping;
+    private startTime;
+    private mimeType;
+    private onBytesUpdate?;
+    private onStateChange?;
+    private onError?;
+    private canvasState;
+    constructor(options: WebSocketStreamerOptions);
+    /**
+     * Calculate scaled dimensions for fitting video into canvas.
+     * @param mode - "contain" fits video inside canvas, "cover" fills canvas (cropping)
+     */
+    private calculateScaledDimensions;
+    /**
+     * Invalidate cached scaling dimensions (call when video source changes)
+     */
+    private invalidateScalingCache;
+    /**
+     * Validate stream key format
+     * Stream keys must follow format: {tierCode}{foreignId}_{randomKey}
+     * Tier codes: a (audio shared), b (audio VIP), v (video shared), w (video VIP)
+     */
+    private validateStreamKeyFormat;
+    /**
+     * Set up canvas-based rendering pipeline for video streams.
+     * This allows seamless camera flips by changing the video source
+     * without affecting MediaRecorder (which records from the canvas).
+     *
+     * This is async to ensure the video is producing frames before returning,
+     * which prevents black initial thumbnails.
+     */
+    private setupCanvasRendering;
+    /**
+     * Clean up canvas rendering resources
+     */
+    private cleanupCanvasRendering;
+    /**
+     * Build WebSocket URL from stream key
+     */
+    private buildWebSocketUrl;
+    /**
+     * Start streaming
+     */
+    start(): Promise<void>;
+    /**
+     * Stop streaming
+     */
+    stop(): void;
+    /**
+     * Get total bytes sent
+     */
+    getBytesSent(): number;
+    /**
+     * Get the current source media stream.
+     * This may change after replaceVideoTrack() is called.
+     */
+    getMediaStream(): MediaStream;
+    /**
+     * Get current diagnostics
+     */
+    private getDiagnostics;
+    /**
+     * Replace the video track for camera flips.
+     *
+     * When using canvas-based rendering (video streams), this preloads the new
+     * camera in a temporary video element, waits for it to be ready, then swaps
+     * it in. This ensures continuous frame output with no gaps.
+     *
+     * @param newVideoTrack - The new video track from the flipped camera
+     * @returns Promise that resolves when the swap is complete
+     */
+    replaceVideoTrack(newVideoTrack: MediaStreamTrack): Promise<void>;
+    /**
+     * Replace the audio track in the current MediaStream without stopping MediaRecorder.
+     *
+     * @param newAudioTrack - The new audio track
+     */
+    replaceAudioTrack(newAudioTrack: MediaStreamTrack): void;
+    /**
+     * Update the media stream (e.g., when switching devices from settings)
+     * This keeps the WebSocket connection alive while swapping the media source.
+     * Restarts the MediaRecorder with the new stream.
+     *
+     * Note: For camera flips, prefer replaceVideoTrack() which doesn't restart MediaRecorder.
+     * Note: Errors are thrown to the caller, not sent to onError callback.
+     */
+    updateMediaStream(newMediaStream: MediaStream): Promise<void>;
+    /**
+     * Set up WebSocket event handlers
+     */
+    private setupWebSocketHandlers;
+    /**
+     * Set up MediaRecorder event handlers
+     */
+    private setupMediaRecorderHandlers;
+}
+
+/**
+ * Media constraints for browser streaming
+ * Based on prankcast reference implementation
+ */
+interface MediaConstraintsOptions {
+    isVideo: boolean;
+    facingMode?: "user" | "environment";
+}
+declare function getMediaConstraints(options: MediaConstraintsOptions): MediaStreamConstraints;
+/**
+ * MediaRecorder options for encoding
+ */
+declare function getMediaRecorderOptions(isVideo: boolean): MediaRecorderOptions;
+/**
+ * Check browser compatibility
+ */
+declare function checkBrowserCompatibility(): {
+    compatible: boolean;
+    error?: string;
+};
+
+/**
+ * Utility functions for opening broadcast streamer popup windows
+ */
+interface PopupDimensions {
+    width: number;
+    height: number;
+    left: number;
+    top: number;
+}
+/**
+ * Calculate optimal popup dimensions based on screen size
+ * - Desktop/wider screens: 16:9 landscape ratio (e.g., 1280x720) to match modern webcams
+ * - Mobile/narrower screens: 9:16 portrait ratio (e.g., 720x1280) for vertical video
+ */
+declare function calculatePopupDimensions(): PopupDimensions;
+/**
+ * Options for opening a broadcast streamer popup window.
+ */
+interface OpenDialtribeStreamerPopupOptions {
+    /**
+     * Session token for API authentication. **Required.**
+     * The token must include `broadcasts:stream` permission.
+     * Sent securely via postMessage (not in the URL).
+     */
+    sessionToken: string;
+    /**
+     * Stream key for broadcasting. **Required for production use.**
+     * Fetch this from your backend and pass it here.
+     * The key is sent securely via postMessage (not in the URL).
+     *
+     * @example "w1_abc123def456..."
+     */
+    streamKey: string;
+    /**
+     * URL path for the streamer page. **Required.**
+     * This is the route in your app where the popup page is hosted.
+     *
+     * @example "/broadcasts/new"
+     * @example "/stream/live"
+     */
+    streamerUrl: string;
+    /** Optional app ID to include in the postMessage payload */
+    appId?: number;
+    /** Additional URL parameters to pass to the popup page */
+    additionalParams?: Record<string, string>;
+}
+/**
+ * Open broadcast streamer popup window with credentials sent via postMessage
+ * This is more secure than passing sensitive data in the URL
+ *
+ * @example
+ * ```tsx
+ * import { openDialtribeStreamerPopup } from '@dialtribe/react-sdk/dialtribe-streamer';
+ *
+ * // Open popup for live streaming
+ * openDialtribeStreamerPopup({
+ *   sessionToken: 'sess_xxx...',
+ *   streamKey: 'w1_abc123...',
+ *   streamerUrl: '/broadcasts/new',
+ * });
+ * ```
+ *
+ * @returns The popup window reference, or null if popup was blocked
+ */
+declare function openDialtribeStreamerPopup(options: OpenDialtribeStreamerPopupOptions): Window | null;
+/**
+ * Legacy function name for backwards compatibility
+ * @deprecated Use openDialtribeStreamerPopup instead
+ */
+declare const openBroadcastPopup: typeof openDialtribeStreamerPopup;
+
+/**
+ * Return value from useDialtribeStreamerPopup hook.
+ */
+interface UseDialtribeStreamerPopupReturn {
+    /**
+     * Session token received from parent window.
+     * Will be null until credentials are received via postMessage.
+     */
+    sessionToken: string | null;
+    /**
+     * Stream key received from parent window.
+     * Will be null until credentials are received via postMessage.
+     */
+    streamKey: string | null;
+    /**
+     * API base URL received from parent window.
+     * Defaults to empty string (uses SDK default).
+     */
+    apiBaseUrl: string;
+    /**
+     * Function to update the stream key.
+     * Pass this to DialtribeStreamer's onStreamKeyChange prop.
+     */
+    setStreamKey: React.Dispatch<React.SetStateAction<string | null>>;
+    /**
+     * True if credentials have been received from the parent window.
+     */
+    isReady: boolean;
+}
+/**
+ * Hook for popup pages that receive streaming credentials via postMessage.
+ *
+ * Use this in your popup page component to handle the postMessage communication
+ * with the parent window that opened the popup via `openDialtribeStreamerPopup()`.
+ *
+ * @example
+ * ```tsx
+ * import { DialtribeStreamer, useDialtribeStreamerPopup } from '@dialtribe/react-sdk/dialtribe-streamer';
+ *
+ * export default function BroadcastPopupPage() {
+ *   const { sessionToken, streamKey, apiBaseUrl, setStreamKey } = useDialtribeStreamerPopup();
+ *
+ *   return (
+ *     <DialtribeStreamer
+ *       sessionToken={sessionToken}
+ *       streamKey={streamKey}
+ *       apiBaseUrl={apiBaseUrl}
+ *       onDone={() => window.close()}
+ *       onStreamKeyChange={setStreamKey}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function useDialtribeStreamerPopup(): UseDialtribeStreamerPopupReturn;
+
+/**
+ * Fallback behavior when popup is blocked by the browser.
+ */
+type PopupFallbackMode = 'fullscreen' | 'newTab' | 'none';
+/**
+ * Options for the useDialtribeStreamerLauncher hook.
+ */
+interface UseDialtribeStreamerLauncherOptions {
+    /**
+     * Session token for API authentication.
+     */
+    sessionToken: string | null;
+    /**
+     * Stream key for broadcasting.
+     */
+    streamKey: string;
+    /**
+     * URL path for the streamer page (e.g., '/broadcasts/new').
+     */
+    streamerUrl: string;
+    /**
+     * API base URL for the streamer.
+     */
+    apiBaseUrl?: string;
+    /**
+     * What to do if the popup is blocked by the browser.
+     * - 'fullscreen': Show a fullscreen overlay in the current page
+     * - 'newTab': Open in a new browser tab (less likely to be blocked)
+     * - 'none': Do nothing, let the caller handle it
+     *
+     * @default 'fullscreen'
+     */
+    fallback?: PopupFallbackMode;
+    /**
+     * Callback when popup is blocked (called regardless of fallback mode).
+     */
+    onPopupBlocked?: () => void;
+    /**
+     * Callback when streaming ends (from fullscreen fallback mode).
+     */
+    onDone?: () => void;
+    /**
+     * Callback when stream key changes (from fallback streamer).
+     */
+    onStreamKeyChange?: (key: string) => void;
+}
+/**
+ * Return value from useDialtribeStreamerLauncher hook.
+ */
+interface UseDialtribeStreamerLauncherReturn {
+    /**
+     * Launch the streamer. Tries popup first, falls back if blocked.
+     */
+    launch: () => void;
+    /**
+     * Portal component that renders the fallback overlay.
+     * Include this once in your JSX - it renders via portal to document.body.
+     *
+     * @example
+     * ```tsx
+     * const { launch, Fallback } = useDialtribeStreamerLauncher({...});
+     * return (
+     *   <>
+     *     <button onClick={launch}>Start</button>
+     *     <Fallback />
+     *   </>
+     * );
+     * ```
+     */
+    Fallback: React$1.FC;
+    /**
+     * Whether the fallback fullscreen overlay is currently shown.
+     * Use this for custom fallback rendering.
+     */
+    showFallback: boolean;
+    /**
+     * Close the fallback overlay.
+     * Use this for custom fallback rendering.
+     */
+    closeFallback: () => void;
+    /**
+     * Reference to the popup window (if successfully opened).
+     */
+    popupRef: Window | null;
+    /**
+     * Whether the last launch attempt was blocked.
+     */
+    wasBlocked: boolean;
+}
+/**
+ * Hook for launching the DialtribeStreamer with automatic popup fallback.
+ *
+ * This hook tries to open the streamer in a popup window first. If the popup
+ * is blocked by the browser, it automatically falls back to a fullscreen
+ * overlay or new tab (configurable).
+ *
+ * @example
+ * ```tsx
+ * import { useDialtribeStreamerLauncher } from '@dialtribe/react-sdk/dialtribe-streamer';
+ *
+ * function StreamButton({ sessionToken, streamKey }: Props) {
+ *   const { launch, Fallback } = useDialtribeStreamerLauncher({
+ *     sessionToken,
+ *     streamKey,
+ *     streamerUrl: '/broadcasts/new',
+ *     fallback: 'fullscreen',
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <button onClick={launch}>Start Streaming</button>
+ *       <Fallback />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function useDialtribeStreamerLauncher(options: UseDialtribeStreamerLauncherOptions): UseDialtribeStreamerLauncherReturn;
+
+export { DialtribeStreamer as D, type MediaConstraintsOptions as M, type OpenDialtribeStreamerPopupOptions as O, type PopupDimensions as P, StreamingPreview as S, type UseDialtribeStreamerPopupReturn as U, WebSocketStreamer as W, type DialtribeStreamerProps as a, type StreamingPreviewProps as b, StreamingControls as c, type StreamingControlsProps as d, type StreamingControlState as e, StreamKeyDisplay as f, type StreamKeyDisplayProps as g, StreamKeyInput as h, type StreamKeyInputProps as i, DEFAULT_ENCODER_SERVER_URL as j, type WebSocketStreamerOptions as k, type StreamDiagnostics as l, getMediaConstraints as m, getMediaRecorderOptions as n, checkBrowserCompatibility as o, openDialtribeStreamerPopup as p, openBroadcastPopup as q, calculatePopupDimensions as r, useDialtribeStreamerLauncher as s, type UseDialtribeStreamerLauncherOptions as t, useDialtribeStreamerPopup as u, type UseDialtribeStreamerLauncherReturn as v, type PopupFallbackMode as w };