@cinecrew/cinecrew-player 0.1.3 → 0.1.5

package/README.md

@@ -52,8 +52,8 @@ flowchart LR
 
 | Area | Included capabilities | Designed for |
 |---|---|---|
-| 🎞️ **Playback** | On-demand and live media; URLs and local URIs; HLS and MPEG-TS paths on web; native VLC path; embedded YouTube playback | Movies, episodes, trailers, and channels |
-| 🎛️ **Player controls** | Play/pause, seek, restart, mute, aspect ratio, lock, video-only/audio-only modes, audio tracks, playback speed, fullscreen, back | A complete control surface without hard-wiring your app navigation |
+| 🎞️ **Playback** | On-demand and live direct media URLs and local URIs; HLS and MPEG-TS paths on web; native VLC path | Movies, episodes, and channels |
+| 🎛️ **Player controls** | Play/pause, seek, restart, mute, aspect ratio, lock, audio-only mode, audio tracks, playback speed, fullscreen, back | A complete control surface without hard-wiring your app navigation |
 | 🎨 **Branding** | Theme colors, radius, platform styles, replaceable icons, custom panel render slots | Match your app without forking the player |
 | 📡 **Live TV extensions** | Inline preview component; optional chat and EPG panels; recording adapter hooks | Channel browsing and live-viewing workflows |
 | 🔌 **App integration** | Per-action callbacks, imperative ref API, source resolver, progress/presence/events hooks, sleep timer callback | Keep account, IPTV, analytics, and storage logic in your app |
@@ -70,12 +70,12 @@ flowchart LR
 | 🔒 | `lock` | Lock / unlock controls | Prevent accidental touches |
 | 🔊 | `mute` | Mute / unmute | Volume prop also sets initial level |
 | 🖼️ | `aspectRatio` | Fit / fill / stretch | Available choices depend on renderer |
-| 🔇 | `videoOnly` | Video-only mode | Keeps video presentation while muting audio |
+| 🔇 | `videoOnly` | Legacy video-only visibility key | Kept for compatibility; no separate video-only button is rendered |
 | 🎧 | `audioOnly` | Audio-only presentation | Playback continues behind the audio card |
 | 🎚️ | `audioTracks` | Audio-track selection | Depends on exposed tracks / platform engine |
 | ⏩ | `playbackRate` | Playback speed | On-demand experience |
 | ⛶ | `fullscreen` | Fullscreen / promote preview | Native full-player presentation is platform-specific |
-| ⏺️ | `recording` | Recording controls | Requires an app recording adapter or callback |
+| ⏺️ | `recording` | Recording controls | Web uses built-in MediaRecorder when supported; native uses an app recording adapter |
 | 💬 | `liveChat` | Live chat panel | Requires an adapter, render slot, or callback |
 | 📅 | `epg` | Electronic program guide | Requires an adapter, render slot, or callback |
 | ⏱️ | `seek` | Seek bar | Meaningful for seekable media |
@@ -89,7 +89,7 @@ flowchart LR
 |---|---|
 | 🎨 Colors and shape | `theme`: accent, background, control, surface, error colors, border radius, and native palette |
 | 🪄 Icons | `icons`: provide a glyph/string, React node, or icon component; omitted icons keep CineCrew defaults |
-| 🧠 Per-control behavior | `actions`: override only the actions your app wants to own; built-in behavior remains the default otherwise |
+| 🧠 Per-control behavior | `actions`: observe completed player actions in your app without replacing built-in behavior |
 | 🧱 Chat and EPG drawers | `drawerMode`, `drawerStyle`, and optional app-owned `renderLiveChat` / `renderEpg` views |
 | 🔗 Source handling | `resolveSource` for share pages or host-specific resolution; direct media sources pass through unchanged |
 | 📐 Layout | `style`, web `className`, inline preview geometry, and `InlineLivePlayer` height |
@@ -101,7 +101,7 @@ flowchart LR
 
 | Host | Public entry | Rendering / engine path | Key considerations |
 |---|---|---|---|
-| 🌐 React in browser | `@cinecrew/cinecrew-player` or `@cinecrew/cinecrew-player/react` | DOM player; browser media, hls.js, patched mpegts.js; YouTube embed | Browser codec support and origin CORS still apply |
+| 🌐 React in browser | `@cinecrew/cinecrew-player` or `@cinecrew/cinecrew-player/react` | DOM player; browser media, hls.js, patched mpegts.js | Browser codec support and origin CORS still apply |
 | 🖥️ Electron | `@cinecrew/cinecrew-player/electron` | Same web renderer inside Electron Chromium | Chromium’s codec and network rules still apply |
 | 🤖 React Native Android | `@cinecrew/cinecrew-player/native` or `@cinecrew/cinecrew-player/react-native` | Native React Native surface with bundled VLC adapter; Expo Video fallback where available | Native dependencies must be compiled into the app |
 | 📱 React Native iOS | `@cinecrew/cinecrew-player/native` or `@cinecrew/cinecrew-player/react-native` | Native React Native surface with bundled VLC adapter; Expo Video fallback where available | Native dependencies must be compiled into the app |
