coda-player 0.0.0-stage → 2.0.0

package/README.md

@@ -1,3 +1,154 @@
-# 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.
+# Coda-Player
+
+[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)]()
+[![Browser Support](https://img.shields.io/badge/browsers-Chrome%20%7C%20Firefox%20%7C%20Safari-lightgrey.svg)]()
+[![npm downloads](https://img.shields.io/npm/dm/coda-player.svg)](https://www.npmjs.com/package/coda-player)
+[![License](https://img.shields.io/badge/license-MIT-yellow.svg)]()
+
+## 📖 简述
+
+`Coda Player` 是一款专为现代 Web 前端打造的轻量级 HTML5 视频播放器 SDK，开箱即用，全面支持主流视频格式与 .m3u8 (HLS) 直播/点播流，UI 界面与功能高度可定制。
+
+1. **核心定位**:
+   - 为开发者提供开箱即用、有极致定制能力的视频播放器组件。
+
+2. **核心能力**：
+   - **支持主流操作**：提供播放/暂停、进度跳转、平滑音量调节、多档倍速切换、全屏控制及悬浮控制栏交互，交互习惯兼容主流播放器。
+   - **支持原生事件**：内置强大的事件总线（Event Bus），支持全面监听播放器状态与底层媒体原生事件，保证开发者自定义功能开发需求。
+   - **支持多开画面**：支持播放器多开场景，每个播放器互不影响，且能安全注销，保障页面的顺畅播放。
+
+3. **达成目标**:
+   - **开箱即用**：简单配置，让开发者能够快速在项目中落地业务需求。
+   - **自由扩展**：播放器可继承/可扩展架构与样式表变量体系可重写UI，完美满足各类深度换肤与二次开发需求。
+
+## 🌟 核心特性
+
+- **极致轻量的体积**: 底层基于原生 HTML5 video标签与原生 DOM 操作，仅引入轻量级 hls.js 处理切片流，无冗余的框架负担。
+- **前后端一体化服务**：SDK开箱支持 MP4、WebM、OGG 以及 .m3u8 流式切片，其他视频格式无法播放可以使用`Coda Media Server`进行大文件视频上传并自动转码与切片即可播放。
+- **无缝衔接的事件**：内置标准 .on() 与 .off() 订阅机制，完美融合自定义高阶事件（如 statechange, timeupdate）与所有 HTML5 视频原生事件。
+- **多实例与键盘隔离**：支持单页面多实例独立运行，具备鼠标悬停焦点隔离的快捷键支持。
+
+【提示】`Coda Player`不支持flash/flv格式的视频播放，如需支持flash/flv格式请使用[Coda player sdk](https://www.npmjs.com/package/coda-player-sdk)
+
+## 📌 播放器属性/方法/事件
+
+| 类型   | 名称                                  | 描述                                        |
+| ------ | ------------------------------------- | ------------------------------------------- |
+| 📦属性 | `container: HTMLElement`              | 播放器挂载的容器 DOM 元素                   |
+| 📦属性 | `videoElement: HTMLVideoElement`      | 底层原生的 HTML5 video 元素                 |
+| 📦属性 | `currentTime: number`                 | 获取当前视频的播放时间进度（以秒为单位）    |
+| 📦属性 | `duration: number`                    | 获取视频的总时长（以秒为单位）              |
+| 📦属性 | `paused: boolean`                     | 视频当前是否处于暂停状态                    |
+| 📦属性 | `volume: number`                      | 当前音量大小（取值范围 0 到 1）             |
+| 📦属性 | `muted: boolean`                      | 当前是否处于静音状态                        |
+| 📦属性 | `playbackRate: PlaybackRate`          | 当前播放倍速                                |
+| 📦属性 | `state: PlayerState`                  | 播放器当前的内部状态                        |
+| ⚙️方法 | `play()`                              | 异步开始播放视频                            |
+| ⚙️方法 | `pause()`                             | 暂停视频播放                                |
+| ⚙️方法 | `seek(time: number)`                  | 跳转到指定的播放时间点（秒）                |
+| ⚙️方法 | `setVolume(volume: number)`           | 设置播放音量大小（0 到 1）                  |
+| ⚙️方法 | `setMuted(muted: boolean)`            | 开启或关闭静音模式                          |
+| ⚙️方法 | `setPlaybackRate(rate: PlaybackRate)` | 设置播放倍速                                |
+| ⚙️方法 | `toggleFullScreen()`                  | 切换全屏显示 / 退出全屏模式                 |
+| ⚙️方法 | `destroy()`                           | 销毁播放器实例，清空 DOM 并释放资源         |
+| ⚙️方法 | `on(event, callback)`                 | 订阅播放器事件（和原生HTML5 video事件同名） |
+| ⚙️方法 | `off(event, callback)`                | 取消订阅播放器事件                          |
+| 📡事件 | `videoElement.addEventListener(...)`  | 兼容直接监听底层视频元素的原生媒体事件      |
+
+## 🎨 UI定制
+
+coda-player 的所有外观均通过 CSS 变量 进行控制。外部用户无需修改 SDK 源码，只需在自己的样式表中针对播放器容器重写对应变量，即可实现深度换肤和 UI 定制：
+
+```css
+/* 外部业务系统的样式覆盖 */
+#player-container {
+  /* 1. 色彩与主题体系 */
+  --coda-theme-color: #3b82f6; /* 主题高亮色 */
+  --coda-text-color: #ffffff; /* 文本与图标颜色 */
+
+  /* 2. 控件背景与遮罩体系 */
+  --coda-bg-color: rgba(0, 0, 0, 0.75); /* 基础遮罩与悬浮提示背景 */
+  --coda-control-bg: linear-gradient(transparent, rgba(0, 0, 0, 0.85)); /* 控制栏渐变背景 */
+  --coda-menu-bg: rgba(20, 20, 20, 0.95); /* 弹出菜单背景（如倍速菜单） */
+
+  /* 3. 视觉形状与字体体系 */
+  --coda-border-radius: 8px; /* 容器、卡片及弹出菜单圆角 */
+  --coda-font-family:
+    -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; /* 全局字体 */
+
+  /* 4. 尺寸与间距体系 */
+  --coda-progress-height: 6px; /* 进度条粗细 */
+  --coda-control-padding: 12px 16px; /* 控制栏内边距 */
+
+  /* 5. 居中播放/暂停按钮定制体系 */
+  --coda-center-btn-size: 64px; /* 按钮尺寸大小 */
+  --coda-center-btn-bg: rgba(0, 0, 0, 0.6); /* 按钮背景色 */
+  --coda-center-btn-color: #3b82f6; /* 图标颜色（默认跟随主题色） */
+  --coda-center-btn-hover-scale: 1.1; /* 鼠标悬停时的放大倍数 */
+}
+```
+
+## ⌨️ 键盘快捷键
+
+当鼠标悬停在播放器容器内时，支持以下快捷键操作：
+
+- Space：播放 / 暂停切换
+- Enter：进入 / 退出全屏
+- ArrowUp：增大音量 (+10%)
+- ArrowDown：减小音量 (-10%)
+
+## 🚀 使用指南
+
+1. 安装
+
+在您的项目中引入 coda-player-sdk ：
+
+```bash
+npm install coda-player
+```
+
+2. 基础 HTML 容器
+
+```html
+<div id="player-container"></div>
+```
+
+3. 代码集成示例
+
+```typescript
+import {CodaPlayer} from 'coda-player';
+
+// 初始化播放器实例
+const player = new CodaPlayer({
+  container: '#player-container', // 传入容器 DOM 或 CSS 选择器字符串
+  url: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8', // 支持 .mp4 或 .m3u8
+  themeColor: '#3b82f6', // 自定义主题色（可选）
+  autoplay: false, // 是否自动播放
+  muted: true, // 是否默认静音
+  poster: 'https://example.com/poster.jpg', // 封面图（可选）
+});
+
+// 1. 监听播放与暂停
+player.on('play', () => {
+  console.log('事件触发：视频开始播放');
+});
+
+player.on('pause', () => {
+  console.log('事件触发：视频已暂停');
+});
+
+// 2. 监听进度更新
+player.on('timeupdate', (currentTime: number) => {
+  console.log('当前播放时间:', currentTime);
+});
+
+// 3. 监听内部状态总线变化 (idle / loading / playing / paused / ended / error)
+player.on('statechange', (state: string) => {
+  console.log('播放器状态变更为:', state);
+});
+
+// 4. 取消订阅
+const handlePlay = () => {};
+player.on('play', handlePlay);
+player.off('play', handlePlay);
+```

package/index.d.ts

@@ -0,0 +1,5 @@
+import './styles/coda-player.css';
+export type { PlayerState, PlaybackRate, PlayerTheme, PlayerOptions, IPlayer } from './types';
+export { BasePlayer } from './player/base.player';
+export { CodaPlayer } from './player/coda.player';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,0BAA0B,CAAC;AAGlC,YAAY,EAAC,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAC,MAAM,SAAS,CAAC;AAC5F,OAAO,EAAC,UAAU,EAAC,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAC,UAAU,EAAC,MAAM,sBAAsB,CAAC"}

package/index.js

@@ -0,0 +1,3 @@
+import './styles/coda-player.css';
+export { BasePlayer } from './player/base.player';
+export { CodaPlayer } from './player/coda.player';