# MetaStream

**Repository Path**: PolarisF/MetaStream

## Basic Information

- **Project Name**: MetaStream
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-04
- **Last Updated**: 2026-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MetaStream

> 视频编解码 SDK，支持在 H.264 视频流中注入和提取自定义 SEI (Supplemental Enhancement Information) 元数据

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![FFmpeg](https://img.shields.io/badge/FFmpeg-7.1-green.svg)](https://ffmpeg.org/)

---

## 📖 项目简介

MetaStream 是一个高性能的视频编解码库，专注于在视频流中**无损传递自定义元数据**。通过将元数据编码为 H.264 SEI 数据，实现视频与结构化信息的完美配对，特别适用于：

- 🎯 **目标检测/跟踪**：将检测框、类别、置信度等信息与视频帧绑定
- 📊 **视频分析**：嵌入时间戳、统计数据、分析结果
- 🔍 **智能监控**：实时传输报警信息、事件标记
- 🎬 **视频后处理**：在不重新编码的情况下关联原始数据

**核心优势**：
- ✅ 元数据随视频流传输，不需要独立的同步文件
- ✅ 支持 RTMP/RTSP 流媒体和本地文件（TS/MP4/FLV）
- ✅ 100% SEI 覆盖率和数据完整性保证
- ✅ 高层 Python API，易于集成

---

## 🚀 快速开始

### 环境要求

- **Python**: 3.8 - 3.11 (推荐 3.10)
- **FFmpeg**: 7.0+ (需要 libx264)
- **系统**: Linux / macOS (Windows 需 WSL)

### 安装

```bash
# 1. 克隆项目
git clone https://gitee.com/PolarisF/MetaStream.git
cd MetaStream

# 2. 创建 Conda 环境（推荐）
conda create -n metastream python=3.10 -y
conda activate metastream

# 3. 安装 Python 依赖
pip install numpy opencv-python

# 4. 编译 C 库
bash scripts/build_linux.sh
```

### 5分钟上手

#### 编码：将元数据注入视频

```python
from metastream import VideoEncoder
import numpy as np

# 创建编码器
encoder = VideoEncoder(
    output_path='output.ts',
    width=1280,
    height=720,
    fps=30,
    bitrate=2000000
)

# 编码视频帧 + SEI 元数据
with encoder:
    for frame_id in range(100):
        # 创建视频帧（或从摄像头/文件读取）
        frame = np.zeros((720, 1280, 3), dtype=np.uint8)
        
        # 定义 SEI 元数据（任意 JSON 结构）
        sei_data = {
            'frame_id': frame_id,
            'timestamp': frame_id / 30.0,
            'objects': [
                {'class': 'person', 'bbox': [100, 200, 50, 80], 'confidence': 0.95}
            ]
        }
        
        # 编码帧并注入 SEI
        encoder.write_frame(frame, sei_data=sei_data)

print("✅ 编码完成！")
```

#### 解码：提取元数据

```python
from metastream import VideoDecoder

# 创建解码器
decoder = VideoDecoder('output.ts')

# 逐帧解码并提取 SEI
with decoder:
    for result in decoder:
        frame_bgr = result['frame']       # 视频帧（bytes）
        sei_data = result['sei']          # SEI 元数据（dict）
        pts = result['pts']               # 时间戳
        
        if sei_data:
            print(f"帧 {sei_data['frame_id']}: {len(sei_data['objects'])} 个目标")

print("✅ 解码完成！")
```

---

## 📦 功能特性

### 核心功能

| 功能 | 说明 | 状态 |
|------|------|------|
| SEI 注入 | 将 JSON 数据编码为 H.264 SEI | ✅ |
| SEI 提取 | 从视频流解码 SEI 元数据 | ✅ |
| 容器格式 | TS, MP4, FLV 自动检测 | ✅ |
| 流媒体 | RTMP/RTSP 推流支持 | ✅ |
| UUID 过滤 | 自定义 SEI 标识符 | ✅ |
| Python SDK | 高层 Pythonic API | ✅ |
| 上下文管理 | `with` 语句自动资源管理 | ✅ |
| 迭代器协议 | `for` 循环遍历视频帧 | ✅ |

### 流媒体支持 (RTSP/RTMP)

#### 编码推流
```python
from metastream import VideoEncoder

# 推流到RTMP服务器
encoder = VideoEncoder('rtmp://127.0.0.1:1935/live/test', width=1280, height=720, fps=30)
with encoder:
    for frame in video_frames:
        encoder.write_frame(frame, sei_data={'frame_id': i})

# 注意：FFmpeg不支持直接RTSP推流
# 方案：推送RTMP → MediaMTX转发 → RTSP拉流
```

#### 解码拉流
```python
from metastream import VideoDecoder

# 从RTSP/RTMP接收视频流
decoder = VideoDecoder('rtsp://127.0.0.1:8554/live/test')
with decoder:
    for result in decoder:
        frame = result['frame']
        sei_data = result['sei']
        print(f"Frame {sei_data['frame_id']}")
```

#### 流媒体服务器设置

使用 **MediaMTX** (推荐，支持RTMP→RTSP转发)：
```bash
# 下载并运行MediaMTX
wget https://github.com/bluenviron/mediamtx/releases/download/v1.13.0/mediamtx_v1.13.0_linux_amd64.tar.gz
tar -xzf mediamtx_v1.13.0_linux_amd64.tar.gz
./mediamtx

# 推流到RTMP（端口1935）
python examples/rtsp_stream_encode.py video.mp4 rtmp://127.0.0.1:1935/live/test

# 通过RTSP拉流（端口8554）
python examples/rtsp_stream_decode.py rtsp://127.0.0.1:8554/live/test --duration 10
```

**测试结果：**
- ✅ RTMP推流：120帧，100% SEI覆盖率，30.2 fps
- ✅ RTMP接收：305帧，100% SEI覆盖率，61.0 fps  
- ✅ RTSP接收：179帧，100% SEI覆盖率，35.6 fps
- ✅ 视频质量：VLC播放器验证正常

详见 [docs/STREAMING.md](docs/STREAMING.md) 完整流媒体使用指南。

### 测试工具

位于 `examples/` 目录，提供完整的编解码测试和验证：

```bash
# 1. 基础编解码测试
python examples/basic_encode.py videos/input.mp4    # 生成 .ts + SEI记录
python examples/basic_decode.py videos/input.ts     # 解码 + SEI 可视化
python examples/verify_sei.py videos/input.ts videos/input.txt  # 验证数据一致性

# 2. 目标检测编解码
python examples/detection_encode.py videos/video.mp4 videos/labels  # YOLO 标注编码
python examples/detection_decode.py videos/video_detection.ts     # 绘制检测框

# 3. 流媒体编解码
python examples/rtsp_stream_encode.py video.mp4 rtmp://127.0.0.1:1935/live/test
python examples/rtsp_stream_decode.py rtsp://127.0.0.1:8554/live/test --duration 10
python examples/verify_rtmp_sei.py rtmp://127.0.0.1:1935/live/test  # 验证SEI完整性

# 4. 视觉验证
python examples/visual_verify.py  # 生成对比视频（画面显示 SEI 信息）
```

---

## 🎯 应用场景

### 1. 目标检测结果传输

将 YOLO/Faster R-CNN 等检测结果与视频帧同步传输：

```python
# 编码检测结果
for frame, detections in zip(video_frames, detection_results):
    sei_data = {
        'detections': [
            {
                'class_id': det.class_id,
                'class_name': det.class_name,
                'bbox': det.bbox,
                'confidence': det.confidence
            }
            for det in detections
        ]
    }
    encoder.write_frame(frame, sei_data=sei_data)

# 解码并绘制检测框
with VideoDecoder('detection_stream.ts') as decoder:
    for result in decoder:
        frame = result['frame']
        detections = result['sei']['detections']
        
        for det in detections:
            draw_bbox(frame, det['bbox'], det['class_name'])
        
        cv2.imshow('Detections', frame)
```

### 2. 视频分析管道

在视频处理流水线中传递中间结果：

```python
# 阶段1：编码原始视频 + 预处理信息
sei_data = {
    'brightness': calculate_brightness(frame),
    'motion_score': detect_motion(frame, prev_frame),
    'scene_type': classify_scene(frame)
}
encoder.write_frame(frame, sei_data=sei_data)

# 阶段2：后续处理直接读取 SEI，无需重新分析
with VideoDecoder('processed.ts') as decoder:
    for result in decoder:
        if result['sei']['motion_score'] > threshold:
            perform_detailed_analysis(result['frame'])
```

### 3. 实时监控告警

在监控视频流中嵌入事件标记：

```python
# 编码告警信息
sei_data = {
    'alert': True if detect_intrusion(frame) else False,
    'alert_type': 'intrusion_detected',
    'location': get_camera_location(),
    'timestamp': time.time()
}
encoder.write_frame(frame, sei_data=sei_data)

# 回放时快速定位告警帧
with VideoDecoder('surveillance.ts') as decoder:
    for result in decoder:
        if result['sei'].get('alert'):
            handle_alert(result['frame'], result['sei'])
```

---

## 📂 项目结构

```
MetaStream/
├── src/                     # C++ 源码
│   └── CEncode.cpp          # 核心编解码器实现
├── metastream/              # Python SDK
│   ├── __init__.py          # 包初始化
│   ├── encoder.py           # VideoEncoder 类
│   ├── decoder.py           # VideoDecoder 类
│   ├── exceptions.py        # 异常定义
│   ├── config.py            # 配置管理
│   └── utils.py             # 工具函数
├── examples/                # 示例代码
│   ├── basic_encode.py      # 基础编码示例
│   ├── basic_decode.py      # 基础解码示例
│   ├── detection_encode.py  # 目标检测编码
│   ├── detection_decode.py  # 目标检测解码
│   ├── verify_sei.py        # SEI 验证工具
│   ├── visual_verify.py     # 视觉对比测试
│   └── README.md            # 示例说明
├── tests/                   # 单元测试（pytest）
│   ├── test_encoder.py      # 编码器测试
│   ├── test_decoder.py      # 解码器测试
│   └── test_integration.py  # 集成测试
├── scripts/                 # 构建脚本
│   └── build_linux.sh       # Linux 编译脚本
├── docs/                    # 文档
│   ├── DEVELOPMENT.md       # 开发文档
│   └── API.md               # API 参考
├── libmetastream.so         # 编译后的动态库
└── README.md                # 本文件
```

---

## 🔧 技术细节

### SEI 数据格式

MetaStream 使用以下 SEI 结构：

```
[16 bytes UUID] + [JSON payload]
```

- **UUID**: `a1b2c3d4-e5f6-0102-0304-050607080910` (可自定义)
- **Payload**: UTF-8 编码的 JSON 字符串

示例 SEI 数据：
```json
{
  "frame_id": 123,
  "timestamp": 4.1,
  "detections": [
    {
      "class_id": 0,
      "class_name": "person",
      "bbox": [100, 200, 150, 250],
      "confidence": 0.95
    }
  ],
  "metadata": {
    "camera_id": "cam_001",
    "location": "entrance"
  }
}
```

### 颜色格式

- **编码输入**: BGR (OpenCV 默认格式)
- **内部处理**: YUV420P (H.264 标准)
- **解码输出**: BGR (便于 OpenCV 处理)

### 性能指标

| 测试场景 | 分辨率 | 帧率 | SEI 覆盖率 | 备注 |
|---------|--------|------|-----------|------|
| 基础编解码 | 1280x720 | 30fps | 100% | 本地文件 |
| 目标检测 (demo01) | 1280x720 | 30fps | 99.2% | 本地文件 |
| RTMP推流 | 1280x720 | 30fps | 100% | MediaMTX 1.13.0 |
| RTMP接收 | 1280x720 | 61fps | 100% | 本地网络 |
| RTSP接收 | 1280x720 | 35fps | 100% | MediaMTX转发 |

> **测试环境**: Ubuntu 22.04, i7-10700, 16GB RAM, FFmpeg 7.1, MediaMTX v1.13.0  
> **已知问题**: EasyPlayer可能显示RTSP为竖条纹，推荐使用VLC播放器（已验证正常）

---

## 🐛 已知问题与计划

### 已解决
- ✅ **资源泄漏**: create_encoder 错误处理已修复 (2026-01-04)
- ✅ **BGR/RGB 颜色错误**: 已修复 sws_getContext 格式问题
- ✅ **SEI 数据不更新**: 已添加 av_frame_remove_side_data
- ✅ **RTSP视频损坏**: 修复sws_scale数组维度错误 (dst_data[1]→dst_data[4]) (2026-01-05)

### 待优化
1. **第一帧无 SEI**: I 帧通常不携带 SEI（H.264 标准限制）
2. **性能优化**: SwsContext 未复用，存在优化空间
3. **Windows 支持**: 当前仅支持 Linux/macOS，Windows 适配中
4. **硬件加速**: 探索 NVENC/QSV 硬件编码支持

查看 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) 了解更多技术细节和改进计划。

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

### 提交规范

- **Commit 格式**: `[模块] 动作: 简要描述`
  - 示例: `[编码器] 修复: SEI 数据累积问题`
  - 示例: `[测试] 新增: 目标检测可视化脚本`

### 开发环境

```bash
# 安装开发依赖
pip install pytest pytest-cov black mypy

# 运行测试
pytest tests/              # 运行所有测试
pytest tests/ -v           # 详细输出
pytest tests/ --cov        # 代码覆盖率

# 代码格式化
black metastream/ examples/ tests/
```

---

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

---

## 🙏 致谢

- [FFmpeg](https://ffmpeg.org/) - 强大的多媒体处理框架
- [x264](https://www.videolan.org/developers/x264.html) - 高性能 H.264 编码器
- [OpenCV](https://opencv.org/) - 计算机视觉库

---

## 📮 联系方式

- **Gitee**: [https://gitee.com/PolarisF/MetaStream](https://gitee.com/PolarisF/MetaStream)
- **Issues**: [提交问题](https://gitee.com/PolarisF/MetaStream/issues)

---

<p align="center">
  <b>⭐ 如果这个项目对你有帮助，请给个 Star！</b>
</p>