@@ -112,7 +112,7 @@ flowchart LR
 | MP4 / browser-native media | ✅ Browser media element | ✅ Native engine | A directly playable URL or local URI |
 | HLS (`.m3u8`) | ✅ hls.js / native HLS where available | ✅ Native engine | Origin access, valid playlist/segments, compatible codecs |
 | MPEG-TS (`.ts`) | ✅ Bundled patched MPEG-TS client, when browser conditions permit | ✅ VLC path | Browser codecs and CORS; native module availability |
-| YouTube watch / Shorts / `youtu.be` | ✅ Embedded YouTube player | ✅ Embedded native WebView | Video must allow embedding; network access to YouTube |
+| Hosted-video or share pages | ⚙️ Resolve to a direct media URL with `resolveSource` | ⚙️ Resolve to a direct media URL with `resolveSource` | A watch/share page is not a media stream |
 | Local files | ✅ Platform-supported local/blob URI | ✅ Platform-supported file URI | App obtains and passes the platform-readable URI |
 | Share pages / cloud-drive pages | ⚙️ Optional `resolveSource` | ⚙️ Optional `resolveSource` | Your app resolves authentication and obtains a playable media URL |
 
@@ -123,7 +123,7 @@ flowchart LR
 | Layer | Technologies in this package |
 |---|---|
 | UI & API | React · React Native · TypeScript declarations |
-| Web playback | HTML video · hls.js · patched mpegts.js · YouTube IFrame API |
+| Web playback | HTML video · hls.js · patched mpegts.js |
 | Native playback | VLC adapter bundled in `@cinecrew/cinecrew-player` · `expo-video` fallback |
 | Native UI / utilities | React Native · Expo config plugins · safe-area context · SVG · community slider |
 | Optional media utilities | Mediabunny / AC3 parsing support in relevant web playback paths |
@@ -160,9 +160,9 @@ The items below are planned for more consistent, user-facing support across plat
 
 ## Demos
 
