@cinecrew/cinecrew-player 0.1.5 → 0.1.7

package/src/web/index.js

@@ -1,13 +1,17 @@
 import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { useWebVideoAspectRatio } from '../native/media/web/useWebVideoAspectRatio';
 import { useWebMpegTsPlayback } from '../native/media/web/useWebMpegTsPlayback.web';
+import { useWebFlvPlayback } from '../native/media/web/useWebFlvPlayback.web';
 import { useWebHlsPlayback } from '../native/media/web/useWebHlsPlayback.web';
+import { useWebDashPlayback } from '../native/media/web/useWebDashPlayback.web';
+import { useWebOgvPlayback } from '../native/media/web/useWebOgvPlayback.web';
 import { useWebAc3AudioPlayback } from '../native/media/web/useWebAc3AudioPlayback.web';
 import { getWebRuntimePlatform, useResolvedPlayerSource } from '../utils/sourceUtils';
 import { EMOJI_GROUPS, searchEmojis } from '../data/emoji';
 import { createRecordingDownloadLink, createVideoRecordingStream, createScreenRecordingStream, downloadRecording, getRecordingMimeType } from '../utils/webRecording';
 import { invokePlayerAction } from '../utils/invokePlayerAction.js';
 import { emitProgressBarTime } from '../utils/progressBarTime.js';
+import { getPlayerErrorMessage } from '../utils/playerError.js';
 import './styles.css';
 
 const h = React.createElement;
