@veepai/video-player

基于 Vue 3 + XGPlayer 的 HLS 视频回放播放器组件，支持时间轴、精灵图预览、多片段播放。

✨ 特性

• 🎬 HLS 流媒体播放 - 支持 m3u8 格式视频
• 📊 自定义时间轴 - Canvas 绘制，性能优秀
• 🖼️ 精灵图预览 - 鼠标悬浮显示视频缩略图
• 🔄 多片段播放 - 自动切换多个视频片段
• 📱 移动端适配 - 支持触摸手势
• 🔌 API 适配器 - 灵活的接口适配机制
• 📦 TypeScript - 完整的类型定义

📦 安装

npm install @veepai/video-player
# or
pnpm add @veepai/video-player
# or
yarn add @veepai/video-player

🚀 快速开始

1. 基础使用

<template>
  <VeepaiVideoPlayer :config="playerConfig" :api-adapter="apiAdapter" />
</template>

<script setup lang="ts">
import { VeepaiVideoPlayer } from '@veepai/video-player'
import '@veepai/video-player/style.css'
import type { PlayerConfig, ApiAdapter } from '@veepai/video-player'

// 配置播放器
const playerConfig: PlayerConfig = {
  deviceId: 'device123',
  userId: 'user456',
  timeRange: ['2025-01-01 08:00:00', '2025-01-01 18:00:00'],
  playerHeight: '400px',
  playbackRate: [0.5, 1, 1.5, 2, 4, 8],
  defaultPlaybackRate: 1,
}

// 实现 API 适配器
const apiAdapter: ApiAdapter = {
  async getReplayData(params) {
    const response = await fetch('/api/replay/rows', {
      method: 'GET',
      params,
    })
    return response.json()
  },

  async getM3u8File(params) {
    const response = await fetch('/api/replay/m3u8file', {
      method: 'GET',
      params,
    })
    return response.text()
  },

  async getSprite(params) {
    const response = await fetch('/api/replay/sprite', {
      method: 'GET',
      params,
    })
    return response.json()
  },
}
</script>

2. 使用 Axios

import axios from 'axios'
import type { ApiAdapter } from '@veepai/video-player'

const apiAdapter: ApiAdapter = {
  async getReplayData(params) {
    const { data } = await axios.get('/api/replay/rows', { params })
    return data
  },

  async getM3u8File(params) {
    const { data } = await axios.get('/api/replay/m3u8file', {
      params,
      responseType: 'text',
    })
    return data
  },

  async getSprite(params) {
    const { data } = await axios.get('/api/replay/sprite', { params })
    return data
  },
}

📚 API 文档

PlayerConfig

播放器配置对象

| 属性 | 类型 | 必填 | 默认值 | 说明 | | --------------------- | ------------------ | ---- | ------------------------ | ------------------ | | deviceId | string | 是 | - | 设备 ID | | userId | string | 是 | - | 用户 ID | | timeRange | [string, string] | 否 | 最近 1 小时 | 时间范围 | | playerHeight | string\|number | 否 | '400px' | 播放器高度 | | timelineHeight | number | 否 | 44 | 时间轴高度（像素） | | playbackRate | number[] | 否 | [0.5, 1, 1.5, 2, 4, 8] | 播放速率选项 | | defaultPlaybackRate | number | 否 | 1 | 默认播放速率 | | timelineColors | TimelineColors | 否 | 见下方 | 时间轴颜色配置 |

TimelineColors

时间轴颜色配置

interface TimelineColors {
  background?: string // 背景色，默认 '#2D2D2D'
  meddleLine?: string // 中心指针颜色，默认 '#FFFFFF'
  scaleLine?: string // 大刻度线颜色，默认 '#5A5A5A'
  smallScaleLine?: string // 小刻度线颜色，默认 '#404040'
  scaleText?: string // 刻度文字颜色，默认 '#CCCCCC'
  scaleBar?: string // 刻度背景色，默认 '#1E1E1E'
}

ApiAdapter

API 适配器接口，用于对接后端接口

interface ApiAdapter {
  // 获取回放数据列表
  getReplayData(params: ReplayDataParams): Promise<ReplayItem[]>

  // 获取 m3u8 文件内容
  getM3u8File(params: M3u8FileParams): Promise<string>

  // 获取精灵图数据
  getSprite(params: SpriteParams): Promise<SpriteData>
}

1. getReplayData 参数

interface ReplayDataParams {
  deviceid: string
  userid: string
  begin: number // 开始时间戳（毫秒）
  end: number // 结束时间戳（毫秒）
  channel: number
  provider?: string
  bucket?: string
}

返回数据格式：

interface ReplayItem {
  duration: number // 持续时间（秒）
  startTime: number // 开始时间戳（毫秒）
  endTime: number // 结束时间戳（毫秒）
  key: string // m3u8 文件名
}

2. getM3u8File 参数

interface M3u8FileParams {
  deviceid: string
  userid: string
  begin: number
  end: number
  channel: number
  provider?: string
  bucket?: string
  name: string // m3u8 文件名
}

返回：m3u8 文件内容（纯文本）

3. getSprite 参数

interface SpriteParams {
  deviceid: string
  userid: string
  begin: number // 回放片段开始时间戳
  end: number // 回放片段结束时间戳
  channel: number
}

返回数据格式：

interface SpriteData {
  data: string // base64 编码的图片数据
  meta: {
    webp_width: number // 大图总宽度
    webp_height: number // 大图总高度
    sprite_width: number // 每帧宽度
    sprite_height: number // 每帧高度
    total: number // 总帧数
  }
}

🎨 样式定制

组件使用 CSS 变量，可以轻松定制样式：

/* 自定义播放器容器样式 */
.veepai-player-container {
  --player-bg-color: #464c59;
}

/* 自定义时间轴样式 */
.veepai-timeline-controls {
  --timeline-controls-bg: #424243;
  --timeline-btn-color: #ffffff;
}

📱 移动端适配

组件已内置移动端适配：

• 📱 触摸拖动时间轴
• 🔍 双指缩放时间轴
• 📏 响应式按钮和文字大小
• 🖼️ 自适应精灵图尺寸

🔧 开发

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建库
pnpm build

# 构建演示
pnpm build:demo

📄 License

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📧 联系

如有问题，请联系 [email protected]