@streamq/player

Version 1.1.0 — Official cinematic React player for StreamQ.

Start here: https://www.streamq.in/ — live demo, pricing, FAQ, and production sq_live_* license keys.
This npm package is the SDK shown on the site: one install, one <StreamqPlayer /> component, HLS/DASH/live/subtitles, and built-in license gating.

One npm package. One React component. Production-ready streaming.

npm install @streamq/player react react-dom

License: Proprietary commercial software. See LICENSE in this package. Production use requires a valid sq_live_* license id — request one at streamq.in.

Peers: react ≥ 18, react-dom ≥ 18

Links

| | | |-|-| | Website (demo, docs, pricing) | https://www.streamq.in/ | | npm | https://www.npmjs.com/package/@streamq/player | | Repository | https://github.com/sazzzzid/streamq | | Issues | https://github.com/sazzzzid/streamq/issues | | EULA | https://github.com/sazzzzid/streamq/blob/main/EULA.md |

Quick start

import '@streamq/player/baseline.css';

import { StreamqPlayer } from '@streamq/player';

export default function App() {
  return (
    <StreamqPlayer
      license="sq_live_YOUR_LICENSE_ID"
      source={{ src: 'https://example.com/master.m3u8', type: 'hls' }}
    />
  );
}

Try before you buy — open the live demo on streamq.in or use the public demo key:

<StreamqPlayer license="sq_live_D8JK2LQ9MNP4" source={...} />

DASH:

<StreamqPlayer
  license="sq_live_YOUR_LICENSE_ID"
  source={{ src: 'https://example.com/manifest.mpd', type: 'dash' }}
/>

Import @streamq/player/baseline.css once in your app entry (see Styling).

What's new in 1.1.0

• StreamqReelsFeed — vertical short-form feed with snap scrolling and windowed player mounts
• Center playback feedback — play/pause puck on tap and gesture seek
• Mobile polish — background playback, auto-rotate, brightness clamp, improved touch gestures
• Quality HD badge — settings panel indicator for HD renditions
• Adaptive buffer policy — smarter HLS/DASH load and buffer targets (engines still lazy-loaded on first play)
• Settings & chrome — refreshed cinematic settings overlay and transport controls

Full changelog: CHANGELOG.md.

License (required)

Every StreamqPlayer must receive a license prop. This is how StreamQ validates commercial/production use.

<StreamqPlayer license="sq_live_D8JK2LQ9MNP4" source={...} />

| Item | Detail | |------|--------| | Format | sq_live_ + uppercase alphanumeric | | Firebase config | Managed by StreamQ (baked into the package) — not your app | | Your setup | Pass the license id string only |

How validation works

1. On mount, the player subscribes to Firestore document licenses/{licenseId}.
2. Document fields: active (boolean), plan, company, version.
3. active: true → playback allowed.
4. active: false, missing doc, invalid id, or network error → playback blocked.
5. Changes to active apply in real time — no page refresh.

Built-in denied UI

When the license is invalid, a full-screen overlay appears. You do not need custom error UI.

| Situation | Overlay title | |-----------|----------------| | No / empty license prop | License required | | Wrong id format | Invalid license | | Id not in Firestore | License not found | | Doc exists, active: false | License inactive | | Firestore / network error | License verification failed |

While validation is in progress (pending), playback stays blocked but no error overlay is shown yet.

Plans & pricing

| Plan | Price | Best for | |------|-------|----------| | Evaluation | Free | Public demo key on streamq.in | | Player | $49/mo or $499/yr | One production app | | Studio | $199/mo or $1,999/yr | Agencies — 5 client keys | | Premium | $499/mo or $4,999/yr | DRM, analytics, custom UI SDK, white-label |

Request a production key at streamq.in. License terms: EULA.

For agencies, DRM (Premium), benchmarks, and full FAQ, see streamq.in.

Sources & adapters

| source.type | Engine loaded | |---------------|---------------| | hls | hls.js (lazy, on first HLS load) | | dash | shaka-player (lazy, on first DASH load) | | Progressive / MP4 | Native path via bundled DASH adapter |

Only the engine for the format you play is downloaded at runtime. Safari may play HLS natively without hls.js.

Initial @streamq/player bundle is ~79 KB gzip (full UI + license gate). Streaming engines load on first play — your marketing pages stay fast.

Styling

StreamqPlayer reads --sq-* CSS custom properties. Without tokens the player renders but looks unstyled.

Built-in baseline (recommended)

import '@streamq/player/baseline.css';

Export: @streamq/player/baseline.css

Full theme system (optional)

import '@streamq/themes/css/base.css';

Import themes after baseline to override --sq-* variables.

Custom tokens

:root {
  --sq-color-accent: #e11d48;
  --sq-radius-md: 0.75rem;
}

Layout

Standard embed — parent supplies width; default 16:9 until video metadata loads.

Full-viewport:

<StreamqPlayer
  fillViewport
  license="sq_live_YOUR_LICENSE_ID"
  radius="none"
  source={{ src: 'https://example.com/master.m3u8', type: 'hls' }}
/>

StreamqPlayer API

import '@streamq/player/baseline.css';
import { StreamqPlayer } from '@streamq/player';

<StreamqPlayer
  license="sq_live_YOUR_LICENSE_ID"
  source={{ src: 'https://example.com/stream.mpd', type: 'dash' }}
  layout="default"
  live={false}
  options={{ autoplay: false }}
  immersiveFullscreen
  videoFit="contain"
/>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | license | string | — | Required. StreamQ license id (sq_live_*). | | source | SourceInput | — | Media source (HLS, DASH, or progressive) | | options | PlayerFactoryOptions | — | Plugins, recovery, autoplay, etc. | | layout | 'default' \| 'compact' \| 'mobile' \| 'live' | 'default' | Chrome layout preset | | live | boolean | false | Live stream mode | | settingsOpen | boolean | — | Controlled settings panel state | | defaultSettingsOpen | boolean | false | Uncontrolled initial settings state | | onSettingsOpenChange | (open: boolean) => void | — | Settings panel callback | | settingsContent | ReactNode | — | Replace default settings UI | | renderSubtitles | boolean | true | Built-in subtitle overlay | | immersiveFullscreen | boolean | false | object-fit: cover in fullscreen | | fillViewport | boolean | false | Edge-to-edge full viewport embed | | dynamicAspectRatio | boolean | true | Follow video metadata dimensions | | videoFit | 'contain' \| 'cover' | — | Force video fit | | videoProps | VideoProps | — | Forwarded to inner <Video> | | title / subtitle | string | — | Top chrome labels | | controlsLeft / controlsRight | ReactNode | — | Extra footer controls | | radius | 'none' \| … | — | Surface corner radius |

The licensing plugin is injected automatically from the license prop — do not add a separate licensing plugin.

Layouts

| Layout | Best for | |--------|----------| | default | Desktop / general VOD | | compact | Smaller embeds | | mobile | Touch-first | | live | Live streams with jump-to-live |

Reels feed

Vertical short-form playback with snap scrolling:

import { StreamqReelsFeed } from '@streamq/player';

<StreamqReelsFeed
  license="sq_live_YOUR_LICENSE_ID"
  items={[
    {
      id: '1',
      title: 'Clip one',
      poster: 'https://example.com/poster.jpg',
      source: { src: 'https://example.com/clip.m3u8', type: 'hls' },
    },
  ]}
/>

Optional plugins

Premium tier adds DRM playback (Widevine, PlayReady, FairPlay), analytics, casting, ads, and thumbnails. Contact StreamQ or visit streamq.in for Premium.

Features

• License gate — Firestore validation, real-time revoke, built-in denied overlay
• Playback — play/pause, seek, volume, mute, quality, audio tracks
• Subtitles — track picker, DOM overlay
• Live — live edge, jump-to-live, live seekbar
• PiP & fullscreen — when supported
• Keyboard & gestures — shortcuts, double-tap seek, swipe, center feedback puck
• Mobile — background playback, auto-rotate, gesture hints
• Accessibility — ARIA announcer, focus manager, keyboard scope
• Buffering — cinematic buffering overlay
• Settings — quality, audio, subtitles, HD badge

Package exports

| Import | Description | |--------|-------------| | @streamq/player | StreamqPlayer, StreamqReelsFeed, layouts, orchestration helpers | | @streamq/player/baseline.css | Built-in --sq-* design tokens |

Dependencies

| | | |-|-| | Runtime | firebase | | Peer | react ≥ 18, react-dom ≥ 18 |

HLS/DASH adapters, React bindings, and UI primitives are bundled inside @streamq/player. Adapter engines (hls.js, shaka-player) still load lazily at playback time.

When to use something else

| Need | Package | |------|---------| | Headless playback only | @streamq/core + @streamq/hls or @streamq/dash | | Custom UI without the preset | @streamq/react + @streamq/ui | | DRM, analytics, casting | Premium plugins — streamq.in |

License

Proprietary commercial software — SEE LICENSE IN LICENSE.

Production deployment requires a valid StreamQ license. See License (required) for the runtime license prop.

Third-party attributions: NOTICE.