# Mage-VL Proactive Streaming Commentary Demo

基于 Microsoft [Mage-VL](https://huggingface.co/microsoft/Mage-VL) 的 **Proactive Streaming Alignment**（主动流式对齐）功能：一边播放视频，一边由 StreamMind Gate（System 1）决策何时触发 Qwen3-4B 生成解说（System 2）。

论文：[arXiv:2607.24904](https://arxiv.org/pdf/2607.24904)

---

## 架构

```
视频流 → Mage-ViT (Codec-Native 16×16 patch 编码)
            │
            ├──→ StreamMind Gate (System 1, Mamba-SSM)
            │         │
            │         └──→ p(speak) 每段概率
            │                   │
            │              若 p ≥ threshold → 触发 System 2
            │
            └──→ Qwen3-4B Decoder (System 2) → 生成解说文本
```

---

## 本地运行

```bash
conda activate py311
pip install torch torchvision transformers accelerate \
            decord opencv-python-headless moviepy Pillow scipy safetensors
pip install mamba-ssm   # StreamMind gate 需要 CUDA 编译

python streaming_commentary.py \
  --video /path/to/video.mp4 \
  --checkpoint microsoft/Mage-VL \
  --backend codec \
  --segment-sec 8 \
  --threshold 0.5 \
  --gpu
```

---

## Google Colab 运行

**可以运行。** 完整 notebook 见 `colab_setup.ipynb`，步骤如下：

1. 打开 [Google Colab](https://colab.research.google.com)，新建 Notebook
2. 将本项目三个文件上传到 `/content/`（或复制粘贴代码单元格）
3. 按顺序运行：
   - **Cell 1**：确认 GPU（Runtime → Change runtime type → GPU）
   - **Cell 2**：`pip install` 依赖（mamba-ssm 需编译，约 2-3 分钟）
   - **Cell 3**：上传视频（`files.upload()`）
   - **Cell 4**：运行 `streaming_commentary.py`

Colab 免费额度提供 T4 GPU（16GB VRAM），足以运行 `microsoft/Mage-VL`（bf16 约 8GB）。

> 注意：Colab 无 GUI，输出为纯文本（不依赖 `cv2.imshow`）。

---

## 参数

| 参数 | 默认 | 说明 |
|---|---|---|
| `--video` | (必填) | 视频路径 |
| `--checkpoint` | `microsoft/Mage-VL` | HF 模型 ID 或本地路径 |
| `--backend` | `codec` | `codec`=Codec-Native；`frames`=均匀帧采样 |
| `--segment-sec` | `8.0` | 每段长度（秒）|
| `--threshold` | `0.5` | Gate 触发阈值 |
| `--max-tokens` | `120` | 每次生成最大 token 数 |
| `--gpu` | 关 | 启用 CUDA（推荐）|

---

## 无 mamba-ssm 时的行为

若未安装 `mamba-ssm`，Gate 不可用，程序自动降级为**非门控模式**：每个视频片段都触发生成解说。逻辑流程不变。