Skip to content
BranchesTags

Repository files navigation

🐦 Starling（椋鸟）— AI 同声传译助手

粘贴 B 站英文视频链接，AI 自动生成双语字幕卡片。

🎬 演示视频：demo介绍.mp4

📥 百度网盘下载：Starling.mp4（提取码: uug7）

Python 3.12+ Node.js 22+ React 19 FastAPI

项目简介

Starling（椋鸟）是一款 AI 同声传译 Web 应用。粘贴一个 B 站英文视频链接，系统自动解析播放地址、提取音频、实时语音识别、流式翻译，并以卡片流的形式逐张蹦出双语字幕。

核心链路（6 段全自动）：

🔗 解析 → ⬇️ 下载 → 🎙️ ASR → 🌐 翻译 → 🪄 纠错 → 🃏 字幕

快速开始

环境要求

依赖 版本 说明
Python 3.12+ 后端运行环境
Node.js 22+ 前端构建与开发
ffmpeg 系统包 音频流提取（必需）

1. 配置 API Key

cp backend/.env.example backend/.env

编辑 backend/.env，填入 API Key：

# 必填：DeepSeek API Key（翻译 + 纠错）
DEEPSEEK_API_KEY=sk-your-deepseek-key

# 必填：阿里云 DashScope API Key（语音识别）
DASHSCOPE_API_KEY=sk-your-dashscope-key

2. 安装依赖

# 后端
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 前端
cd ../frontend
npm install

3. 一键启动

bash start.sh

前端 → http://localhost:5173 后端管理面板 → http://localhost:8000/admin

使用方式

  1. 在底部输入框粘贴 B 站英文视频链接，点击 载入
  2. 视频加载后点击 ▶ 开始
  3. 后端自动：解析 → 拉音频流 → 实时 ASR → 流式翻译 → 纠错
  4. 字幕卡片一张张蹦到右侧面板，英文灰色 + 中文白色
  5. 前 2 张卡片就绪后视频自动起播
  6. 播放过程中当前卡片高亮（青色边框 + 发光），字幕自动滚动跟随
  7. 纠错发生时卡片显示 ✏️ 徽章，悬停查看修正原因
  8. 随时点击 ⏹ 停止 中止链路

功能特性

视频链接解析

  • 通过 B 站公开 API 解析 BV 号，获取 CDN 直链
  • 后端代理视频流，附带 Referer 头绕过 CDN 校验
  • 前端 <video> 标签直接播放，无需下载视频文件

实时语音识别（ASR）

  • 后端用 ffmpeg 从视频流提取 PCM 16kHz 单声道音频
  • 通过 WebSocket 推送到阿里云 DashScope Qwen-ASR-Realtime
  • 服务端 VAD 自动断句，实时返回识别结果

流式上下文翻译

  • 每完成一句英文识别后，调用 DeepSeek 流式翻译
  • 携带前 5 句原文+译文作为上下文，保证前后连贯
  • 前端逐字渲染，打字机效果
  • 译文过长时自动触发二次精修

LLM 纠错

  • 当积累 ≥2 句字幕时，异步触发 DeepSeek 纠错检查
  • 检查：同音词、误识别术语、VAD 导致的缺词/重复、语义漂移
  • 仅修正真实的 ASR 错误，不做风格改写
  • 纠错结果通过 WebSocket 推送，前端显示 ✏️ 徽章

双语字幕卡片流

  • 每句英文+中文组成一张独立卡片
  • 卡片从右侧滑入+淡入（framer-motion 动画）
  • 当前播放句：青色边框 + 发光阴影 + 字号放大
  • 草稿句：灰色文字；定稿句：白色实色
  • 随视频进度自动滚动，支持手动翻阅

梦参三章

  • 基于字幕内容，用 LLM 提炼「道·法·术」三层参悟
  • 道 — 视频传递的核心规律
  • 法 — 可复用的思维框架
  • 术 — 即学即用的操作技巧
  • 在底部控制栏点击 🌙 梦参三章 打开

