sqr-tube-player

A highly customizable, responsive React video player component tailored for HLS/Live streams and standard video formats (MP4, WebM). Designed to provide a premium viewing experience with support for theater mode, floating mode (PiP), and seamless fallback URLs.

Features

• HLS & Standard Formats: Built-in support for .m3u8 (HLS) streams and regular .mp4 / .webm formats.
• Theater & Fullscreen Mode: Out-of-the-box UI for theater and native fullscreen modes.
• Alternate Sources: Supports providing a fallback/alternate video URL for enhanced reliability.
• Responsive Layout: Adapts beautifully to desktop, tablet, and mobile screens.
• TypeScript Support: Fully typed for an excellent developer experience.

Installation

Install the package via npm:

npm install sqr-tube-player

Since this player is built with React and uses modern icons, ensure you have the required peer dependencies installed:

npm install react react-dom clsx lucide-react hls.js

Note on CSS: You MUST import the package's CSS file in your application's entry point (e.g., src/main.tsx or App.tsx) to ensure the player UI renders correctly.

Basic Usage

import { useState } from "react";
import { VideoPlayer } from "sqr-tube-player";
// IMPORTANT: Import the CSS!
import "sqr-tube-player/dist/style.css";

function App() {
  const [isTheaterMode, setIsTheaterMode] = useState(false);

  return (
    <div style={{ width: "100%", maxWidth: "800px", margin: "0 auto" }}>
      <VideoPlayer
        videoUrl="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
        isHls={true}
        autoplay={true}
        enableTheaterMode={true}
        enableFullscreenMode={true}
        enableFloatingMode={true}
        isTheaterMode={isTheaterMode}
        onTheaterModeChange={() => setIsTheaterMode(!isTheaterMode)}
      />
    </div>
  );
}

export default App;

Props Reference

| Prop | Type | Default | Description | | --- | --- | --- | --- | | videoUrl | string | undefined | The primary URL of the video or HLS stream. | | alternateVideoUrl | string | undefined | Fallback URL if the primary fails. | | isHls | boolean | false | Set to true if videoUrl is an .m3u8 stream. | | isAlternateHls | boolean | false | Set to true if alternateVideoUrl is an .m3u8 stream. | | thumbnailUrl | string | undefined | Poster image URL to display before playback. | | alternateThumbnailUrl | string | undefined | Fallback poster image URL. | | autoplay | boolean | false | Automatically start playback when loaded. | | durationSeconds | number | undefined | Total duration in seconds (useful for UI formatting). | | enableTheaterMode | boolean | false | Enables the theater mode toggle button. | | isTheaterMode | boolean | false | Current state of theater mode. | | onTheaterModeChange | function | undefined | Callback fired when the theater mode button is clicked. | | enableFullscreenMode| boolean | false | Enables the native fullscreen button. | | enableFloatingMode | boolean | false | Enables Picture-in-Picture (PiP) support. | | enableWatchLog | boolean | true | Enables emitting watch log events periodically and on complete. | | onWatchLog | function | undefined | Callback fired every 1 second (while playing) with player state (currentTime, duration, isCompleted, etc.). | | hlsXhrSetup | function | undefined | Callback to intercept and configure HLS.js XHR requests (e.g., adding Authorization headers). |

Advanced: Authenticated Streams

If you are playing streams that require authentication (like signed cookies or custom headers), you can configure the internal hls.js instance using the hlsXhrSetup prop:

<VideoPlayer
  videoUrl="https://secure.example.com/live/index.m3u8"
  isHls={true}
  hlsXhrSetup={(xhr, url) => {
    // Send cookies with cross-origin requests
    xhr.withCredentials = true;
    
    // Add custom auth headers
    if (url.includes("secure.example.com")) {
      xhr.setRequestHeader("Authorization", "Bearer YOUR_TOKEN_HERE");
    }
  }}
/>

License

ISC