qalbplayer

qalbplayer is a custom React video player package for React and Next.js App Router projects. It supports classic video playback, vertical shorts, and live streams using native HTML5 video with dynamic hls.js loading for .m3u8 streams.

Install

npm install qalbplayer

Import the component and bundled CSS:

"use client";

import { QalbPlayer } from "qalbplayer";
import "qalbplayer/style.css";

export default function Page() {
  return (
    <QalbPlayer
      url="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
      mode="video"
      autoplay={false}
    />
  );
}

Next.js App Router

Add the CSS import in app/layout.tsx or directly inside a client component:

import "qalbplayer/style.css";

Use the player only inside a client component because browser video APIs, Fullscreen, PiP, and keyboard events require the client runtime.

Props

| Prop | Type | Required | Description | |---|---|---:|---| | url | string | Yes | MP4, WebM, or HLS .m3u8 media URL. | | mode | 'video' \| 'shorts' \| 'live' | Yes | Selects the UI and interaction model. | | poster | string | No | Optional video poster image. | | autoplay | boolean | No | Attempts autoplay. Muted autoplay is used when needed by browsers. | | className | string | No | Optional class added to the root player element. |

Modes

video

A 16:9 cinematic player with custom controls, scrubber, hover timestamps, current/total time, settings, speed selection, HLS quality selection, theater mode, Picture-in-Picture, fullscreen, keyboard shortcuts, double-click skip, and long-press speed boost.

shorts

A 9:16 vertical player for reel-style playback. It loops automatically and uses tap/click to mute or unmute. The timeline is minimal and does not show timestamp text.

live

A live-stream layout with a glowing LIVE badge, connection timer, disabled scrubbing, and an offline/reconnecting card for fatal HLS playback errors.

Keyboard shortcuts

When the player is focused:

| Key | Action | |---|---| | Space | Play / pause | | Left / Right | Seek -5s / +5s in video mode | | Up / Down | Volume up / down | | M | Mute / unmute | | F | Fullscreen | | T | Theater mode |

Local package test on VPS

After extracting the ZIP:

cd qalbplayer
npm install --no-audit --no-fund
npm run verify
npm pack

Then test it in a Next.js app:

cd ~
npx create-next-app@latest qalbplayer-test
cd qalbplayer-test
npm install ../qalbplayer/qalbplayer-1.0.2.tgz

Use it in src/app/page.tsx:

"use client";

import { QalbPlayer } from "qalbplayer";
import "qalbplayer/style.css";

export default function Home() {
  return (
    <main style={{ minHeight: "100vh", background: "#020617", padding: 24 }}>
      <QalbPlayer
        url="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
        mode="video"
      />
    </main>
  );
}

Run:

npm run dev -- --host 0.0.0.0

Open http://YOUR_SERVER_IP:3000.

Publish

npm login
npm publish --access public

If the package name is already taken, change name in package.json to a scoped package such as @your-npm-name/qalbplayer, then publish with public access.

Notes

The distributed package includes prebuilt dist/ files and does not require Rollup, tsup, esbuild, or rimraf during installation. This avoids native optional dependency failures on small VPS environments.