Feat: add support to enable/disable HLS buffering

examples/nextjs-with-typescript/pages/MuxPlayerBufferingControl.tsx

@@ -0,0 +1,103 @@
+import React, { useRef, useEffect, useState } from 'react';
+import MuxPlayer from '@mux/mux-player-react';
+
+const BufferingControlExample: React.FC = () => {
+  const playerRef = useRef(null);
+  const [isBuffering, setIsBuffering] = useState<boolean>(false);
+
+  const handleStartBuffering = () => {
+    playerRef.current?.startBuffering();
+    updateBufferingStatus();
+  };
+
+  const handleStopBuffering = () => {
+    playerRef.current?.stopBuffering();
+    updateBufferingStatus();
+  };
+
+  const updateBufferingStatus = () => {
+    const buffering = playerRef.current?.isBuffering() ?? false;
+    setIsBuffering(buffering);
+  };
+
+  useEffect(() => {
+    setTimeout(() => {
+      updateBufferingStatus();
+    }, 100);
+  }, []);
+
+  return (
+    <div style={{ maxWidth: '1200px', margin: '0 auto', padding: '20px' }}>
+      <h1>Mux Player React - Buffering Control Example</h1>
+
+      <div style={{ marginBottom: '20px' }}>
+        <MuxPlayer
+          ref={playerRef}
+          playbackId="ihZa7qP1zY8oyLSQW9TS602VgwQvNdyIvlk9LInEGU2s"
+          muted
+          preload="auto"
+          autoPlay={true}
+          style={{ width: '100%', height: '400px' }}
+        />
+      </div>
+
+      <div style={{ display: 'flex', gap: '10px', justifyContent: 'center', margin: '20px 0', flexWrap: 'wrap' }}>
+        <button
+          onClick={handleStartBuffering}
+          style={{
+            padding: '10px 20px',
+            border: 'none',
+            borderRadius: '4px',
+            backgroundColor: '#4CAF50',
+            color: 'white',
+            cursor: 'pointer',
+            fontSize: '14px',
+          }}
+        >
+          Start Buffering
+        </button>
+
+        <button
+          onClick={handleStopBuffering}
+          style={{
+            padding: '10px 20px',
+            border: 'none',
+            borderRadius: '4px',
+            backgroundColor: '#f44336',
+            color: 'white',
+            cursor: 'pointer',
+            fontSize: '14px',
+          }}
+        >
+          Stop Buffering
+        </button>
+
+        <button
+          onClick={updateBufferingStatus}
+          style={{
+            padding: '10px 20px',
+            border: 'none',
+            borderRadius: '4px',
+            backgroundColor: '#2196F3',
+            color: 'white',
+            cursor: 'pointer',
+            fontSize: '14px',
+          }}
+        >
+          Check Status
+        </button>
+      </div>
+
+      <div style={{ backgroundColor: '#000', padding: '15px', borderRadius: '4px', margin: '20px 0' }}>
+        <h3>Current Status:</h3>
+        <p>
+          Buffering: <span style={{ fontWeight: 'bold', color: isBuffering ? '#4CAF50' : '#f44336' }}>
+            {isBuffering ? 'Yes' : 'No'}
+          </span>
+        </p>
+      </div>
+    </div>
+  );
+};
+
+export default BufferingControlExample;

examples/nextjs-with-typescript/pages/index.tsx

