@hau.nv/hevc-player

Trình phát HEVC/H.265 cho web: giải mã bằng ffmpeg.wasm + vẽ WebGL canvas, tự fallback <video> native khi trình duyệt hỗ trợ HEVC phần cứng. Hỗ trợ MP4 trực tiếp và HLS (.m3u8), seek tới giây N, tự retry lỗi mạng tạm thời. Không phụ thuộc Tailwind — style tự chứa.

Cài đặt

npm install @hau.nv/hevc-player

react/react-dom là peer dependency (bạn đã có sẵn trong app).

Asset ffmpeg

Player nạp 4 file lõi tại /hevc/... lúc runtime. Copy chúng vào thư mục tĩnh:

npx hevc-copy-assets public      # Next / Vite → public/hevc

Hoặc dùng plugin của bundler (giữ nguyên cấu trúc ffmpeg/):

• Vite: vite-plugin-static-copy copy node_modules/@hau.nv/hevc-player/assets/hevc/* → hevc.
• Next: thêm "predev"/"prebuild": "hevc-copy-assets public" vào scripts.

Host asset ở nơi khác (CDN…)? Ghi đè:

import { configureHevc } from "@hau.nv/hevc-player";
configureHevc({
  ffmpegCorePath: "https://cdn.example.com/hevc/ffmpeg-core.js",
  ffmpegWasmPath: "https://cdn.example.com/hevc/ffmpeg-core.wasm",
  ffmpegWrapperPath: "https://cdn.example.com/hevc/ffmpeg/ffmpeg.js",
});

Dùng

import { HevcPlayer } from "@hau.nv/hevc-player";

<HevcPlayer url="/video.mp4" sourceType="mp4" autoPlay muted />;

Next.js (App Router) — client-only:

import dynamic from "next/dynamic";
const HevcPlayer = dynamic(
  () => import("@hau.nv/hevc-player").then((m) => m.HevcPlayer),
  { ssr: false },
);

Props chính

| Prop | Kiểu | Mô tả | |------|------|------| | url | string \| null | Nguồn .mp4 / .m3u8 | | sourceType | "auto" \| "mp4" \| "hls" | Mặc định auto (đoán theo đuôi URL) | | autoPlay / muted | boolean | Phát ngay (muted để trình duyệt cho tự chạy) | | fps | number | FPS decode/render mục tiêu (nhẹ CPU khi nhiều player) | | optimized | boolean | Ưu tiên substream độ phân giải thấp (HLS master) | | releaseOffscreen | boolean | Dừng decode khi cuộn khỏi viewport | | renderOverlay | (player) => ReactNode | Overlay điều khiển tùy biến |

Seek (tua tới giây N)

Player expose API mệnh lệnh qua ref (HevcPlayerHandle). Vì next/dynamic không forward ref, hãy import trực tiếp trong 1 Client Component ("use client"):

"use client";
import { useRef } from "react";
import { HevcPlayer, type HevcPlayerHandle } from "@hau.nv/hevc-player";

export default function Player() {
  const ref = useRef<HevcPlayerHandle>(null);
  return (
    <>
      <HevcPlayer ref={ref} url="/video.mp4" sourceType="mp4" autoPlay muted />
      <button onClick={() => ref.current?.seek(30)}>Tua tới 30s</button>
    </>
  );
}

HevcPlayerHandle: seek(second), play(), pause(), resume(), toggle(), stop(). (Nếu dùng hook useHevcPlayer trực tiếp thì các hàm này có sẵn trong kết quả trả về.)

Cơ chế seek:

• HEVC/canvas (WASM): decode lại từ keyframe (RAP) ≤ N rồi bỏ frame thừa (decode nhưng không render) tới đúng giây N → hiển thị frame đích rồi phát tiếp. Độ chính xác ~1 frame (do resample fps).
• Native <video>: dùng currentTime (browser tự tua).

Điều kiện seek (nhánh WASM MP4): chỉ tua được khi nguồn hỗ trợ HTTP Range HOẶC đã cache full-file (server trả 200 nguyên file). Không thoả → log error "Không thể seek do thiếu Range". HLS/live không seek được → log error.

Chỉ dùng cho playback (không có thanh duration sẵn — tự dựng UI tua nếu cần).

Xử lý lỗi mạng & retry

Player không giết stream vì lỗi tạm thời:

• HLS nhánh WASM (ffmpeg): lỗi tải playlist/init → tự retry (chờ rồi poll lại); lỗi 1 segment → bỏ qua, phát tiếp. Không set error.
• HLS nhánh native (hls.js): lỗi non-fatal để hls.js tự phục hồi. Lỗi fatal cứu được → tự thử lại tối đa 3 lần: NETWORK_ERROR → startLoad(), MEDIA_ERROR → recoverMediaError(). Bộ đếm reset khi phát ổn định lại (buffer thêm fragment) nên mạng chớp tắt lặp lại vẫn tự hồi phục. Chỉ khi lỗi không cứu được hoặc hết lượt mới chuyển status: "error" (lúc khởi động thì fallback sang nhánh WASM).

Bắt trạng thái/lỗi qua prop onError hoặc status ("loading" | "playing" | "paused" | "ended" | "error") và log qua onLog.

License

MIT