@@ -311,19 +315,10 @@ function WebBottomControls(props) {
 
 function getRecordingOverlayContent({ status, elapsed, error, downloadLink, onPause, onResume, onStop, onDownload, onDismiss }) {
   if (status === 'complete') {
-    const children = [];
-    if (error) children.push(h('span', null, error));
-    children.push(h('strong', { className: 'cinecrew-player__recording-ready' }, 'Recording ready'));
-    if (downloadLink) {
-      children.push(h('a', {
-        className: 'cinecrew-player__recording-download',
-        href: downloadLink.url,
-        download: downloadLink.filename,
-        onClick: onDownload,
-      }, 'Download recording'));
-    }
-    children.push(h('button', { type: 'button', onClick: onDismiss, 'aria-label': 'Dismiss recording controls' }, 'Done'));
-    return h(React.Fragment, null, ...children);
+    return h(React.Fragment, null,
+      error ? h('span', null, error) : null,
+      h('strong', { className: 'cinecrew-player__recording-ready' }, 'Recording ready'),
+      h('button', { type: 'button', onClick: onDismiss, 'aria-label': 'Dismiss recording controls' }, 'Done'));
   }
   if (status === 'finalizing') {
     return h('strong', { className: 'cinecrew-player__recording-ready' }, 'Preparing recording…');
@@ -394,6 +389,51 @@ function WebPlayerControls({ locked, buffering, overrides, theme, icons, unlocke
     bottomControls);
 }
 
+function getDrawerResizedVideoStyle(drawerResize, videoStyle) {
+  if (!drawerResize) return {};
+  if (videoStyle.width === 'auto') {
+    return {
+      left: 'calc(var(--cinecrew-media-width, 64%) / 2)',
+      top: '50%',
+      right: 'auto',
+      bottom: 'auto',
+      maxWidth: 'var(--cinecrew-media-width, 64%)',
+      transform: 'translate(-50%, -50%)',
+    };
+  }
+  return {
+    width: 'var(--cinecrew-media-width, 64%)',
+    height: '100%',
+    left: 0,
+    top: 0,
+    right: 'auto',
+    bottom: 0,
+    transform: 'none',
+  };
+}
+
+function getVideoSurfaceStyle(videoStyle, resizedVideoStyle, audioOnly) {
+  return {
+    ...videoStyle,
+    ...resizedVideoStyle,
+    opacity: audioOnly ? 0 : 1,
+  };
+}
+
+function getOgvStageStyle(drawerResize, audioOnly) {
+  return {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: drawerResize ? 'auto' : 0,
+    bottom: 0,
+    width: drawerResize ? 'var(--cinecrew-media-width, 64%)' : '100%',
+    height: '100%',
+    backgroundColor: '#000',
+    opacity: audioOnly ? 0 : 1,
+  };
+}
+
 function WebPlayerSurface({
   title,
   streamUrl,
@@ -419,30 +459,40 @@ function WebPlayerSurface({
   onError,
   handleError,
   corsMode,
+  useOgv,
+  mediaType,
+  ogvResourceBase,
+  pausedRef,
+  onErrorRef,
 }) {
+  const ogvContainerRef = useRef(null);
+  useWebOgvPlayback({
+    activeUrl: streamUrl,
+    type: mediaType,
+    videoRef,
+    playerContainerRef: ogvContainerRef,
+    playerStyle: videoStyle,
+    pausedRef,
+    onErrorRef,
+    onBufferingRef: bufferingRef,
+    resourceBase: ogvResourceBase,
+  });
   if (!streamUrl) return h('div', { className: 'cinecrew-player__empty' });
-  let resizedVideoStyle = {};
-  if (drawerResize && videoStyle.width === 'auto') {
-    resizedVideoStyle = {
-      left: 'calc(var(--cinecrew-media-width, 64%) / 2)',
-      top: '50%',
-      right: 'auto',
-      bottom: 'auto',
-      maxWidth: 'var(--cinecrew-media-width, 64%)',
-      transform: 'translate(-50%, -50%)',
-    };
-  } else if (drawerResize) {
-    resizedVideoStyle = {
-      width: 'var(--cinecrew-media-width, 64%)',
-      height: '100%',
-      left: 0,
-      top: 0,
-      right: 'auto',
-      bottom: 0,
-      transform: 'none',
-    };
+  const resizedVideoStyle = getDrawerResizedVideoStyle(drawerResize, videoStyle);
+  const surfaceStyle = getVideoSurfaceStyle(videoStyle, resizedVideoStyle, audioOnly);
+  if (useOgv) {
+    return h('div', {
+      ref: ogvContainerRef,
+      className: 'cinecrew-player__video',
+      style: getOgvStageStyle(drawerResize, audioOnly),
+      onClick: inlinePreview ? onPromotePreview : undefined,
+      'data-stream-mode': 'ogv',
+    });
   }
   return h('video', {
+    // MSE-backed engines (HLS, DASH, MPEG-TS, FLV) own this element. Changing
+    // the CORS mode must not replace it after an engine has attached to it.
+    key: directVideoSource ? `${directVideoSource}:${corsMode || 'nocors'}` : 'managed-media',
     ref: videoRef,
     className: 'cinecrew-player__video',
     src: directVideoSource,
@@ -452,11 +502,7 @@ function WebPlayerSurface({
     playsInline: true,
     preload: 'auto',
     crossOrigin: corsMode,
-    style: {
-      ...videoStyle,
-      ...resizedVideoStyle,
-      opacity: audioOnly ? 0 : 1,
-    },
+    style: surfaceStyle,
     onClick: inlinePreview ? onPromotePreview : undefined,
     onError: (event) => {
       if (!directVideoSource) return;
@@ -466,7 +512,8 @@ function WebPlayerSurface({
   });
 }
 
-function WebAudioOnlyCard({ poster, title, theme, icons, onSwitchToVideo }) {
+function WebAudioOnlyCard({ poster, title, theme, icons, onSwitchToVideo, hasVideo, isPaused }) {
+  const bars = [1, 2, 3, 4, 5, 6, 7];
   return h('div', {
     className: 'cinecrew-player__audio-card',
     style: { background: '#07090E', color: theme.controlColor, borderColor: theme.accentColor },
@@ -475,13 +522,18 @@ function WebAudioOnlyCard({ poster, title, theme, icons, onSwitchToVideo }) {
     ? h('img', { className: 'cinecrew-player__audio-poster', src: poster, alt: '' })
     : h('div', { className: 'cinecrew-player__audio-placeholder', role: 'img', 'aria-label': 'Audio artwork placeholder' },
       h(Icon, { name: 'audioOnly', icons, color: theme.accentColor })),
-  h('span', { className: 'cinecrew-player__audio-wave', style: { color: theme.accentColor }, 'aria-hidden': true }, '•••••••'),
+  h('div', {
+    className: `cinecrew-player__audio-wave${!isPaused ? ' is-playing' : ''}`,
+    'aria-hidden': true,
+  }, bars.map((b) => h('span', { key: b, style: { background: theme.accentColor } }))),
   h('strong', null, title || 'Audio only'),
-  h('button', {
-    type: 'button',
-    onClick: onSwitchToVideo,
-    style: { color: theme.accentColor, borderColor: theme.accentColor },
-  }, 'Switch to video'));
+  hasVideo && onSwitchToVideo
+    ? h('button', {
+      type: 'button',
+      onClick: onSwitchToVideo,
+      style: { color: theme.accentColor, borderColor: theme.accentColor },
+    }, 'Switch to video')
+    : null);
 }
 
 function WebPlayerError({ error, theme, renderBackButton }) {
@@ -492,8 +544,8 @@ function WebPlayerError({ error, theme, renderBackButton }) {
     renderBackButton());
 }
 
-function getDirectVideoSource({ mpegTs, useHls, sourceType, activeUrl }) {
-  if (mpegTs || useHls || /mpegurl|mpeg-ts/.test(sourceType)) return undefined;
+function getDirectVideoSource({ mpegTs, useHls, useDash, useOgv, sourceType, activeUrl }) {
+  if (mpegTs || useHls || useDash || useOgv || /mpegurl|mpeg-ts|dash|flv|video\/ogg|ogv/.test(sourceType)) return undefined;
   return activeUrl;
 }
 
@@ -522,6 +574,9 @@ function stopBrowserRecorder(recorderRef, completionRef, finalizerRef) {
       return;
     }
     recorder.addEventListener('error', (event) => reject(event.error || new Error('Recording failed.')), { once: true });
+    try {
+      if (recorder.state === 'recording') recorder.requestData();
+    } catch {}
     recorder.stop();
     if (completion) completion.then(resolve, reject);
     else resolve();
@@ -543,16 +598,21 @@ async function performRecordingStop({ stop, action, recordingElapsed, streamUrl,
   let stopCore = () => stopBrowserRecorder(recorderRef, completionRef, finalizerRef);
   if (stop) stopCore = () => stop();
   await action('onRecordingStop', stopCore, { elapsedMs: recordingElapsed, source: streamUrl, title });
-  if (!stop) await waitForRecordingFinalization(completionRef.current);
+  if (!stop) return await waitForRecordingFinalization(completionRef.current);
+  return null;
 }
 
-function updateRecordingStopState({ clock, recordingBlobRef, stop, setRecordingElapsed, setRecordingStatus, setRecordingError }) {
+function updateRecordingStopState({ clock, completedBlob, stop, setRecordingElapsed, setRecordingStatus, setRecordingError }) {
   if (clock.startedAt) clock.accumulatedMs += Date.now() - clock.startedAt;
   setRecordingElapsed(clock.accumulatedMs);
-  const hasRecording = Boolean(recordingBlobRef.current);
-  setRecordingStatus(hasRecording ? 'complete' : 'idle');
-  if (!hasRecording && !stop) {
+  if (completedBlob) {
+    setRecordingStatus('idle');
+    setRecordingError('');
+  } else if (!stop) {
+    setRecordingStatus('idle');
     setRecordingError((current) => current || 'The browser returned no recorded media data for this source. Try a local or CORS-enabled video while it is playing.');
+  } else {
+    setRecordingStatus('idle');
   }
 }
 
@@ -614,7 +674,7 @@ function getPlaybackStatus(error, buffering, paused) {
 
 function WebPlayerLayout(props) {
   let controlLayer = null;
-  if (!props.error && !props.audioOnly) {
+  if (!props.error) {
     controlLayer = h(WebPlayerControls, {
       locked: props.locked,
       buffering: props.buffering,
@@ -633,11 +693,19 @@ function WebPlayerLayout(props) {
   let loadingNotice = null;
   if (props.buffering && !props.error) {
     loadingNotice = h('div', { className: 'cinecrew-player__status', style: { color: props.theme.controlColor } },
-      h('span', { className: 'cinecrew-player__spinner', style: { borderTopColor: props.theme.accentColor } }), 'Loading stream…')
+      h('span', { className: 'cinecrew-player__spinner', style: { borderTopColor: props.theme.accentColor } }), 'Loading stream…');
   }
   let audioCard = null;
   if (props.audioOnly) {
-    audioCard = h(WebAudioOnlyCard, { poster: props.poster, title: props.title, theme: props.theme, icons: props.icons, onSwitchToVideo: props.onSwitchToVideo });
+    audioCard = h(WebAudioOnlyCard, {
+      poster: props.poster,
+      title: props.title,
+      theme: props.theme,
+      icons: props.icons,
+      onSwitchToVideo: props.onSwitchToVideo,
+      hasVideo: props.hasVideo,
+      isPaused: props.isPaused,
+    });
   }
   let panelNode = null;
   if (props.activePanel && props.webPanel) {
@@ -649,23 +717,26 @@ function WebPlayerLayout(props) {
   }
   return h('div', {
     ref: props.playerRef,
-    className: `cinecrew-player${props.inlinePreview ? ' cinecrew-player--inline-preview' : ''}${props.drawerMode === 'resize' && props.activePanel ? ' cinecrew-player--drawer-resize' : ''} ${props.className}`.trim(),
+    className: `cinecrew-player${props.audioOnly ? ' cinecrew-player--audio-mode' : ''}${props.inlinePreview ? ' cinecrew-player--inline-preview' : ''}${props.drawerMode === 'resize' && props.activePanel ? ' cinecrew-player--drawer-resize' : ''} ${props.className}`.trim(),
     style: { ...props.rootStyle, ...props.style, background: props.theme.backgroundColor, borderRadius: props.theme.borderRadius, '--cinecrew-accent': props.theme.accentColor, '--cinecrew-text': props.theme.controlColor, '--cinecrew-surface': props.theme.surfaceColor, '--cinecrew-media-width': '64%' },
     onWheel: props.onWheel,
     'data-stream-mode': props.streamMode,
   },
   props.mediaSurface,
+  audioCard,
   h('div', { className: 'cinecrew-player__shade', style: { background: 'linear-gradient(180deg, rgba(0,0,0,.48), transparent 28%, transparent 68%, rgba(0,0,0,.64))' } }),
   loadingNotice,
   h(WebPlayerError, { error: props.error, theme: props.theme, renderBackButton: props.locked ? () => null : props.renderBackButton }),
   controlLayer,
-  audioCard,
   panelNode);
 }
 
-function getStreamMode(mpegTs, useHls) {
+function getStreamMode({ mpegTs, isFlv, useHls, useDash, useOgv }) {
+  if (isFlv) return 'flv';
   if (mpegTs) return 'mpegts';
   if (useHls) return 'hls';
+  if (useDash) return 'dash';
+  if (useOgv) return 'ogv';
   return 'native';
 }
 
@@ -1231,7 +1302,7 @@ export const CineCrewPlayer = forwardRef(function CineCrewPlayer(props, ref) {
 
   const handleError = useCallback((detail) => {
     const message = typeof detail === 'string' ? detail : detail?.message || 'Unable to play this media source.';
-    // If the video failed while crossOrigin="anonymous" was set, retry without
+    // If playback failed while crossOrigin="anonymous" was set, retry without
     // CORS so playback still works (recording will fall back to screen capture).
     if (detail?.isCorsCandidate && corsModeRef.current === 'anonymous') {
       setCorsMode(undefined);
@@ -1240,7 +1311,16 @@ export const CineCrewPlayer = forwardRef(function CineCrewPlayer(props, ref) {
     }
     setError(message);
     setBuffering(false);
-    errorRef.current?.(detail instanceof Error ? detail : { ...detail, message });
+    if (detail instanceof Error) {
+      errorRef.current?.(detail);
+      return;
+    }
+    const actualMessage = getPlayerErrorMessage(detail);
+    errorRef.current?.({
+      ...detail,
+      message,
+      ...(actualMessage ? { actualMessage } : {}),
+    });
   }, []);
   const onErrorRef = useRef(handleError);
   onErrorRef.current = handleError;
@@ -1312,6 +1392,19 @@ export const CineCrewPlayer = forwardRef(function CineCrewPlayer(props, ref) {
     onErrorRef,
     onBufferingRef,
   });
+  const useFlv = useWebFlvPlayback({
+    activeUrl,
+    type: media.type || media.mimeType,
+    isLive,
+    videoRef,
+    pausedRef: pausedStateRef,
+    onErrorRef,
+    onBufferingRef,
+    onAutoplayBlocked: () => {
+      pausedStateRef.current = true;
+      setIsPaused(true);
+    },
+  });
   const useHls = useWebHlsPlayback({
     activeUrl,
     isLive,
@@ -1319,7 +1412,22 @@ export const CineCrewPlayer = forwardRef(function CineCrewPlayer(props, ref) {
     pausedRef: pausedStateRef,
     onErrorRef,
   });
-  const streamMode = getStreamMode(mpegTs.useMpegTs, useHls);
+  const useDash = useWebDashPlayback({
+    activeUrl,
+    type: media.type || media.mimeType,
+    videoRef,
+    pausedRef: pausedStateRef,
+    onErrorRef,
+  });
+  const useOgv = Boolean(/\.ogv(?:$|[?#])/i.test(activeUrl)
+    || /(?:video\/ogg|\bogv\b)/i.test(String(media.type || media.mimeType || '')));
+  const streamMode = getStreamMode({
+    mpegTs: mpegTs.useMpegTs,
+    isFlv: mpegTs.isFlv,
+    useHls,
+    useDash,
+    useOgv,
+  });
   const ac3AudioPlayback = useWebAc3AudioPlayback({
     active: mpegTs.useAc3Fallback,
     streamUrl,
@@ -1328,17 +1436,39 @@ export const CineCrewPlayer = forwardRef(function CineCrewPlayer(props, ref) {
     volume: volume * 100,
     videoRef,
   });
+  const isManagedPlayback = mpegTs.useMpegTs || useFlv || useHls || useDash || useOgv;
 
   useEffect(() => {
     const video = videoRef.current;
     if (!video) return;
-    if (isPaused) video.pause();
-    else video.play().catch((playError) => {
-      if (playError?.name !== 'NotAllowedError' && playError?.name !== 'AbortError') {
-        handleError(playError);
+    if (isPaused) {
+      video.pause();
+    } else if (isManagedPlayback && video.readyState < 2) {
+      // Let the streaming engine start playback once its MediaSource has
+      // produced a decodable frame. Calling play() before then can reject and
+      // incorrectly trigger the native-source CORS retry path.
+      return;
+    } else {
+      const playPromise = video.play();
+      if (playPromise !== undefined) {
+        playPromise.catch((playError) => {
+          if (playError?.name === 'NotAllowedError') {
+            if (useFlv) {
+              video.pause();
+              pausedStateRef.current = true;
+              setIsPaused(true);
+            } else {
+              video.muted = true;
+              setMuted(true);
+              video.play().catch(() => {});
+            }
+          } else if (playError?.name !== 'AbortError') {
+            handleError({ message: playError?.message || 'Unable to start playback.', err: playError });
+          }
+        });
       }
-    });
-  }, [isPaused, streamUrl, handleError]);
+    }
+  }, [isPaused, streamUrl, corsMode, handleError, isManagedPlayback, useFlv]);
 
   useEffect(() => {
     const video = videoRef.current;
@@ -1375,14 +1505,15 @@ export const CineCrewPlayer = forwardRef(function CineCrewPlayer(props, ref) {
 
   const startBuiltinRecording = useCallback(async () => {
     const video = videoRef.current;
-    const mimeType = getRecordingMimeType();
-    if (typeof MediaRecorder === 'undefined' || !mimeType) throw new Error('This browser does not support WebM audio/video recording.');
     if (!video) throw new Error('The media element is not ready to record.');
     let capture = createVideoRecordingStream(video, playerRef.current, () => aspectRatioRef.current, ac3AudioPlayback.getRecordingAudioStream());
     // Fallback: if direct capture failed (CORS / tainted), use screen capture.
     if (!capture) {
       capture = await createScreenRecordingStream();
     }
+    const hasAudio = Boolean(capture.stream?.getAudioTracks?.().length);
+    const mimeType = getRecordingMimeType(hasAudio);
+    if (typeof MediaRecorder === 'undefined' || !mimeType) throw new Error('This browser does not support WebM audio/video recording.');
     const recorder = new MediaRecorder(capture.stream, { mimeType });
     recordingCaptureRef.current = capture;
     recordingChunksRef.current = [];
@@ -1404,11 +1535,18 @@ export const CineCrewPlayer = forwardRef(function CineCrewPlayer(props, ref) {
         if (!downloadLink) throw new Error('The recording is empty. Play the video briefly, then stop and download again.');
         recordingDownloadLinkRef.current = downloadLink;
         setRecordingDownloadLink(downloadLink);
-        setRecordingStatus('complete');
         try {
-          if (!downloadRecording(blob, title)) throw new Error('The browser did not start the recording download. Use Download recording to retry.');
+          if (!downloadRecording(blob, title)) throw new Error('The browser did not start the recording download. Try a local or CORS-enabled source.');
+          // Auto-dismiss back to idle after a successful download.
+          setRecordingStatus('idle');
+          setRecordingError('');
+          recordingBlobRef.current = null;
+          if (recordingDownloadLinkRef.current?.url) URL.revokeObjectURL(recordingDownloadLinkRef.current.url);
+          recordingDownloadLinkRef.current = null;
+          setRecordingDownloadLink(null);
         } catch (downloadError) {
-          setRecordingError(downloadError?.message || 'The recording could not be downloaded. Use Download recording to retry.');
+          setRecordingError(downloadError?.message || 'The recording could not be downloaded.');
+          setRecordingStatus('idle');
         }
       } catch (error_) {
         setRecordingError(error_?.message || 'Could not finish the recording.');
@@ -1491,7 +1629,7 @@ export const CineCrewPlayer = forwardRef(function CineCrewPlayer(props, ref) {
   const stopRecording = useCallback(async () => {
     try {
       const stop = integrations.recording?.stop;
-      await performRecordingStop({
+      const completedBlob = await performRecordingStop({
         stop,
         action,
         recordingElapsed,
@@ -1504,7 +1642,7 @@ export const CineCrewPlayer = forwardRef(function CineCrewPlayer(props, ref) {
       });
       updateRecordingStopState({
         clock: recordingClockRef.current,
-        recordingBlobRef,
+        completedBlob,
         stop,
         setRecordingElapsed,
         setRecordingStatus,
@@ -1616,8 +1754,10 @@ export const CineCrewPlayer = forwardRef(function CineCrewPlayer(props, ref) {
   const hasDiagnostics = Boolean(features.diagnostics) || typeof actions.onDiagnosticsOpen === 'function';
   const sourceType = String(media.type || media.mimeType || '').toLowerCase();
   const directVideoSource = getDirectVideoSource({
-    mpegTs: mpegTs.useMpegTs,
+    mpegTs: mpegTs.useMpegTs || useFlv,
     useHls,
+    useDash,
+    useOgv,
     sourceType,
     activeUrl,
   });
@@ -1758,6 +1898,11 @@ export const CineCrewPlayer = forwardRef(function CineCrewPlayer(props, ref) {
     onError: handleError,
     handleError,
     corsMode,
+    useOgv,
+    mediaType: media.type || media.mimeType,
+    ogvResourceBase: props.ogvResourceBase,
+    pausedRef: pausedStateRef,
+    onErrorRef,
   });
   const bottomControlProps = {
     isLive,
@@ -1812,6 +1957,7 @@ export const CineCrewPlayer = forwardRef(function CineCrewPlayer(props, ref) {
     error,
     buffering,
     audioOnly,
+    hasVideo: !audioOnly,
     activePanel,
     webPanel,
     renderBackButton: () => control('back', 'Close player', () => action('onBack', undefined, { title, source: media }), { icon: 'close' }),

package/src/web/styles.css

@@ -273,13 +273,13 @@
 .cinecrew-player__audio-card {
   position: absolute;
   inset: 0;
-  z-index: 5;
+  z-index: 2;
   box-sizing: border-box;
   display: flex;
   flex-direction: column;
   align-items: center;
   justify-content: center;
-  gap: 18px;
+  gap: 16px;
   padding: 24px;
   border: 1px solid;
   border-radius: inherit;
@@ -287,6 +287,10 @@
   box-shadow: 0 18px 60px rgba(0, 0, 0, .32);
 }
 
+.cinecrew-player--audio-mode .cinecrew-player__controls {
+  opacity: 1;
+}
+
 .cinecrew-player__audio-poster {
   width: min(30vw, 160px);
   aspect-ratio: 1;
@@ -312,8 +316,37 @@
 }
 
 .cinecrew-player__audio-wave {
-  letter-spacing: .28em;
-  font-size: 1.25rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 5px;
+  height: 24px;
+}
+
+.cinecrew-player__audio-wave span {
+  display: inline-block;
+  width: 4px;
+  height: 8px;
+  border-radius: 2px;
+  background: var(--cinecrew-accent, #00E5FF);
+  transition: height 0.2s ease, opacity 0.2s ease;
+}
+
+.cinecrew-player__audio-wave.is-playing span {
+  animation: cinecrew-audio-bar 0.9s ease-in-out infinite alternate;
+}
+
+.cinecrew-player__audio-wave.is-playing span:nth-child(1) { height: 14px; animation-delay: 0.1s; }
+.cinecrew-player__audio-wave.is-playing span:nth-child(2) { height: 22px; animation-delay: 0.3s; }
+.cinecrew-player__audio-wave.is-playing span:nth-child(3) { height: 10px; animation-delay: 0.5s; }
+.cinecrew-player__audio-wave.is-playing span:nth-child(4) { height: 24px; animation-delay: 0.2s; }
+.cinecrew-player__audio-wave.is-playing span:nth-child(5) { height: 16px; animation-delay: 0.4s; }
+.cinecrew-player__audio-wave.is-playing span:nth-child(6) { height: 20px; animation-delay: 0.6s; }
+.cinecrew-player__audio-wave.is-playing span:nth-child(7) { height: 12px; animation-delay: 0.15s; }
+
+@keyframes cinecrew-audio-bar {
+  0% { transform: scaleY(0.35); opacity: 0.45; }
+  100% { transform: scaleY(1.25); opacity: 1; }
 }
 
 .cinecrew-player__audio-card strong {

package/types/index.d.ts

@@ -80,6 +80,20 @@ export interface PlayerActionContext {
   video?: unknown | null;
 }
 
+/** Structured playback failure. `message` is suitable for the player UI; `actualMessage` and `cause`/`err` preserve the underlying engine diagnostic when available. */
+export interface PlayerErrorDetails {
+  message: string;
+  actualMessage?: string;
+  cause?: unknown;
+  err?: unknown;
+  errorType?: string;
+  errorDetail?: string;
+  httpStatus?: number | null;
+  [key: string]: unknown;
+}
+
+export type PlayerError = Error | PlayerErrorDetails;
+
 /** App callback for a player action. Back is app-owned and has no built-in behavior. */
 export type PlayerAction = (payload?: Record<string, unknown>, context?: PlayerActionContext) => unknown;
 
@@ -234,6 +248,8 @@ export interface CineCrewPlayerProps {
   videoOnly?: boolean;
   /** Optional resolver for share pages or other non-media links. */
   resolveSource?: (source: PlayerSource, context: { platform: 'web' | 'native' | 'electron' }) => PlayerSource | string | Promise<PlayerSource | string>;
+  /** Optional base URL for ogv.js worker/WASM assets; defaults to the versioned jsDelivr distribution. */
+  ogvResourceBase?: string;
   audioTracks?: AudioTrack[];
   selectedAudioTrack?: string | number;
   resumePosition?: number;
@@ -265,7 +281,8 @@ export interface CineCrewPlayerProps {
   onProgressBarChange?: (time: string) => void;
   onPlaying?: (event: unknown) => void;
   onBuffering?: (buffering: boolean) => void;
-  onError?: (error: Error | Record<string, unknown>) => void;
+  /** Receives the player-facing error plus the underlying engine diagnostic (`actualMessage`, `cause`, `err`) when available. */
+  onError?: (error: PlayerError) => void;
   onEnded?: () => void;
   onPlaybackRoute?: (url: string) => void;
   onNextEpisode?: (episode: Record<string, unknown>) => void;
@@ -292,7 +309,8 @@ export interface InlineLivePlayerProps {
   icons?: PlayerIcons;
   style?: unknown;
   initialMuted?: boolean;
-  onError?: (error: Error | Record<string, unknown>) => void;
+  /** Receives the player-facing error plus the underlying engine diagnostic (`actualMessage`, `cause`, `err`) when available. */
+  onError?: (error: PlayerError) => void;
   onPlaying?: (event: unknown) => void;
 }