hx-player 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# HxPlayer
+
+华下云 Web 播放器。本目录是独立项目雏形，后续可单独拆成仓库使用。
+
+- 已移除 `H265Player` 软解播放器
+- 点播：`src/videoPlayer`
+- 直播：`src/livePlayer`（WebRTC / WHEP）
+- 构建：Vite（ES + UMD）
+- 创建方式：`new HxPlayer()`（不再使用 `YlcPlayer.create()`）
+
+开发构建需要 **Node.js >= 18**（Vite 6）。本机可用 `nvm use 22`。
+
+## 安装
+
+```bash
+cd player_rebuild
+npm install
+```
+
+## 开发
+
+```bash
+npm run dev
+```
+
+默认打开 `demo/index.html`。
+
+## 构建
+
+```bash
+npm run build
+```
+
+产物：
+
+- `dist/hx-player.js` ESM
+- `dist/hx-player.umd.js` 浏览器 script 标签
+
+## 使用
+
+### ESM
+
+```js
+import HxPlayer from 'hx-player'
+
+const player = new HxPlayer({
+  id: 'player-container-id',
+  url: 'https://example.com/playlist.m3u8',
+  appId: 'xxx'
+})
+
+player.ready.then(() => player.play())
+player.on('play', () => {})
+player.destroy()
+```
+
+也支持容器 id 作为第一参数：
+
+```js
+const player = new HxPlayer('player-container-id', {
+  url: 'https://example.com/video.mp4'
+})
+```
+
+`url` 与原先的 `sourceURL` 等价，两者都可传。
+
+如果通过 `fileId` + `secret_id` 换地址，初始化是异步的，请使用 `player.ready`：
+
+```js
+const player = new HxPlayer({
+  id: 'player-container-id',
+  appId: 'xxx',
+  fileId: 'xxx',
+  secret_id: 'xxx',
+  timestamp: 0,
+  sign: 'xxx'
+})
+await player.ready
+player.play()
+```
+
+### 直播
+
+```js
+const player = new HxPlayer({
+  id: 'live-container-id',
+  mode: 'live',
+  whepUrl: 'https://example.com/whep'
+})
+```
+
+也可传 `protocol: 'webrtc'`、`mediaStream`、`getStream`、`signaling`。
+
+### UMD
+
+```html
+<script src="./dist/hx-player.umd.js"></script>
+<script>
+  const player = new HxPlayer({
+    id: 'player-container-id',
+    url: 'https://example.com/playlist.m3u8'
+  })
+</script>
+```
+
+## 常用方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `play()` / `pause()` | 播放 / 暂停 |
+| `seek(time)` | 跳转秒 |
+| `currentTimeSec()` / `duration()` | 当前时间 / 总时长 |
+| `changeSrc(url)` | 切换片源 |
+| `muted(true\|false)` | 静音 |
+| `setPlaybackRate(rate)` | 倍速 |
+| `switchLine(line)` | 切换线路 |
+| `on(name, cb)` / `off(name, cb)` | 事件 |
+| `destroy()` | 销毁 |
+
+## 目录
+
+```
+src/
+  index.js          HxPlayer 入口
+  videoPlayer/      点播（HLS / FLV / MP4）
+  livePlayer/       直播（WebRTC）
+  logs/             日志
+  utils/            工具
+```