video-stream-snap/README.md

Capture the first frame from video streams (HLS/RTMP/FLV)

# video-stream-snap

一个轻量级的视频流截图工具，支持从HLS、RTMP和FLV流中快速捕获第一帧画面。

## 特性

- 🚀 支持多种流媒体格式：HLS、RTMP、FLV
- 🎯 自动检测流类型并使用对应解码器
- ⚡️ 异步操作，支持超时控制
- 🎨 可配置输出图片格式和质量
- 🖼 支持黑帧检测
- 📦 支持TypeScript
- 🔧 可自定义视频元素

## 安装

```bash
# 使用 npm
npm install video-stream-snap

# 使用 yarn
yarn add video-stream-snap

# 使用 pnpm
pnpm add video-stream-snap

# 使用 bun
bun add video-stream-snap
```

## 使用方法

```typescript
import StreamSnap from 'video-stream-snap';

// 基本用法
try {
  const imageDataUrl = await StreamSnap.capture('https://example.com/stream.m3u8');
  console.log('截图成功:', imageDataUrl);
} catch (error) {
  console.error('截图失败:', error);
}

// 使用配置选项
const options = {
  timeout: 10000,        // 超时时间(毫秒)
  quality: 0.9,          // 输出图片质量(0-1)
  mimeType: 'image/png', // 输出图片格式
  skipBlackFrame: true   // 跳过黑帧检测
};

const imageDataUrl = await StreamSnap.capture('rtmp://example.com/live', options);
```

## API文档

### StreamSnap.capture(streamUrl, options?)

捕获视频流的第一帧画面。

#### 参数

- `streamUrl` (string): 视频流地址
- `options` (StreamSnapOptions): 可选配置项

#### StreamSnapOptions

```typescript
interface StreamSnapOptions {
  /** 超时时间(毫秒)，默认5000 */
  timeout?: number;
  
  /** 输出图片质量(0-1)，默认0.8 */
  quality?: number;
  
  /** 输出图片类型，默认'image/jpeg' */
  mimeType?: 'image/jpeg' | 'image/png' | 'image/webp';
  
  /** 跳过黑帧检测，默认false */
  skipBlackFrame?: boolean;
  
  /** 自定义视频元素 */
  videoElement?: HTMLVideoElement;
}
```

#### 返回值

返回一个Promise，解析为base64编码的图片数据URL。

## 开发指南

### 环境要求

- Node.js >= 16
- Bun >= 1.1.38

### 开发流程

1. 安装依赖
```bash
bun install
```

2. 开发模式
```bash
bun run dev
```

3. 构建
```bash
bun run build
```

## 测试

项目使用Vitest进行测试。

```bash
# 运行测试
bun test

# 查看测试覆盖率
bun run coverage

# 使用UI界面运行测试
bun run test:ui
```

## 许可证

[MIT](LICENSE) © zhangjingjing207