@evolve.ui/core-components 1.0.1 → 1.1.0

package/src/WebRTCPlayer/WebRTCPlayer.tsx

@@ -0,0 +1,325 @@
+import { cn } from '@evolve.ui/theme-system';
+import React, { useEffect, useMemo, useState } from 'react';
+
+import { Button } from '../Button/Button';
+import { IconButton } from '../IconButton/IconButton';
+import { ArrowSquareOut } from '../Icons';
+import { LoadingSpinner } from '../LoadingSpinner/LoadingSpinner';
+import { BodySecondary, Caption, H5 } from '../Typography/Text/Text';
+import { useWebRTCStream } from './hooks/useWebRTCStream';
+import { DEFAULT_WS_PORT, DEFAULT_WSS_PORT } from './types';
+
+export type WebRTCPlayerProps = {
+    /** Allow fullscreen mode (default: true) */
+    allowFullscreen?: boolean;
+    /** Allow picture-in-picture mode (default: true) */
+    allowPictureInPicture?: boolean;
+    /** Additional CSS classes for the container */
+    className?: string;
+    /** Test ID for testing */
+    'data-testid'?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Optional callback invoked before each reconnect attempt to obtain a fresh
+     * stream ID. A stream that restarts on the server is usually issued a new ID,
+     * so reconnecting with the original `streamId` would target a dead stream.
+     * Return the latest ID (sync or async); return a falsy value to keep the
+     * current one.
+     */
+    fetchStreamId?: () => string | Promise<string>;
+    /** WebRTC server hostname */
+    hostname: string;
+    /** Callback when user clicks the "Contact Support" button on error */
+    onContactSupportOnError?: () => void;
+    /** Callback when stream encounters an error */
+    onError?: (error: string) => void;
+    /** Callback when user enters or exits fullscreen mode */
+    onFullscreenToggle?: (isFullscreen: boolean) => void;
+    /** Callback when user clicks "open in new window" button */
+    onOpenInNewWindow?: () => void;
+    /** Callback when video is paused */
+    onPause?: () => void;
+    /** Callback when user enters or exits picture-in-picture mode */
+    onPipToggle?: (isPip: boolean) => void;
+    /** Callback when stream starts playing */
+    onPlay?: () => void;
+    /** Callback when mute state changes */
+    onToggleMute?: (isMuted: boolean) => void;
+    /** Callback when volume changes */
+    onVolumeChange?: (volume: number) => void;
+    /** Optional placeholder image URL to display before stream starts (defaults to black background) */
+    placeholderUrl?: string;
+    /**
+     * Show native HTML5 video controls bar (default: true).
+     * Set to `false` for compact surfaces where the host app renders custom controls (e.g. mute, expand).
+     */
+    showControls?: boolean;
+    /** Stream ID from Ant Media Server */
+    streamId: string;
+    /** WebSocket port for non-SSL connections (defaults to 5080) */
+    wsPort?: number;
+    /** WebSocket port for SSL connections (defaults to 5443) */
+    wssPort?: number;
+};
+
+/**
+ * WebRTC video player component for streaming from Ant Media Server
+ *
+ * This component provides a simple interface for playing live WebRTC streams from
+ * Ant Media Server. It handles connection management, error recovery, and provides
+ * a clean UI with loading states and error messages.
+ *
+ * Features:
+ * - Automatic connection to Ant Media Server
+ * - Loading spinner while connecting
+ * - Error state display with automatic reconnection
+ * - Native HTML5 video controls with volume, fullscreen, and picture-in-picture
+ * - Responsive container with aspect ratio preservation
+ * - Configurable hostname and ports for different server setups
+ *
+ * @example
+ * ```tsx
+ * <WebRTCPlayer
+ *   hostname="media.example.com"
+ *   streamId="my-stream-id"
+ *   onPlay={() => console.log('Stream started')}
+ *   onError={(error) => console.error('Stream error:', error)}
+ * />
+ * ```
+ *
+ * @example Custom server configuration
+ * ```tsx
+ * <WebRTCPlayer
+ *   streamId="my-stream-id"
+ *   hostname="custom-server.com"
+ *   wsPort={8080}
+ *   wssPort={8443}
+ * />
+ * ```
+ */
+export const WebRTCPlayer = ({
+    allowFullscreen = true,
+    allowPictureInPicture = true,
+    className,
+    'data-testid': testid = 'webrtc-player',
+    debug = false,
+    fetchStreamId,
+    hostname,
+    onContactSupportOnError,
+    onError,
+    onFullscreenToggle,
+    onOpenInNewWindow,
+    onPause,
+    onPipToggle,
+    onPlay,
+    onToggleMute,
+    onVolumeChange,
+    placeholderUrl,
+    showControls = true,
+    streamId,
+    wsPort = DEFAULT_WS_PORT,
+    wssPort = DEFAULT_WSS_PORT,
+}: WebRTCPlayerProps) => {
+    const { connectionState, error, loading, videoRef } = useWebRTCStream({
+        debug,
+        fetchStreamId,
+        hostname,
+        streamId,
+        wsPort,
+        wssPort,
+    });
+
+    const [showContent, setShowContent] = useState(false);
+    const hasUserInteractedRef = React.useRef(false);
+
+    const controlsList = useMemo(
+        () => [!allowFullscreen && 'nofullscreen', 'nodownload'].filter(Boolean).join(' ') || undefined,
+        [allowFullscreen]
+    );
+
+    // Track when user has hovered over the video
+    const handleUserInteraction = () => {
+        hasUserInteractedRef.current = true;
+    };
+
+    // Trigger fade-in animation when loading completes
+    useEffect(() => {
+        if (!loading) {
+            // Small delay to ensure smooth transition
+            const timer = setTimeout(() => setShowContent(true), 50);
+            return () => clearTimeout(timer);
+        }
+        setShowContent(false);
+        return undefined;
+    }, [loading]);
+
+    // Call onError callback when an error occurs
+    useEffect(() => {
+        if (error && onError) {
+            onError(error);
+        }
+    }, [error, onError]);
+
+    // Listen for fullscreen changes
+    useEffect(() => {
+        if (!onFullscreenToggle || !allowFullscreen) {
+            return;
+        }
+
+        const handleFullscreenChange = () => {
+            if (!hasUserInteractedRef.current) {
+                return;
+            }
+            const isFullscreen = Boolean(document.fullscreenElement);
+            onFullscreenToggle(isFullscreen);
+        };
+
+        document.addEventListener('fullscreenchange', handleFullscreenChange);
+        return () => {
+            document.removeEventListener('fullscreenchange', handleFullscreenChange);
+        };
+    }, [allowFullscreen, onFullscreenToggle]);
+
+    // Listen for picture-in-picture changes
+    useEffect(() => {
+        const video = videoRef.current;
+        if (!onPipToggle || !allowPictureInPicture || !Boolean(video)) {
+            return;
+        }
+
+        const handleEnterPip = () => {
+            if (!hasUserInteractedRef.current) {
+                return;
+            }
+            onPipToggle(true);
+        };
+        const handleLeavePip = () => {
+            if (!hasUserInteractedRef.current) {
+                return;
+            }
+            onPipToggle(false);
+        };
+
+        video.addEventListener('enterpictureinpicture', handleEnterPip);
+        video.addEventListener('leavepictureinpicture', handleLeavePip);
+
+        return () => {
+            video.removeEventListener('enterpictureinpicture', handleEnterPip);
+            video.removeEventListener('leavepictureinpicture', handleLeavePip);
+        };
+    }, [allowPictureInPicture, onPipToggle, videoRef]);
+
+    return (
+        <div
+            className={cn(
+                'relative w-full overflow-hidden rounded-container bg-background-inverse',
+                'aspect-video', // 16:9 aspect ratio
+                className
+            )}
+            data-testid={testid}
+        >
+            {/* eslint-disable-next-line jsx-a11y/media-has-caption */}
+            <video
+                aria-label="Live video stream"
+                autoPlay
+                className={cn(
+                    'h-full w-full object-cover transition-opacity duration-300',
+                    showContent && !error ? 'opacity-100' : 'opacity-0'
+                )}
+                controls={showControls}
+                controlsList={controlsList}
+                disablePictureInPicture={!allowPictureInPicture}
+                muted
+                onMouseEnter={handleUserInteraction}
+                onPause={() => {
+                    if (!hasUserInteractedRef.current) {
+                        return;
+                    }
+                    onPause?.();
+                }}
+                onPlay={() => {
+                    if (!hasUserInteractedRef.current) {
+                        return;
+                    }
+                    onPlay?.();
+                }}
+                onTouchStart={handleUserInteraction}
+                onVolumeChange={(e: React.SyntheticEvent<HTMLVideoElement>) => {
+                    if (!hasUserInteractedRef.current) {
+                        return;
+                    }
+                    const video = e.currentTarget;
+                    onVolumeChange?.(video.volume);
+                    onToggleMute?.(video.muted);
+                }}
+                playsInline
+                poster={placeholderUrl}
+                ref={videoRef}
+            >
+                <track kind="captions" />
+            </video>
+
+            {onOpenInNewWindow && !error && !loading && (
+                <IconButton
+                    aria-label="Open in new window"
+                    className="absolute right-xs top-xs z-10"
+                    data-testid={`${testid}-open-in-new-window`}
+                    icon={ArrowSquareOut}
+                    onClick={onOpenInNewWindow}
+                    shape="circle"
+                    size="sm"
+                    style="inverse"
+                    variant="transparent"
+                />
+            )}
+
+            {/* Loading overlay */}
+            {loading && (
+                <div
+                    className="absolute inset-0 flex items-center justify-center"
+                    data-testid={`${testid}-loading`}
+                >
+                    <LoadingSpinner
+                        color="inverse"
+                        size="md"
+                    />
+                </div>
+            )}
+
+            {/* Error overlay */}
+            {error && !loading && (
+                <div
+                    className={cn(
+                        'absolute inset-0 flex w-full flex-col items-center justify-center p-sm transition-opacity duration-300',
+                        showContent ? 'opacity-100' : 'opacity-0'
+                    )}
+                    data-testid={`${testid}-error`}
+                >
+                    <div className="flex w-full flex-col items-center justify-center gap-xs text-center">
+                        <H5 color="inverse">Connection Error</H5>
+                        <BodySecondary color="inverse">{error}</BodySecondary>
+                        {onContactSupportOnError && (
+                            <Button
+                                onClick={onContactSupportOnError}
+                                size="sm"
+                                style="inverse"
+                                variant="outlined"
+                            >
+                                Contact Support
+                            </Button>
+                        )}
+                        {connectionState === 'reconnecting' && (
+                            <Caption
+                                className="mt-sm"
+                                color="inverse"
+                            >
+                                Attempting to reconnect...
+                            </Caption>
+                        )}
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+};