-- **[React + Vite web demo](examples/web-demo)** — try YouTube, MPEG-TS, MP4, MKV, or a local video file. Switch between the full player (all controls and demo chat/EPG/recording adapters enabled) and the compact inline player. [Open a fresh StackBlitz copy](https://stackblitz.com/fork/github/nahushr/cinecrew-player/tree/main/examples/web-demo?startScript=dev).
+- **[React + Vite web demo](examples/web-demo)** — try HLS, MPEG-TS, MP4, MKV, or a local video file. Switch between the full player (all controls and demo chat/EPG/recording adapters enabled) and the compact inline player. [Open a fresh StackBlitz copy](https://stackblitz.com/fork/github/nahushr/cinecrew-player/tree/main/examples/web-demo?startScript=dev).
 - **[Expo / React Native Web demo](examples/expo-web-demo)** — the same source tests and controls in an Expo app rendered for the web.
-- **[Android and iOS Expo Snack demos](examples/snack/App.js)** — both platform links load the same five-test native playground (YouTube, `.ts`, `.mp4`, `.mkv`, and local-file upload), with full-player and inline-player modes. Snack runs in Expo Go, which cannot load this package's custom VLC module; MPEG-TS and MKV playback should be tested in a native development build. [Expo documents this Expo Go limitation](https://docs.expo.dev/faq/#what-can-i-do-or-cannot-do-with-expo-go).
+- **[Android and iOS Expo Snack demos](examples/snack/App.js)** — both platform links load a native playground (`.ts`, `.mp4`, `.mkv`, and local-file upload), with full-player and inline-player modes. Snack runs in Expo Go, which cannot load this package's custom VLC module; MPEG-TS and MKV playback should be tested in a native development build. [Expo documents this Expo Go limitation](https://docs.expo.dev/faq/#what-can-i-do-or-cannot-do-with-expo-go).
 
 The React/Vite demo is self-contained and installs the released `@cinecrew/cinecrew-player` package, so its StackBlitz link works from the `examples/web-demo` subdirectory. Its MPEG-TS button uses a small same-origin H.264/AAC fixture to exercise the TS parser without relying on an external server's CORS configuration. The Expo Web demo uses this repository's package source (`file:../..`) so contributors can test unreleased changes locally. Snack loads the native example from this repository's `main` branch and installs `@cinecrew/cinecrew-player` from npm. The React DOM entry resolves to the browser renderer; it does not evaluate React Native or VLC code. The Expo native entry bundles VLC into the same installed package. External media hosts must allow browser CORS requests; format/codec support also depends on the browser. MKV playback is generally more reliable through the native VLC adapter than a browser video element.
 
@@ -180,7 +180,7 @@ npm install
 npm run web
 ```
 
-> Direct media sources are passed through to the platform engine. A page/share URL is not necessarily a playable media source; use `resolveSource` to resolve it. The player does not rewrite protocols, proxy media, or impose host-specific CORS rules.
+> The player has no built-in YouTube playback or embed mode. Pass a direct playable media URL or local URI; page/share URLs (including YouTube watch pages) must be resolved by your app to a direct media source before playback. The player does not rewrite protocols, proxy media, or impose host-specific CORS rules.
 
 ## Install
 
@@ -198,9 +198,9 @@ The package has one public player API with a renderer selected for the host. The
 
 | Host app | Import | Renderer / playback |
 | --- | --- | --- |
-| React DOM in a browser | `@cinecrew/cinecrew-player` or `@cinecrew/cinecrew-player/react` | HTML video, hls.js, patched mpegts.js, and the browser YouTube embed. |
+| React DOM in a browser | `@cinecrew/cinecrew-player` or `@cinecrew/cinecrew-player/react` | HTML video, hls.js, and patched mpegts.js. |
 | React DOM inside Electron (macOS `.dmg`, Windows `.exe`) | `@cinecrew/cinecrew-player/electron` | Same renderer as React web, using Electron's Chromium media stack. No WebView or custom Electron IPC bridge is needed. |
-| React Native Android / iOS | `@cinecrew/cinecrew-player` or `@cinecrew/cinecrew-player/react-native` | React Native UI with the bundled VLC adapter and Expo video fallback; YouTube uses `react-native-webview`. |
+| React Native Android / iOS | `@cinecrew/cinecrew-player` or `@cinecrew/cinecrew-player/react-native` | React Native UI with the bundled VLC adapter and Expo video fallback. |
 | React Native Web / Expo Web | `@cinecrew/cinecrew-player` or `@cinecrew/cinecrew-player/react-native-web` | React DOM adapter hosted inside the React Native Web app; uses browser playback engines and does not load native VLC or WebView code. |
 
 Metro selects the React Native entry for native builds; regular React bundlers select the React DOM entry. The explicit subpaths let you pin the renderer when preferred.
@@ -221,7 +221,7 @@ export function WatchScreen() {
 }
 ```
 
-For an Expo prebuild project, add the CineCrew Player config plugin and rebuild the native app (a JavaScript reload cannot add a native module). The VLC native implementation ships inside this same package; there is no second VLC package to install. `react-native-webview` is used only as the native YouTube embed surface; regular native streams use VLC / `expo-video`. Browser and Electron YouTube playback use the YouTube IFrame API instead.
+For an Expo prebuild project, add the CineCrew Player config plugin and rebuild the native app (a JavaScript reload cannot add a native module). The VLC native implementation ships inside this same package; there is no second VLC package to install. Native streams use VLC / `expo-video`.
 
 ```json
 {
@@ -244,7 +244,6 @@ import { InlineLivePlayer } from '@cinecrew/cinecrew-player/native';
   height={220}
   isActive={selected}
   paused={!selected}
-  onFullscreen={() => openFullPlayer(channelUrl)}
 />
 ```
 
@@ -259,7 +258,6 @@ import '@cinecrew/cinecrew-player/styles.css';
   title="Example channel"
   isActive={selected}
   paused={!selected}
-  onFullscreen={() => openFullPlayer(channelUrl)}
 />
 ```
 
@@ -283,15 +281,9 @@ export function WatchScreen() {
 
 Web playback is direct from the supplied URL. HLS and MPEG-TS clients fetch playlists and segments from the stream origin, so the origin must permit those browser requests.
 
-### YouTube and share links
+### Direct media URLs and share pages
 
-Pass a YouTube watch, Shorts, or `youtu.be` URL as the source to play it inside the player rather than opening another app:
-
-```tsx
-<CineCrewPlayer source="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="Trailer" />
-```
-
-The video must allow embedding. Other URLs are passed unchanged to the platform engine. A Google Drive/share page or other webpage is not itself a media stream; resolve it in your app and provide the playable URL, or use the optional `resolveSource` callback. This keeps provider authentication, CORS policy, and URL extraction under the consuming app’s control.
+Pass a direct media URL or a platform-readable local file URI. Hosted-video watch pages and share pages are not supported as playable sources because they are HTML pages, not media streams. Resolve those pages in your app and provide a direct playable URL, or use the optional `resolveSource` callback. This keeps provider authentication, CORS policy, and URL extraction under the consuming app’s control.
 
 ```tsx
 <CineCrewPlayer
@@ -311,7 +303,7 @@ The video must allow embedding. Other URLs are passed unchanged to the platform
 | React Native Android / iOS | VLC native module; `expo-video` fallback when VLC is unavailable | VLC supports a broader range of containers/codecs, including common AC3 streams. Native module availability depends on the app binary. |
 | Electron renderer | Chromium `<video>`, hls.js, and patched mpegts.js | Same browser codec/CORS constraints as React web; packages with the app's `.dmg` / `.exe`. |
 
-Browser codec support varies. The web player reports an AC3 compatibility message only when its MPEG-TS probe identifies unsupported AC3 audio; native playback does not apply this browser-only restriction. YouTube sources use the embedded YouTube player and remain subject to the video’s embed settings.
+Browser codec support varies. The web player reports an AC3 compatibility message only when its MPEG-TS probe identifies unsupported AC3 audio; native playback does not apply this browser-only restriction.
 
 ## How CineCrew Player differs from established players
 
@@ -343,13 +335,16 @@ In short: CineCrew’s intended distinction is **one app-facing player package f
 | `muted` | `boolean` | `false` | Initial mute state. |
 | `volume` | `number` | `1` | Initial volume from `0` to `1`. |
 | `playbackRate` | `number` | `1` | Initial playback speed; the on-demand speed control can change it afterward. |
+| `showProgressBar` | `boolean` | `true` | Show or hide the playback seek bar. When hidden, `onProgressBarChange` is not called. |
+| `aspectRatios` | `(string \| { value, label? })[]` | built-in choices | Customize the aspect-ratio menu. Values include `FIT`, `FILL`, `STRETCH`, or a ratio such as `1:1`; labels are optional. |
+| `defaultAspectRatio` | `string` | `'FIT'` | Initial and source-reset aspect mode. Must match an item in `aspectRatios` to appear selected. |
 | `controls` | `PlayerControls` | defaults below | Show/hide individual control buttons. |
 | `features` | feature flags | `{}` | Optional player features, including web stream diagnostics with `{ diagnostics: true }`. |
-| `actions` | `PlayerActions` | `{}` | Replace the built-in behavior for individual actions. If a callback is provided, that callback owns the action. |
+| `actions` | `PlayerActions` | `{}` | Observe built-in actions. The player performs its core action first, then invokes the callback with the resulting action payload. |
 | `integrations` | `PlayerIntegrations` | `{}` | Inject user identity, chat, EPG, recording, analytics, and presence services. |
 | `drawerMode` | `'overlay' \| 'resize'` | `'overlay'` | Web/Electron drawer behavior: overlay the video or resize it to make room for chat, EPG, and diagnostics. |
 | `drawerStyle` | `React.CSSProperties` / React Native `ViewStyle` | — | Platform-specific style overrides for the chat, EPG, and diagnostics drawer. |
-| `messagePageSize` | `number` | `50` | Number of live-chat messages fetched per page; older pages load from the drawer’s “See more” control. |
+| `messagePageSize` | `number` | `50` | Number of live-chat messages fetched per page; older messages load automatically when the list is scrolled to the top. |
 | `theme` | `PlayerTheme` | built-in theme | Customize player colors, borders, and shape. |
 | `icons` | `PlayerIcons` | built-in icons | Override any control icon by key. |
 | `style` | platform style | — | Outer player style. On web this is a CSS style object; native uses React Native style props. |
@@ -364,14 +359,16 @@ In short: CineCrew’s intended distinction is **one app-facing player package f
 | `mediaId`, `episodeLabel`, `season`, `episode`, `genre`, `categoryName` | metadata | — | Optional item metadata for the player and integrations. |
 | `playlist` | `object[]` | — | Episode list used for automatic next-episode behavior. |
 | `shuffle` | `boolean` | `false` | Select a random next episode when the current episode ends. |
-| `onClose`, `onBack` | callbacks | — | Player lifecycle/navigation callbacks. |
+| `onClose`, `onBack` | callbacks | — | App-owned navigation callbacks; Back does not close the player unless your callback does so. |
+| `onAspectRatioChange` | `PlayerAction` | — | Top-level callback invoked after the player applies the selected aspect ratio; `actions.onAspectRatioChange` takes precedence if both are supplied. |
+| `onProgressBarChange` | `(time: string) => void` | — | When the progress bar is shown, reports the played position as zero-padded `HH:MM:SS` once per elapsed playback second, and immediately after a completed seek or restart. Scrubbing reports the committed position, not every intermediate drag update. It is not called when `showProgressBar` is false, `controls.seek` is false, or the live-player UI hides seeking. |
 | `onReady`, `onProgress`, `onPlaying`, `onBuffering`, `onError`, `onEnded`, `onPlaybackRoute` | callbacks | — | Playback lifecycle callbacks. Progress payloads are platform-specific native/browser events. |
 | `onNextEpisode`, `onCwRefresh` | callbacks | — | Episode advancement and post-close refresh hooks. |
 | `renderLiveChat`, `renderEpg` | render functions | — | Web custom-panel render slots. On native, use the chat/EPG integration adapters. |
 | `initialShowLiveChat`, `liveChatNonce` | `boolean`, `number` | `false`, `0` | Open or re-open the live-chat panel (when available). |
 | `inlinePreview`, `inlinePreviewRect`, `onInlinePreviewWheel`, `onPromotePreview`, `onPlayerHostRef` | preview options and callbacks | — | Embed/manage the player as a movable inline preview. Mainly useful for app-level player shells. |
 
-`features={{ diagnostics: true }}` enables the diagnostics button and built-in stream status panel on web; `controls.diagnostics` can hide it and `actions.onDiagnosticsOpen` can replace the panel action. `onFullscreen` receives `{ isFullscreen }`. All lifecycle callbacks in the table are optional; native event objects differ from browser events.
+`features={{ diagnostics: true }}` enables the diagnostics button and built-in stream status panel on web; `controls.diagnostics` can hide it. `onFullscreen` receives `{ isFullscreen }` after the player requests the fullscreen change. All lifecycle callbacks in the table are optional; native event objects differ from browser events.
 
 ### Player source
 
@@ -385,7 +382,7 @@ type PlayerSource = string | {
   id?: string | number;
   streamId?: string | number;
   mediaId?: string | number;
-  type?: string;       // e.g. 'mpegts', 'hls', or 'youtube' when paired with a YouTube video ID
+  type?: string;       // e.g. 'mpegts' or 'hls'
   mimeType?: string;
   mediaType?: string;
   isLive?: boolean;
@@ -394,7 +391,7 @@ type PlayerSource = string | {
 
 ### Inline live preview props
 
-`InlineLivePlayer` is exported from `@cinecrew/cinecrew-player/native` and `@cinecrew/cinecrew-player/web`. It renders a compact channel preview/poster and can promote playback to the host app's full player.
+`InlineLivePlayer` is exported from `@cinecrew/cinecrew-player/native` and `@cinecrew/cinecrew-player/web`. It renders a compact channel preview/poster with its title at the bottom-left. Its fullscreen control expands the same inline playback surface; it does not promote or switch to the standard player.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -404,9 +401,9 @@ type PlayerSource = string | {
 | `poster`, `posterChannel` | string / object | — | Still image or channel object used when preview is paused/inactive. |
 | `paused`, `isActive` | `boolean` | `false`, `true` | Control whether this preview should render/play its stream. |
 | `onActivate` | `() => void` | — | Called when an inactive preview poster is selected. |
-| `onFullscreen` | `() => void` | — | Called to promote/open the full player. |
+| `onFullscreen` | `() => void` | — | Deprecated; no longer promotes to another player. Use `actions.onFullscreen` to observe the inline player's fullscreen state after it changes. |
 | `controls` | `Pick<PlayerControls, 'playPause' \| 'mute' \| 'fullscreen'>` | all shown | Toggle its compact controls. |
-| `actions` | matching `PlayerActions` subset | built-in | Replace play/pause, mute, or promote behavior. |
+| `actions` | matching `PlayerActions` subset | built-in | Observe play/pause, mute, or fullscreen actions after their built-in behavior runs. |
 | `initialMuted` | `boolean` | `true` | Initial preview mute state. |
 | `theme`, `icons`, `style` | `PlayerTheme`, `PlayerIcons`, platform style | defaults | Customize preview colors, controls, and layout. |
 | `onError`, `onPlaying` | callbacks | — | Playback lifecycle callbacks. |
@@ -447,20 +444,22 @@ Every control can be hidden with `false`. Defaults are designed to be useful out
 | `lock` | Lock/unlock touch controls. |
 | `mute` | Mute/unmute. |
 | `aspectRatio` | Fit/fill/stretch and available aspect choices. |
-| `videoOnly` | Mute audio while keeping video visible. |
+| `videoOnly` | Legacy compatibility setting; the player does not render a separate video-only button. |
 | `audioOnly` | Show the audio-only card while playback continues. |
 | `audioTracks` | Audio-track picker when tracks are exposed. |
 | `playbackRate` | On-demand playback speed. |
 | `fullscreen` | Fullscreen button on web and inline previews. Native player opens full-screen. |
-| `recording` | Recording controls; requires `integrations.recording` or an action override. |
-| `liveChat` | Chat drawer/panel; requires a chat adapter, render slot, or action override. |
-| `epg` | EPG drawer/panel; requires an EPG adapter, render slot, or action override. |
-| `diagnostics` | Stream diagnostics button; enable with `features={{ diagnostics: true }}` or provide `actions.onDiagnosticsOpen`. |
+| `recording` | Recording controls; web has a built-in MediaRecorder flow where supported, while native requires an app recording adapter. |
+| `liveChat` | Chat drawer/panel; requires a chat adapter or render slot. |
+| `epg` | EPG drawer/panel; requires an EPG adapter or render slot. |
+| `diagnostics` | Stream diagnostics button; enable with `features={{ diagnostics: true }}`. |
 | `seek` | On-demand seek bar. |
 
 ## Actions and callbacks
 
-Callbacks passed to `actions` **replace** built-in behavior; this is useful when an app wants to own navigation, playback state, or a control. Each receives an action payload and a context with the imperative `player` API (and the web video element where available).
+For playback controls, the player executes its core behavior first and then invokes the matching `actions` callback. This lets your app show a snackbar, update analytics, or synchronize app state. Back is intentionally different: it has no built-in close/navigation behavior. The player invokes `actions.onBack`, `onBack`, or `onClose` (in that precedence), and your app decides whether to navigate, dismiss the player, or just show a snackbar. Each callback receives an action payload and a context with the imperative `player` API (and the web video element where available). If a callback throws, the player logs the error without blocking the UI.
+
+`onProgressBarChange` is separate from the platform-specific `onProgress` event: while the progress bar is enabled, it emits a compact time string such as `00:00:05` once per playback second. A seek emits its final target time after the player applies the seek; skipped positions are not reported as watched time. Set `showProgressBar={false}` (or `controls={{ seek: false }}`) to hide seeking and suppress these progress-bar callbacks.
 
 ```tsx
 const playerRef = React.useRef(null);
@@ -469,17 +468,18 @@ const playerRef = React.useRef(null);
   ref={playerRef}
   source={source}
   actions={{
-    onRestart: (_payload, { player }) => player?.restart(),
-    onBack: () => navigation.goBack(),
-    onMute: ({ muted }, { player }) => player?.setMuted(muted),
-    onAspectRatioChange: ({ aspectRatio }, { player }) => player?.setAspectRatio(aspectRatio),
+    onRestart: () => analytics.track('player_restart'),
+    onPlayPause: ({ isPlaying }) => analytics.track('player_play_pause', { isPlaying }),
+    onMute: ({ muted }) => analytics.track('player_mute', { muted }),
+    onAspectRatioChange: ({ aspectRatio }) => analytics.track('player_aspect_ratio', { aspectRatio }),
   }}
+  onBack={() => navigation.goBack()}
 />
 ```
 
 Available action keys: `onBack`, `onPlayPause`, `onSeek`, `onRestart`, `onLock`, `onMute`, `onAspectRatioChange`, `onVideoOnlyChange`, `onAudioOnlyChange`, `onAudioTrackChange`, `onPlaybackRateChange`, `onFullscreen`, `onRecordingStart`, `onRecordingPause`, `onRecordingResume`, `onRecordingStop`, `onLiveChatOpen`, `onEpgOpen`, and `onDiagnosticsOpen`.
 
-The ref exposes `play`, `pause`, `togglePlayPause`, `restart`, `setMuted`, `toggleMute`, `setAspectRatio`, `setAudioTrack`, `setAudioOnly`, `setVideoOnly`, `setPlaybackRate`, `seekTo`, `seekBy`, `back`, `getVideoElement`, `getAudioTracks`, and fullscreen methods where supported.
+The ref exposes `play`, `pause`, `togglePlayPause`, `restart`, `setMuted`, `toggleMute`, `setAspectRatio`, `setAudioTrack`, `setAudioOnly`, `setVideoOnly`, `setPlaybackRate`, `seekTo`, `seekBy`, `back`, `setPanel`, `closePanel`, `getVideoElement`, `getAudioTracks`, and fullscreen methods where supported.
 
 ## Integrations
 
@@ -517,10 +517,20 @@ Integrations are optional. The package has no CineCrew account, database, or wor
 />
 ```
 
-On web and Electron, the player supplies the chat drawer UI—including the composer and emoji picker—when `integrations.liveChat.loadMessages` is provided. `sendMessage` connects the built-in composer to your chat service; omit it to show a read-only chat. Messages may include `id`, `username`, `comment` (or `message`), and `timestamp` (or `createdAt`). The drawer requests the newest page with `offset: 0`, then requests older pages with the same `limit` and an increasing `offset` when “See more messages” is selected. Return each page in chronological order (oldest first); return `{ messages, hasMore }` when your service can report whether older pages exist. Otherwise, a full page implies there may be more. Live chat polls for new messages at `pollIntervalMs` (defaults to five seconds).
+On web and Electron, the player supplies the chat drawer UI—including the composer and searchable, grouped emoji picker—when `integrations.liveChat.loadMessages` is provided. `sendMessage` connects the built-in composer to your chat service; omit it to show a read-only chat. Messages may include `id`, `username`, `comment` (or `message`), and `timestamp` (or `createdAt`). The drawer requests the newest page with `offset: 0`, then automatically requests older pages with the same `limit` and increasing `offset` as the viewer scrolls to the top. Return each page in chronological order (oldest first); return `{ messages, hasMore }` when your service can report whether older pages exist. Otherwise, a full page implies there may be more. Live chat polls for new messages at `pollIntervalMs` (defaults to five seconds); new messages scroll into view at the bottom.
 
 The EPG drawer uses `integrations.epg.loadListings`, which returns entries with `startMs` and `endMs` epoch-millisecond timestamps. Both drawers default to a semi-transparent right-side overlay, so video size does not change. Set `drawerMode="resize"` to reserve space and shrink the video; customize the drawer with `drawerStyle`. You may supply `renderLiveChat` / `renderEpg` or integration render callbacks to replace the built-in drawer contents. The native player renders its platform-native chat and EPG UI from the same adapters.
 
+### Web recording
+
+On supported browsers, the built-in recording control captures the media video and audio tracks, shows a compact timer at the top of the video with pause/resume and stop actions, then attempts a WebM download when stopped. A `Download recording` action remains available afterward as a user-gesture retry if the browser blocks the automatic download. Native React Native apps need an `integrations.recording` implementation backed by Android MediaProjection or iOS ReplayKit (with the platform's permission flow).
+
+For ordinary web media, aspect changes are reflected in the recording when the browser permits the player to draw the cross-origin video into a canvas; if the source does not grant canvas CORS access, the recording keeps its source aspect ratio. Use `integrations.recording` to supply a different recording implementation.
+
+### Audio-only and locked-screen playback
+
+Audio-only mode fully covers the video with an opaque dark surface; its poster remains visible in the audio card. Native VLC playback is configured to continue in audio-only mode when the app is backgrounded. Native apps must also configure their platform background-audio capability where applicable.
+
 ## Themes and icons
 
 Defaults are used unless the caller supplies an override. Web theme properties include `accentColor`, `backgroundColor`, `controlBackground`, `controlColor`, `surfaceColor`, `errorColor`, and `borderRadius`. Native also accepts a `colors` palette object.
@@ -548,7 +558,7 @@ Icon keys: `play`, `pause`, `restart`, `lock`, `unlock`, `mute`, `unmute`, `aspe
 
 ## Sources and link resolution
 
-Local file URIs and direct stream URLs are passed to the selected platform player without changing `http`, `https`, `file`, or other schemes. YouTube watch/share URLs are recognized and played with the embedded YouTube player. Other sharing pages (for example, a private Google Drive page) need a consumer-provided resolver because the package cannot access the consumer’s credentials or infer every host’s download rules:
+Local file URIs and direct stream URLs are passed to the selected platform player without changing `http`, `https`, `file`, or other schemes. Hosted-video watch/share pages (for example, a private cloud-drive page) need a consumer-provided resolver because the package cannot access the consumer’s credentials or infer every host’s download rules:
 
 ```tsx
 <CineCrewPlayer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cinecrew/cinecrew-player",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Customizable cross-platform live and on-demand video player for React and React Native.",
   "license": "MIT",
@@ -113,7 +113,6 @@
     "mediabunny": "^1.59.0",
     "react-native-safe-area-context": "^5.7.0",
     "react-native-svg": "^15.15.4",
-    "react-native-webview": "^13.16.1",
     "prop-types": "^15.8.1"
   },
   "peerDependencies": {

package/src/native/InlineLivePlayer.js

@@ -4,6 +4,7 @@ import {
   Image,
   Pressable,
   StyleSheet,
+  Modal,
   Text,
   View,
 } from 'react-native';
@@ -13,6 +14,7 @@ import { WebVideoPlayer } from './media/WebVideoPlayer';
 import { ElectronVideoPlayer } from './media/ElectronVideoPlayer';
 import { isAndroid, isElectron, isIOS, isWeb } from '../utils/runtimePlatform';
 import { USER_AGENT } from './media/player/playerConstants';
+import { invokePlayerAction } from '../utils/invokePlayerAction.js';
 
 function getArtwork(channel) {
   return channel?.logoUrl || channel?.logo || channel?.stream_icon || channel?.posterUrl || channel?.image || '';
@@ -82,8 +84,7 @@ function InlineControlButton({
     accessibilityLabel: label,
     onPress: () => {
       const callback = actions?.[actionName];
-      if (typeof callback === 'function') callback(payload, { player: null });
-      else fallback?.();
+      invokePlayerAction(fallback, callback, payload, { player: null });
     },
     style: [styles.button, { backgroundColor: palette.controlBackground }, active && { borderColor: palette.accentColor, borderWidth: 1 }],
   }, React.createElement(PlayerIcon, { name: icon, size: 19, color: palette.controlColor }));
@@ -130,7 +131,7 @@ function InlinePlayerOverlay({
     showControls ? React.createElement(React.Fragment, null,
       React.createElement(View, { pointerEvents: 'box-none', style: styles.topRow },
       React.createElement(View, { style: styles.liveBadge }, React.createElement(View, { style: styles.liveDot }), React.createElement(Text, { style: styles.liveText }, 'LIVE')),
-      React.createElement(Text, { numberOfLines: 1, style: [styles.title, { color: palette.controlColor }] }, title),
+      React.createElement(View, { style: { flex: 1 } }),
       button('mute', 'onMute', muteLabel, muteIcon, onMute, { muted: !muted }),
       ),
       React.createElement(View, { pointerEvents: 'box-none', style: styles.center },
@@ -140,12 +141,64 @@ function InlinePlayerOverlay({
       button('fullscreen', 'onFullscreen', 'Open full player', 'fullscreen', onFullscreen, { source, title, isFullscreen: !fullscreen }))) : null);
 }
 
+function createInlinePlayerLayer(player, visible) {
+  if (!visible || !player) return null;
+  return React.createElement(View, { pointerEvents: 'none', style: StyleSheet.absoluteFill }, player);
+}
+
+function createInlineArtworkLayer(shouldRenderVideo, artwork, accentColor) {
+  if (shouldRenderVideo) return null;
+  if (artwork) {
+    return React.createElement(Image, { source: { uri: artwork }, resizeMode: 'contain', style: styles.poster });
+  }
+  return React.createElement(View, { style: styles.emptyPoster },
+    React.createElement(PlayerIcon, { name: 'television-play', size: 48, color: accentColor }));
+}
+
+function createInlineStatusLayer(loading, error, palette) {
+  if (error) {
+    return React.createElement(View, { pointerEvents: 'none', style: styles.error },
+      React.createElement(Text, { style: [styles.errorText, { color: palette.controlColor }] }, error));
+  }
+  if (!loading) return null;
+  return React.createElement(View, { pointerEvents: 'none', style: styles.loading },
+    React.createElement(ActivityIndicator, { size: 'large', color: palette.accentColor }));
+}
+
+function InlineLivePlayerSurface({
+  height,
+  style,
+  palette,
+  fullscreen,
+  setFullscreen,
+  player,
+  shouldRenderVideo,
+  artwork,
+  loading,
+  error,
+  renderOverlay,
+}) {
+  return React.createElement(View, { style: [styles.frame, { height, backgroundColor: palette.surfaceColor }, style] },
+    createInlinePlayerLayer(player, !fullscreen),
+    createInlineArtworkLayer(shouldRenderVideo, artwork, palette.accentColor),
+    createInlineStatusLayer(shouldRenderVideo && loading, error, palette),
+    fullscreen ? null : renderOverlay(),
+    React.createElement(Modal, {
+      visible: fullscreen,
+      animationType: 'none',
+      statusBarTranslucent: true,
+      onRequestClose: () => setFullscreen(false),
+    }, React.createElement(View, { style: styles.fullscreenFrame },
+      createInlinePlayerLayer(player, true),
+      createInlineStatusLayer(loading, error, palette),
+      renderOverlay())));
+}
+
 function InlineLivePlayerView({
   source,
   url,
   title = 'Live TV',
   height = 220,
-  onFullscreen,
   paused: externalPaused,
   isActive = true,
   onActivate,
@@ -213,15 +266,16 @@ function InlineLivePlayerView({
   }, [onPlaying]);
 
   const performAction = (name, fallback, payload) => {
-    if (typeof actions?.[name] === 'function') return actions[name](payload);
-    return fallback?.();
+    return invokePlayerAction(fallback, actions?.[name], payload, { player: null });
   };
 
   const togglePlay = (event) => {
     event?.stopPropagation?.();
     if (!shouldRenderVideo) {
-      onActivate?.();
-      setInternallyPaused(false);
+      performAction('onPlayPause', () => {
+        onActivate?.();
+        setInternallyPaused(false);
+      }, true);
       return;
     }
     performAction('onPlayPause', () => setInternallyPaused((value) => !value), !pausedNow);
@@ -234,10 +288,11 @@ function InlineLivePlayerView({
 
   const openFullscreen = (event) => {
     event?.stopPropagation?.();
-    performAction('onFullscreen', () => {
-      if (typeof onFullscreen === 'function') onFullscreen();
-      else setFullscreen((value) => !value);
-    }, { isFullscreen: !fullscreen, source: sourceObject, title });
+    performAction('onFullscreen', () => setFullscreen((value) => !value), {
+      isFullscreen: !fullscreen,
+      source: sourceObject,
+      title,
+    });
   };
 
   const nativeMediaOptions = useMemo(() => [
@@ -272,31 +327,37 @@ function InlineLivePlayerView({
     onPlaying: handlePlaying,
     onError: handleError,
   });
+  const renderOverlay = () => React.createElement(InlinePlayerOverlay, {
+    showControls,
+    controls: { ...controls, actions },
+    palette,
+    title,
+    muted,
+    paused: pausedNow,
+    source: streamUrl,
+    fullscreen,
+    onToggleControls: () => setShowControls((value) => !value),
+    onMute: toggleMute,
+    onPlay: togglePlay,
+    onFullscreen: openFullscreen,
+  });
 
   return React.createElement(
     PlayerCustomizationProvider,
     { icons, theme },
-    React.createElement(View, { style: [styles.frame, { height, backgroundColor: palette.surfaceColor }, style] },
-      player ? React.createElement(View, { pointerEvents: 'none', style: StyleSheet.absoluteFill }, player) : null,
-      !shouldRenderVideo && artwork ? React.createElement(Image, { source: { uri: artwork }, resizeMode: 'contain', style: styles.poster }) : null,
-      !shouldRenderVideo && !artwork ? React.createElement(View, { style: styles.emptyPoster }, React.createElement(PlayerIcon, { name: 'television-play', size: 48, color: palette.accentColor })) : null,
-      shouldRenderVideo && loading && !error ? React.createElement(View, { pointerEvents: 'none', style: styles.loading }, React.createElement(ActivityIndicator, { size: 'large', color: palette.accentColor })) : null,
-      error ? React.createElement(View, { pointerEvents: 'none', style: styles.error }, React.createElement(Text, { style: [styles.errorText, { color: palette.controlColor }] }, error)) : null,
-      React.createElement(InlinePlayerOverlay, {
-        showControls,
-        controls: { ...controls, actions },
-        palette,
-        title,
-        muted,
-        paused: pausedNow,
-        source: streamUrl,
-        fullscreen,
-        onToggleControls: () => setShowControls((value) => !value),
-        onMute: toggleMute,
-        onPlay: togglePlay,
-        onFullscreen: openFullscreen,
-      }),
-    ),
+    React.createElement(InlineLivePlayerSurface, {
+      height,
+      style,
+      palette,
+      fullscreen,
+      setFullscreen,
+      player,
+      shouldRenderVideo,
+      artwork,
+      loading,
+      error,
+      renderOverlay,
+    }),
   );
 }
 
@@ -304,6 +365,7 @@ export const InlineLivePlayer = React.memo(InlineLivePlayerView);
 
 const styles = StyleSheet.create({
   frame: { width: '100%', minHeight: 80, overflow: 'hidden', borderRadius: 14, position: 'relative', justifyContent: 'center' },
+  fullscreenFrame: { flex: 1, overflow: 'hidden', position: 'relative', justifyContent: 'center', backgroundColor: '#000' },
   video: { width: '100%', height: '100%' },
   poster: { ...StyleSheet.absoluteFillObject, width: '100%', height: '100%' },
   emptyPoster: { ...StyleSheet.absoluteFillObject, alignItems: 'center', justifyContent: 'center' },