npm package: @linker-design-plus/mpegtsplayer
Description: A player base on mpegts.js
Author: Linker Design Team
Latest version: 1.0.5

# @linker-design-plus/mpegtsplayer

一个基于 mpegts.js 的 Vue 3 视频播放器组件，用于播放 FLV 流媒体，具有增强的功能和控件。

## 功能特性

- 🎥 **FLV 流媒体支持**：使用 mpegts.js 播放 FLV 视频流
- 🔄 **自动重载**：连接丢失时自动重新加载视频流
- 👁️ **可见性处理**：处理标签页可见性变化并自动刷新
- ⚙️ **自定义控件**：切换原生视频控件的显示/隐藏
- 📡 **直播流优化**：针对直播流进行了低延迟优化
- 🎯 **错误处理**：全面的错误处理和事件报告
- 📱 **响应式设计**：适应容器尺寸变化
- 🎨 **样式化组件**：内置加载指示器和简洁的界面

## 安装

```bash
# 推荐使用 pnpm
pnpm add @linker-design-plus/mpegtsplayer

# 使用 npm
npm install @linker-design-plus/mpegtsplayer

# 使用 yarn
yarn add @linker-design-plus/mpegtsplayer
```

## 使用方法

### 引入组件

```js
// 在 main.js 或入口文件中
import { createApp } from 'vue';
import MpegtsPlayer from '@linker-design-plus/mpegtsplayer';
import '@linker-design-plus/mpegtsplayer/dist/style.css';

const app = createApp(App);
app.component('MpegtsPlayer', MpegtsPlayer);
```

或者在组件中局部使用：

```vue
<script setup>
import MpegtsPlayer from '@linker-design-plus/mpegtsplayer';
import '@linker-design-plus/mpegtsplayer/dist/style.css';
</script>
```

### 基础用法

```vue
<template>
  <div style="width: 800px; height: 450px;">
    <MpegtsPlayer 
      video-url="http://example.com/stream.flv"
    />
  </div>
</div>
```

### 直播流配置

```vue
<template>
  <div style="width: 100%; height: 100%;">
    <MpegtsPlayer 
      video-url="http://example.com/live-stream.flv"
      :is-live="true"
      :auto-reload="true"
      :auto-visibility-change-refresh="true"
      :close-visibility-change-listener="false"
    />
  </div>
</div>
```

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| videoUrl | 视频流 URL | string | "" |
| closeVisibilityChangeListener | 关闭可见性变化监听器 | boolean | false |
| autoVisibilityChangeRefresh | 可见性变化时自动刷新 | boolean | false |
| autoReload | 错误时自动重载 | boolean | false |
| isLive | 是否为直播流 | boolean | true |
| controls | 显示原生控件 | boolean | false |
| stallTimeout | 卡顿检测超时时间（毫秒） | number | 5000 |

### Events

| 事件 | 说明 | 回调参数 |
|------|------|----------|
| loadError | 加载错误 | errorInfo: any |
| playSuccess | 播放成功 | - |
| loadComplete | 加载完成(针对直播流) | - |
| visibilitychange | 可见性变化 | visibilityState: string |
| timeupdate | 时间更新 | time(s): number |
| playEnded | 播放结束（针对回放流） | - |
| playLoading | 播放加载中(如果视频卡顿了，会触发这个事件) | - |

### 方法 (通过 ref 暴露)
目前start()和pause()是无效的，不能直接控制流的播放或者暂停

| 方法 | 说明 | 参数 |
|------|------|------|
| start() | 开始播放 | - |
| pause() | 暂停播放 | - |
| destroy() | 销毁播放器 | - |
| reload() | 重新加载播放器 | - |

### 访问方法示例

```vue
<template>
  <div>
    <MpegtsPlayer 
      ref="playerRef"
      video-url="http://example.com/stream.flv"
      :is-live="true"
    />
    <button @click="reload">重新加载</button>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import MpegtsPlayer from '@linker-design-plus/mpegtsplayer';
import '@linker-design-plus/mpegtsplayer/dist/style.css';

const playerRef = ref(null);

const reload = () => {
  playerRef.value.reload();
};
</script>
```

## 功能描述

### 自动重连
当启用 `autoReload` 时，如果连接丢失，播放器将自动尝试重新连接到流媒体，最多尝试 2 次后发出错误事件。

### 可见性处理
当浏览器标签页在隐藏后重新可见时，播放器可以自动重新加载，由 `autoVisibilityChangeRefresh` 属性控制。

### 控件自定义
可以使用 `controls` 属性切换原生视频控件的显示/隐藏。

### 直播流优化
针对直播流的优化设置包括：
- 禁用 stash 缓冲区以降低延迟
- 禁用懒加载以实现连续流媒体播放
- 启用实时缓冲区延迟追踪以实现流畅播放


## 依赖

- Vue 3.1.0+
- mpegts.js 1.7.3
- @arco-design/web-vue 2.56.3

## 浏览器兼容性

- 支持 ES2015+ 的现代浏览器
- FLV 播放需要支持媒体源扩展 (MSE)

## 注意事项

1. 生产环境中，请确保您的视频流 URL 支持 CORS
2. 播放器针对 FLV 流进行了优化；其他格式可能无法正常工作
3. 对于直播流，默认启用了延迟优化
4. 通过适当的销毁生命周期自动管理内存

## 许可证

MIT