vue-liveplayer-wrapper/README.md

Vue 3 wrapper for @liveqing/liveplayer-v3 with recording and playback control features

# LivePlayer Wrapper

一个基于 Vue 3 的视频播放器包装组件，集成了 @liveqing/liveplayer-v3，提供视频播放、录制、播放控制等功能。

## 功能特性

- 🎥 支持多种视频格式（HLS、FLV、MP4等）
- 📹 视频录制功能（支持最长5分钟录制）
- 🎮 播放控制（播放/暂停、音量、全屏等）
- 🔄 播放开关功能（可关闭/恢复视频播放）
- 📸 截图功能
- 🎛️ 自定义工具栏按钮
- 📱 响应式设计
- 🎨 丰富的自定义选项

## 安装

```bash
npm install liveplayer-wrapper
```

## 使用方法

### 1. 全局注册

```javascript
import { createApp } from 'vue'
import LivePlayerWrapper from 'liveplayer-wrapper'
import 'liveplayer-wrapper/dist/style.css'

const app = createApp(App)
app.use(LivePlayerWrapper)
app.mount('#app')
```

### 2. 局部使用

```vue
<template>
  <div>
    <LivePlayerWrapper
      :video-url="videoUrl"
      :video-title="videoTitle"
      :autoplay="true"
      :controls="true"
      :live="true"
      @ready="onPlayerReady"
      @recordingStart="onRecordingStart"
      @recordingStop="onRecordingStop"
      @recordingError="onRecordingError"
    />
  </div>
</template>

<script setup>
import { LivePlayerWrapper } from 'liveplayer-wrapper'
import 'liveplayer-wrapper/dist/style.css'

const videoUrl = 'https://example.com/video.m3u8'
const videoTitle = '示例视频'

const onPlayerReady = (player) => {
  console.log('播放器已就绪', player)
}

const onRecordingStart = () => {
  console.log('录制开始')
}

const onRecordingStop = () => {
  console.log('录制结束')
}

const onRecordingError = (error) => {
  console.error('录制错误', error)
}
</script>
```

## Props 配置

### 视频相关属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| videoUrl | String | '' | 视频流地址 |
| videoTitle | String | '' | 视频右上角显示的标题 |
| poster | String | '' | 视频封面图片 |
| alt | String | '无信号' | 无视频时的替代文字 |

### 播放控制属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| autoplay | Boolean | true | 自动播放 |
| controls | Boolean | true | 显示控制栏 |
| loop | Boolean | false | 循环播放 |
| live | Boolean | true | 是否为直播流(隐藏进度条) |
| muted | Boolean | true | 静音 |

### 显示设置

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| aspect | String | '16:9' | 宽高比(fullscreen为全屏) |
| fluent | Boolean | true | 流畅模式 |
| stretch | Boolean | false | 是否拉伸 |
| hideBigPlayButton | Boolean | false | 隐藏大播放按钮 |
| waterMark | String | '' | 水印文字 |

### 按钮显示控制

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| showCustomButton | Boolean | true | 显示自定义按钮 |
| hideSnapshotButton | Boolean | false | 隐藏快照按钮 |
| hideFullscreenButton | Boolean | false | 隐藏全屏按钮 |
| hideFluent | Boolean | false | 隐藏流畅按钮 |
| hideStretch | Boolean | true | 隐藏拉伸按钮 |

### HLS相关设置

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| resolution | String | '' | 清晰度配置(yh,fhd,hd,sd) |
| resolutiondefault | String | 'hd' | 默认清晰度 |
| playbackRates | Array | [0.5, 1, 2, 3] | 倍速列表 |
| playbackRate | Number | 1 | 默认倍速 |

## Events 事件

| 事件名 | 参数 | 说明 |
|--------|------|------|
| ready | player | 播放器就绪 |
| message | {type, message} | m3u8加载失败 |
| error | Error | 播放器出错 |
| ended | - | 播放结束 |
| timeupdate | time | 进度更新 |
| pause | time | 暂停 |
| play | time | 播放 |
| fullscreen | isFullscreen | 全屏状态改变 |
| snapOutside | data | 外部快照 |
| snapInside | data | 内部快照 |
| customButtons | buttonName | 自定义按钮点击 |
| canplay | duration | 可播放 |
| volumechange | volume, muted | 音量改变 |
| recordingStart | - | 录制开始 |
| recordingStop | - | 录制停止 |
| recordingError | error | 录制错误 |

## 方法

通过 ref 可以调用以下方法：

### 播放控制
- `play()` - 播放
- `pause()` - 暂停
- `togglePlay()` - 切换播放/暂停
- `paused()` - 获取暂停状态

### 录制功能
- `startRecording()` - 开始录制
- `stopRecording()` - 停止录制
- `toggleRecording()` - 切换录制状态
- `isRecording()` - 获取录制状态
- `getRecordingTime()` - 获取录制时长
- `forceStopRecording()` - 强制停止录制

### 播放开关功能
- `togglePlayback()` - 切换播放开关
- `isPlaying()` - 获取播放开关状态

### 其他功能
- `snap()` - 截图
- `getCurrentTime()` - 获取当前时间
- `setCurrentTime(time)` - 设置当前时间
- `getVolume()` - 获取音量
- `setVolume(volume)` - 设置音量
- `toggleMute()` - 切换静音
- `toggleFullscreen()` - 切换全屏

## 示例

### 基本使用

```vue
<template>
  <div class="video-container">
    <LivePlayerWrapper
      ref="playerRef"
      :video-url="videoUrl"
      :video-title="'直播视频'"
      :autoplay="true"
      :controls="true"
      :live="true"
      @ready="onReady"
      @recordingStart="onRecordingStart"
      @recordingStop="onRecordingStop"
    />
    
    <div class="controls">
      <button @click="startRecording">开始录制</button>
      <button @click="stopRecording">停止录制</button>
      <button @click="togglePlayback">切换播放</button>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { LivePlayerWrapper } from 'liveplayer-wrapper'

const playerRef = ref()
const videoUrl = 'https://example.com/live.m3u8'

const onReady = (player) => {
  console.log('播放器就绪')
}

const startRecording = () => {
  playerRef.value?.startRecording()
}

const stopRecording = () => {
  playerRef.value?.stopRecording()
}

const togglePlayback = () => {
  playerRef.value?.togglePlayback()
}
</script>
```

### 高级配置

```vue
<template>
  <LivePlayerWrapper
    :video-url="videoUrl"
    :video-title="'高清直播'"
    :aspect="'16:9'"
    :fluent="true"
    :stretch="false"
    :timeout="30"
    :resolution="'fhd,hd,sd'"
    :resolutiondefault="'hd'"
    :playback-rates="[0.5, 1, 1.5, 2]"
    :custom-buttons="'录制:vjs-icon-record,开关:vjs-icon-switch'"
    :water-mark="'LivePlayer'"
    @message="handleMessage"
    @error="handleError"
  />
</template>
```

## 注意事项

1. **录制功能**：录制功能需要浏览器支持 MediaRecorder API
2. **视频格式**：支持 HLS、FLV、MP4 等主流格式
3. **跨域问题**：如果视频源有跨域限制，需要配置相应的 CORS 策略
4. **录制时长**：单次录制最长支持 5 分钟
5. **浏览器兼容性**：建议使用现代浏览器以获得最佳体验

## 开发

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建库
npm run build:lib

# 类型检查
npm run type-check
```

## 许可证

MIT License