管理面板

  • 内嵌玻璃风格 Admin 控制台（/admin）
  • 实时展示：API 状态、活跃会话数、ASR/DeepSeek/ffmpeg 配置状态
  • 6 段管道可视化流程
  • API 调试入口

技术架构

┌──────────────────────────────────────────────────────────┐
│                 Frontend (React 19 + Vite)                │
│                                                          │
│  LinkInput ──→ VideoPlayer ──→ SubtitleView (card flow)  │
│  DreamChapterModal        useSubtitlePipeline (WS hook)  │
└──────────────────────────┬───────────────────────────────┘
                           │ WebSocket
┌──────────────────────────▼───────────────────────────────┐
│               Backend (Python FastAPI)                    │
│                                                          │
│  WebSocket Handler ──→ subtitle_pipeline                 │
│                     ├── ffmpeg PCM 音频流                  │
│                     ├── DashScope ASR (realtime)          │
│                     ├── DeepSeek 流式翻译                   │
│                     └── DeepSeek 异步纠错                   │
│                                                          │
│  REST API ──→ /api/video/resolve (B 站)                   │
│           ──→ /api/video/proxy  (CDN 代理)                │
│           ──→ /api/dream-chapter (梦参三章)                │
└──────────────────────────────────────────────────────────┘

数据流

B 站链接
  → B 站公开 API 解析直链
    → ffmpeg 拉流 → PCM 16kHz/mono
      → DashScope ASR WebSocket（实时识别）
        → DeepSeek 流式翻译（携带上下文）
          → 卡片推送（250ms 节流）
            → SubtitleView 渲染
        → DeepSeek 异步纠错（≥2 句时触发）

技术栈

层级 技术 用途
前端框架 React 19 + TypeScript UI 组件化
构建工具 Vite 8 开发与打包
CSS Tailwind CSS 4 样式系统
动画 Framer Motion 12 卡片入场动画
字体 Noto Serif SC / 宋体 衬线中文排版
后端框架 FastAPI HTTP + WebSocket
ASGI Uvicorn 异步服务器
语音识别 DashScope Qwen-ASR-Realtime 实时英文 ASR
翻译 + 纠错 DeepSeek API (deepseek-chat) 上下文流式翻译 + 异步纠错
视频解析 B 站公开 API 提取 CDN 直链
音频处理 ffmpeg 视频流 → PCM 16kHz
实时通信 WebSocket 双向低延迟消息

WebSocket 协议

前端 → 后端：

消息类型 说明
start_link_pipeline 启动管道：传入视频 URL + 标题
stop_link_pipeline 停止管道：取消所有任务，重置会话

后端 → 前端：

消息类型 说明
session_started 会话已创建，附带 session_id
pipeline_status 管道阶段：resolving → downloading → transcribing → translating → done
asr_result ASR 识别结果（is_final=true，含 start_time/end_time）
translation_start 翻译开始，附带 sentence_id
translation_chunk 翻译流式文本片段
translation_end 翻译完成，附带完整译文
correction 纠错结果（original_text / corrected_text / reason）
error 错误通知（code + message）

REST API

方法 路径 说明
GET /health 健康检查
GET /admin 管理控制台
POST /api/video/resolve?url=... 解析 B 站视频直链
GET /api/video/proxy?url=... 代理视频流（绕过 Referer 校验）
POST /api/dream-chapter 梦参三章生成
WS /ws 字幕实时通道

项目结构

