npm package: @mxmweb/veoviewer
Description: 一个基于 [Video.js](https://github.com/videojs/video.js) 封装的 React 视频播放器组件，支持段落截取、时间轴标记、自定义控制条等高级功能。
Author: hanfeng_Zhang
Latest version: 1.0.4

# VeoViewer - 基于 Video.js 的视频播放器

一个基于 [Video.js](https://github.com/videojs/video.js) 封装的 React 视频播放器组件，支持段落截取、时间轴标记、自定义控制条等高级功能。

## 功能特性

### 🎬 基础播放功能
- 播放/暂停控制
- 音量调节与静音
- 播放速度调节 (0.5x - 2x)
- 进度条拖拽跳转
- 响应式设计

### 📝 段落管理
- 视频段落标记与颜色区分
- 段落快速跳转播放
- 段落编辑与管理
- 时间轴可视化显示

### 🎨 界面定制
- 多种主题支持 (default, dark, minimal)
- 可插拔控制组件
- 自定义样式支持
- 移动端适配

### ⚡ 高级功能
- 键盘快捷键支持
- 事件回调系统
- TypeScript 类型支持
- 无障碍访问支持

## 快速开始

### 安装依赖

```bash
# 依赖已包含在项目中
pnpm install
```

### 启动演示

```bash
# 启动开发服务器
pnpm dev

# 访问 http://localhost:5173 查看演示
```

### 基础使用

```tsx
import { VideoPlayer } from '@mxmweb/veoviewer';

function App() {
  const segments = [
    {
      id: 'intro',
      start: 0,
      end: 10,
      label: '开场介绍',
      color: '#3b82f6',
    },
    {
      id: 'main',
      start: 15,
      end: 25,
      label: '主要内容',
      color: '#10b981',
    },
  ];

  return (
    <VideoPlayer
      src="https://example.com/video.mp4"
      poster="https://example.com/poster.jpg"
      segments={segments}
      showControls={true}
      showTimeline={true}
      showSegments={true}
      onReady={(player) => console.log('播放器准备就绪')}
      onPlay={() => console.log('开始播放')}
      onPause={() => console.log('暂停播放')}
    />
  );
}
```

### 高级使用

```tsx
import { VideoPlayer, VideoPlayerRef } from '@mxmweb/veoviewer';
import { useRef } from 'react';

function AdvancedApp() {
  const playerRef = useRef<VideoPlayerRef>(null);

  const handleAddSegment = () => {
    const newSegment = {
      id: `segment-${Date.now()}`,
      start: 30,
      end: 40,
      label: '新段落',
      color: '#f59e0b',
    };
    playerRef.current?.actions.addSegment(newSegment);
  };

  const handlePlaySegment = (segmentId: string) => {
    const segment = playerRef.current?.state.segments.find(s => s.id === segmentId);
    if (segment) {
      playerRef.current?.actions.playSegment(segment);
    }
  };

  return (
    <div>
      <VideoPlayer
        ref={playerRef}
        src="https://example.com/video.mp4"
        theme="dark"
        onSegmentChange={(segment) => {
          console.log('当前段落:', segment);
        }}
      />
      <button onClick={handleAddSegment}>添加段落</button>
    </div>
  );
}
```

## API 参考

### VideoPlayer Props

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `src` | `string` | - | 视频源地址 |
| `poster` | `string` | - | 视频封面图 |
| `segments` | `VideoSegment[]` | `[]` | 视频段落配置 |
| `showControls` | `boolean` | `true` | 是否显示控制条 |
| `showTimeline` | `boolean` | `true` | 是否显示时间轴 |
| `showSegments` | `boolean` | `true` | 是否显示段落列表 |
| `theme` | `'default' \| 'dark' \| 'minimal'` | `'default'` | 主题样式 |
| `onReady` | `(player: any) => void` | - | 播放器准备就绪回调 |
| `onPlay` | `() => void` | - | 播放事件回调 |
| `onPause` | `() => void` | - | 暂停事件回调 |
| `onTimeUpdate` | `(currentTime: number) => void` | - | 时间更新回调 |
| `onSegmentChange` | `(segment: VideoSegment \| null) => void` | - | 段落变化回调 |

### VideoSegment 接口

```tsx
interface VideoSegment {
  id: string;           // 段落唯一标识
  start: number;        // 开始时间（秒）
  end: number;          // 结束时间（秒）
  label: string;        // 段落标签
  color?: string;       // 段落颜色
}
```

### 播放器方法

通过 ref 可以访问播放器实例的方法：

```tsx
// 播放控制
playerRef.current?.actions.play();
playerRef.current?.actions.pause();
playerRef.current?.actions.togglePlay();

// 跳转
playerRef.current?.actions.seek(30); // 跳转到30秒

// 音量控制
playerRef.current?.actions.setVolume(0.5);
playerRef.current?.actions.setMuted(true);

// 播放速度
playerRef.current?.actions.setPlaybackRate(1.5);

// 段落管理
playerRef.current?.actions.addSegment(segment);
// 段落管理 API
playerRef.current?.segments.add(segment);           // 添加段落
playerRef.current?.segments.remove(segmentId);      // 删除段落
playerRef.current?.segments.update(segmentId, updates); // 更新段落
playerRef.current?.segments.clear();                // 清空所有段落
playerRef.current?.segments.play(segment);          // 播放指定段落
playerRef.current?.segments.getCurrent();           // 获取当前段落
playerRef.current?.segments.getAll();               // 获取所有段落
```

## 演示功能

### 🎮 交互式演示
- **实时控制**: 主题切换、显示/隐藏控制组件
- **段落管理**: 添加随机段落、清空段落、导出数据
- **状态监控**: 实时显示播放器状态信息
- **段落预览**: 可视化段落列表，点击快速跳转

### 🎬 测试视频
- 使用本地视频文件 `/public/video/trailer.mp4`
- 支持多种视频格式 (MP4, WebM, OGG)
- 自动适配视频尺寸和比例

### ⌨️ 键盘快捷键
- **空格键**: 播放/暂停
- **上下箭头**: 音量调节
- **左右箭头**: 快进/快退 (5秒)
- **F键**: 全屏切换
- **M键**: 静音切换

## 开发

### 启动开发服务器

```bash
pnpm dev
```

### 构建

```bash
pnpm build
```

### 预览

```bash
pnpm preview
```

## 技术栈

- **React 18** - UI 框架
- **TypeScript** - 类型安全
- **Video.js 8.23.4** - 视频播放核心
- **Lucide React** - 图标库
- **CSS3** - 样式实现

## 许可证

MIT License