@@ -16,6 +16,7 @@ function HomePage() {
         <li><Link href="/MuxPlayerCuePoints" className="player"><>&lt;MuxPlayer&gt;<br/>(CuePoints)</></Link></li>
         <li><Link href="/MuxPlayerCuePointsMeditate" className="player"><>&lt;MuxPlayer&gt;<br/>(CuePoints + Audio Only)</></Link></li>
         <li><Link href="/MuxPlayerChapters" className="player"><>&lt;MuxPlayer&gt;<br/>(Chapters)</></Link></li>
+        <li><Link href="/MuxPlayerBufferingControl" className="player"><>&lt;MuxPlayer&gt;<br/>(Buffering control)</></Link></li>
         <li><Link href="/MuxPlayerLazy" className="player"><>&lt;MuxPlayer&gt;<br/>(lazy)</></Link></li>
         <li><Link href="/MuxPlayerDynamic" className="player"><>&lt;MuxPlayer&gt;<br/>(Next.js dynamic)</></Link></li>
         <li><Link href="/MuxPlayerLazyDynamic" className="player"><>&lt;MuxPlayer&gt;<br/>(lazy + dynamic)</></Link></li>

examples/vanilla-ts-esm/public/index.html

@@ -40,6 +40,7 @@ <h1><a href="/">Elements</a></h1>
         <li><a href="./mux-player-audio-tracks.html" class="player">&lt;mux-player&gt; (audio tracks)</a></li>
         <li><a href="./mux-player-theme.html" class="player">&lt;mux-player&gt; (microvideo theme)</a></li>
         <li><a href="./mux-player-theme-classic.html" class="player">&lt;mux-player&gt; (classic theme)</a></li>
+        <li><a href="./mux-player-buffering-control.html" class="player">&lt;mux-player&gt; (buffering control)</a></li>
         <li><a href="./mux-uploader-simple.html" class="uploader">&lt;mux-uploader&gt;</a></li>
         <li><a href="./mux-uploader-full.html" class="uploader">&lt;mux-uploader&gt; (full-page)</a></li>
       </ul>

examples/vanilla-ts-esm/public/mux-player-buffering-control.html

@@ -0,0 +1,162 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Mux Player - Buffering Control Example</title>
+  <script type="module" src="./dist/mux-player.js"></script>
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 20px;
+      background-color: #f5f5f5;
+    }
+
+    .container {
+      background: white;
+      padding: 20px;
+      border-radius: 8px;
+      box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+      margin-bottom: 20px;
+    }
+
+    h1 {
+      color: #333;
+      text-align: center;
+    }
+
+    .video-container {
+      position: relative;
+      width: 100%;
+      max-width: 800px;
+      margin: 0 auto 20px;
+    }
+
+    mux-player {
+      width: 100%;
+      height: 400px;
+    }
+
+    .controls {
+      display: flex;
+      gap: 10px;
+      justify-content: center;
+      margin: 20px 0;
+      flex-wrap: wrap;
+    }
+
+    button {
+      padding: 10px 20px;
+      border: none;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 14px;
+      transition: background-color 0.2s;
+    }
+
+    .start-btn {
+      background-color: #4CAF50;
+      color: white;
+    }
+
+    .start-btn:hover {
+      background-color: #45a049;
+    }
+
+    .stop-btn {
+      background-color: #f44336;
+      color: white;
+    }
+
+    .stop-btn:hover {
+      background-color: #da190b;
+    }
+
+    .status-btn {
+      background-color: #2196F3;
+      color: white;
+    }
+
+    .status-btn:hover {
+      background-color: #1976D2;
+    }
+
+    .info {
+      background-color: #e3f2fd;
+      padding: 15px;
+      border-radius: 4px;
+      margin: 20px 0;
+    }
+
+    .status {
+      font-weight: bold;
+      color: #1976D2;
+    }
+
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>Mux Player - Buffering Control Example</h1>
+
+    <div class="video-container">
+      <mux-player
+        playback-id="ihZa7qP1zY8oyLSQW9TS602VgwQvNdyIvlk9LInEGU2s"
+        autoplay
+        controls
+        muted
+        preload="auto"
+        prefer-playback="mse"
+      ></mux-player>
+    </div>
+
+    <div class="controls">
+      <button id="startBtn" class="start-btn">Start Buffering</button>
+      <button id="stopBtn" class="stop-btn">Stop Buffering</button>
+      <button id="statusBtn" class="status-btn">Check Status</button>
+    </div>
+
+    <div class="info">
+      <h3>Current Status:</h3>
+      <p>Buffering: <span id="status" class="status">Unknown</span></p>
+    </div>
+
+
+  </div>
+
+  <script>
+    const player = document.querySelector('mux-player');
+    const startBtn = document.getElementById('startBtn');
+    const stopBtn = document.getElementById('stopBtn');
+    const statusBtn = document.getElementById('statusBtn');
+    const status = document.getElementById('status');
+
+    // Button event listeners
+    startBtn.addEventListener('click', () => {
+      player.startBuffering();
+      updateStatus();
+    });
+
+    stopBtn.addEventListener('click', () => {
+      player.stopBuffering();
+      updateStatus();
+    });
+
+    statusBtn.addEventListener('click', () => {
+      updateStatus();
+    });
+
+    function updateStatus() {
+      const isBuffering = player.isBuffering();
+      status.textContent = isBuffering ? 'Yes' : 'No';
+      status.style.color = isBuffering ? '#4CAF50' : '#f44336';
+    }
+
+    player.addEventListener('loadedmetadata', () => {
+      updateStatus();
+    });
+  </script>
+</body>
+</html>

packages/mux-player/REFERENCE.md