Starling/
├── frontend/                    # React 前端
│   ├── src/
│   │   ├── components/
│   │   │   ├── VideoPlayer.tsx           # 视频播放器
│   │   │   ├── SubtitleView.tsx          # 双语字幕卡片流
│   │   │   ├── ControlBar.tsx            # 播放控制栏（已内联到 App）
│   │   │   ├── DreamChapterModal.tsx     # 梦参三章弹窗
│   │   │   ├── LinkInput.tsx             # 视频链接解析（fetchVideo）
│   │   │   ├── SessionHistory.tsx        # 历史会话
│   │   │   ├── WaveformVisualizer.tsx    # 波形动画
│   │   │   └── ErrorBanner.tsx           # 错误横幅
│   │   ├── hooks/
│   │   │   ├── useWebSocket.ts           # WebSocket 连接管理
│   │   │   └── useSubtitlePipeline.ts    # 管道状态管理
│   │   ├── types/index.ts               # TypeScript 类型
│   │   ├── App.tsx                       # 主应用
│   │   ├── main.tsx                      # 入口
│   │   └── index.css                     # 全局样式（衬线字体）
│   └── package.json
├── backend/                     # FastAPI 后端
│   ├── app/
│   │   ├── main.py                       # 应用入口 + /admin
│   │   ├── config.py                     # 环境变量配置
│   │   ├── api/
│   │   │   ├── video.py                  # 视频解析与代理
│   │   │   └── dream_chapter.py          # 梦参三章 API
│   │   ├── models/schemas.py             # Pydantic 数据模型
│   │   ├── websocket/
│   │   │   ├── handler.py                # WebSocket 路由与会话管理
│   │   │   └── protocol.py              # 消息类型定义
│   │   └── services/
│   │       ├── subtitle_pipeline.py      # 核心管道编排器
│   │       ├── video_downloader.py       # B 站 API 直链解析
│   │       ├── translator.py             # DeepSeek 流式翻译
│   │       ├── corrector.py              # DeepSeek 异步纠错
│   │       ├── dream_chapter.py          # 梦参三章生成
│   │       └── asr/
│   │           ├── provider.py           # ASR Provider 抽象
│   │           ├── alibaba_provider.py   # DashScope Realtime 实现
│   │           └── service.py            # ASR 服务路由
│   ├── requirements.txt
│   └── .env.example
├── docs/                         # 设计文档（BMAD）
│   ├── 00-handoff.md
│   ├── 01-analysis-report.md
│   ├── 02-prd.md
│   ├── 03-architecture.md
│   ├── 04-task-list.md
│   ├── 05-dev-log.md
│   └── 06-demo-script.md
├── scripts/
│   ├── init-claude.sh
│   └── init-codex.sh
├── Dockerfile
├── start.sh
└── README.md

配置参考

变量 必填 默认值 说明
DEEPSEEK_API_KEY ✅ — DeepSeek API Key
DEEPSEEK_BASE_URL — https://api.deepseek.com DeepSeek API 地址
DASHSCOPE_API_KEY ✅ — 阿里云百炼 API Key
DASHSCOPE_ASR_MODEL — qwen3-asr-flash-realtime 实时 ASR 模型
DASHSCOPE_FILE_ASR_MODEL — paraformer-v2 文件转写模型（备选）
CORRECTION_MODEL — deepseek-chat 纠错 LLM 模型
FRONTEND_URL — http://localhost:5173 前端地址（CORS）
BACKEND_URL — http://localhost:8000 后端地址

Docker 部署

docker build -t starling:latest .
docker run -d \
  -p 5173:5173 -p 8000:8000 \
  -v $(pwd):/workspace \
  -e DEEPSEEK_API_KEY=sk-xxx \
  -e DASHSCOPE_API_KEY=sk-xxx \
  starling:latest
bash /workspace/start.sh

镜像内置：Node.js 22 + Python 3 + ffmpeg + code-server + Claude Code CLI。

开源协议

MIT License. 详见 LICENSE。

致谢

本项目使用 BMAD（Breakthrough Method for Agile AI-Driven Development）方法论，由 AI 编码代理驱动全流程开发。详细设计文档见 docs/ 目录。

🐦 Starling 椋鸟 — 让语言不再成为获取知识的障碍

About

奉一纸云笺，便引夷语归中土。 对影成双行，笔误自消如雪融。 更得梦参三章，附卷闲藏。

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages