@flow-player/browser-runtime

ESM browser runtime for H.264 / H.265 FLV live and VOD playback with WebCodecs, WebGL2, and a Rust-powered WASM demux core. Zero npm dependencies.

Quick Start (Live)

import { flowLivePlayer } from "@flow-player/browser-runtime";
// Vite: import PlayerWorker from "@flow-player/browser-runtime/worker?worker";

const player = new flowLivePlayer({
  canvas: document.getElementById("player-canvas") as HTMLCanvasElement,
  workerFactory: () => new PlayerWorker(),
  useWCS: true,
  // wasmUrl is optional — auto-resolved via import.meta.url on Vite / webpack 5
});

player.on("play", () => console.log("playing"));
player.on("stats", (stats) => console.log(stats.fps, "fps"));
player.on("diagnostic", (detail) => console.warn("normalization:", detail));

await player.play("https://example.com/live.flv");

Quick Start (VOD)

import { flowVodPlayer } from "@flow-player/browser-runtime";

const player = flowVodPlayer({
  canvas: document.getElementById("vod-canvas") as HTMLCanvasElement,
  workerFactory: () => new Worker(
    new URL("@flow-player/browser-runtime/worker", import.meta.url),
    { type: "module" }
  ),
  // wasmUrl is optional — auto-resolved via import.meta.url on Vite / webpack 5
});

player.playList([
  { url: "/vod/1.mp4", startTimestamp: 0, endTimestamp: 60000, timeLen: 60, fileSize: 1024000, channelID: 1, RecordType: 0 },
]);

Worker Setup

The module worker is at @flow-player/browser-runtime/worker.

Bundler	Import
Vite	`import PlayerWorker from "@flow-player/browser-runtime/worker?worker"`
webpack 5	`new Worker(new URL("@flow-player/browser-runtime/worker", import.meta.url))`
esbuild	`new Worker(new URL("@flow-player/browser-runtime/worker", import.meta.url), { type: "module" })`

WASM Deployment

The .wasm artifact (~147 KB release) is included at wasm/flow_player_wasm.wasm in the npm package.

Zero-config (recommended for Vite / webpack 5): When using a bundler that supports new URL(url, import.meta.url) asset handling, the player automatically resolves the WASM path. No wasmUrl needed.

Manual deployment (fallback): Copy wasm/flow_player_wasm.wasm to your static assets and pass the URL:

new flowLivePlayer({
  wasmUrl: "https://cdn.example.com/flow_player_wasm.wasm",
  // ...
});

API Reference

`flowLivePlayer`

Method	Description
`play(url)`	Start streaming
`pause()`	Pause
`close()` / `destroy()`	Stop and release resources
`screenshot(filename?, format?, quality?, type?)`	Capture frame → `string \| Blob \| void`
`startRecord(name?, type?)` / `stopRecordAndSave()` / `isRecording()`	Recording
`mute()` / `cancelMute()` / `setVolume(v)` / `isMute()`	Audio control
`setScaleMode(m)` / `setRotate(deg)` / `resize(w, h)` / `clearView()`	Display
`setFullscreen(f)` / `toggleControlBar(b)` / `getControlBarShow()`	Fullscreen
`setKeepScreenOn()`	Prevent screen sleep

Property	Type
`metrics`	`RuntimeMetrics` (`chunksPushed`, `firstFrameAt`, ...)
`loaded`, `playing`, `muted`, `volume`	State booleans/numbers
`scaleMode`, `fullscreen`, `rotate`	Display state

Key Events	Payload
`play`, `pause`, `destroy`	`void`
`start`	`void` (first frame rendered)
`stats`	`FlowLivePlayerStats` `{buf, fps, abps, vbps, ts}`
`videoInfo`	`FlowLivePlayerVideoInfo` `{width, height, codec, codecString}`
`error`	`unknown`
`diagnostic`	`unknown` (stream normalization detail)
`timeout`	`FlowLivePlayerTimeoutDetail`
`resize`	`FlowLivePlayerResizeDetail`
`clearView`	`FlowLivePlayerClearViewDetail`
`mute` / `fullscreen`	`boolean`
`volume`	`number`
`scaleMode`	`FlowLivePlayerScaleMode`
`rotate`	`number`
`recordStart` / `recordEnd` / `recordError`	`unknown`
`recordingTimestamp`	`number` (seconds)

`flowVodPlayer`

Method	Description
`playList(segments: FlowVodRecordSegment[])`	Load and start VOD playback
`seek(timestampMs)`	Seek to absolute millisecond timestamp
`pause()` / `resume()`	Playback control
`nextSegment()` / `previousSegment()`	Segment navigation
`nextFrame()` / `previousFrame()`	Frame-stepping
`setRate(rate)`	Playback speed (e.g. `2` = 2×)
`setGapPolicy(policy: FlowVodGapPolicy)`	Gap handling (`"jump"` or `"hold"`)
`destroy()`	Stop and release resources

Property	Type
`state`	`"idle" \| "loading" \| "playing" \| "paused" \| ...`
`rate`	`number`
`snapshot`	`FlowVodPlayerSnapshot`
`videoElement`	`HTMLVideoElement \| null` (MSE mode only)

`FlowVodRecordSegment`

interface FlowVodRecordSegment {
  url: string;
  startTimestamp: number;
  endTimestamp: number;
  timeLen: number;
  fileSize: number;
  channelID: number | string;
  RecordType: number | string;
}

Tree Shaking

Package is "sideEffects": false with per-module output. Modern bundlers (Vite, webpack 5, Rollup, esbuild) will remove unused code automatically. Importing only flowLivePlayer excludes VOD from your bundle.

License

MIT

Development

# Build WASM (requires Rust wasm32-unknown-unknown target)
npm run build:wasm

# Build npm-grade package
npm run build:package

# Verify before publish
npm run publish:check

# Full test suite
npm run test:smoke

# Type check
npm run typecheck