@@ -76,6 +76,9 @@
 | `addCuePoints()` | Add an array of CuePoints with the shape `{ startTime: number; endTime?: number, value: any; }` to the Mux Player instance                                                                           |
 | `addChapters()`  | Add an array of chapters with the shape `{ startTime: number; endTime?: number, value: string; }` to the Mux Player instance                                                                         |
 | `getStartDate()` | Will return a Date that matches the earliest PDT in your stream. Identical to [native `getStartDate()` method](https://html.spec.whatwg.org/multipage/media.html#dom-media-getstartdate), if exists. |
+| `startBuffering()` | Start or resume video buffering/loading. Useful for resuming buffering after it has been stopped. |
+| `stopBuffering()` | Stop video buffering/loading. Useful for pausing data fetching when video is not visible. |
+| `isBuffering()` | Returns `true` if the player is currently buffering/loading video data, `false` otherwise. |
 
 <!-- UNDOCUMENTED
 | `addTextTrack()` | Identical to the [native `addTextTrack()` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement#methods). |

packages/mux-player/src/base.ts

@@ -817,6 +817,18 @@ class MuxPlayerElement extends VideoApiElement implements IMuxPlayerElement {
     return this.media?.mux;
   }
 
+  startBuffering() {
+    return this.media?.startBuffering?.();
+  }
+
+  stopBuffering() {
+    return this.media?.stopBuffering?.();
+  }
+
+  isBuffering() {
+    return this.media?.isBuffering?.() ?? false;
+  }
+
   /**
    * Gets the theme.
    */

packages/mux-player/src/types.ts

@@ -112,4 +112,7 @@ export interface IMuxPlayerElement {
     listener: EventListenerOrEventListenerObject,
     options?: boolean | EventListenerOptions
   ): void;
+  startBuffering(): void;
+  stopBuffering(): void;
+  isBuffering(): boolean;
 }

packages/mux-video-react/src/index.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useCombinedRefs } from './use-combined-refs';
-import React, { useEffect, useRef, useState } from 'react';
+import React, { useEffect, useRef, useState, useImperativeHandle } from 'react';
 import PropTypes from 'prop-types';
 import {
   allMediaTypes,
@@ -23,11 +23,17 @@ export type Props = Omit<
 > &
   MuxMediaProps;
 
+export interface MuxVideoRef {
+  startBuffering: () => void;
+  stopBuffering: () => void;
+  isBuffering: () => boolean;
+}
+
 export const playerSoftwareVersion = getPlayerVersion();
 export const playerSoftwareName = 'mux-video-react';
 export { generatePlayerInitTime };
 
-const MuxVideo = React.forwardRef<HTMLVideoElement | undefined, Partial<Props>>((props, ref) => {
+const MuxVideo = React.forwardRef<MuxVideoRef, Partial<Props>>((props, ref) => {
   const {
     playbackId,
     src: outerSrc,
@@ -48,7 +54,17 @@ const MuxVideo = React.forwardRef<HTMLVideoElement | undefined, Partial<Props>>(
   const [src, setSrc] = useState<MuxMediaProps['src']>(toMuxVideoURL(props) ?? outerSrc);
   const playbackCoreRef = useRef<PlaybackCore | undefined>(undefined);
   const innerMediaElRef = useRef<HTMLVideoElement>(null);
-  const mediaElRef = useCombinedRefs(innerMediaElRef, ref);
+  const mediaElRef = useCombinedRefs(innerMediaElRef);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      startBuffering: () => playbackCoreRef.current?.startBuffering?.(),
+      stopBuffering: () => playbackCoreRef.current?.stopBuffering?.(),
+      isBuffering: () => playbackCoreRef.current?.isBuffering?.() ?? false,
+    }),
+    []
+  );
 
   useEffect(() => {
     setSrc(toMuxVideoURL(props) ?? outerSrc);

packages/mux-video/src/base.ts

@@ -226,6 +226,18 @@ export class MuxVideoBaseElement extends CustomVideoElement implements IMuxVideo
     return this.nativeEl?.mux;
   }
 
+  startBuffering() {
+    return this.#core?.startBuffering?.();
+  }
+
+  stopBuffering() {
+    return this.#core?.stopBuffering?.();
+  }
+
+  isBuffering() {
+    return this.#core?.isBuffering?.() ?? false;
+  }
+
   get error() {
     return getError(this.nativeEl) ?? null;
   }

packages/mux-video/src/types.ts

@@ -32,4 +32,7 @@ export interface IMuxVideoBaseElement extends HTMLVideoElement {
     listener: EventListenerOrEventListenerObject,
     options?: boolean | EventListenerOptions
   ): void;
+  startBuffering(): void;
+  stopBuffering(): void;
+  isBuffering(): boolean;
 }