Files
speaking-practice/docs/superpowers/specs/2026-06-02-speaking-lab-deepseek-subtitle-ai-design.md
T
2026-06-03 00:34:42 +08:00

4.2 KiB

Speaking Lab DeepSeek Subtitle AI Design

Goal

Add an admin-side AI subtitle workflow that can clean downloaded English subtitle files and generate aligned Chinese translations after a material has been uploaded. The first version uses DeepSeek for text processing and translation, while keeping true audio-based timestamp calibration behind a future ASR provider boundary.

User Experience

The admin page shows an AI 修复并翻译字幕 action for an existing material that has English subtitles. If DeepSeek is not configured, the action remains visible but reports a clear setup message instead of failing silently.

The setup path is intentionally simple for a beginner:

DEEPSEEK_API_KEY=your_key_here
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

After the local server restarts, the admin can click 测试 AI 连接. If the connection works, AI 修复并翻译字幕 becomes usable.

First Version Scope

The first version does these things:

  • Parse uploaded English VTT/SRT into cue objects.
  • Remove empty cues and exact duplicate cues.
  • Keep the original English wording when the downloaded subtitle content is already correct.
  • Ask DeepSeek to translate each cleaned English cue into natural Chinese for English learners.
  • Save a clean English VTT and a matching Chinese VTT back to the material.
  • Return a processing report, including cue count before/after, duplicate count, and translation count.

The first version does not promise automatic audio timestamp correction. It exposes the structure needed for that later, but does not pretend DeepSeek can listen to the uploaded video.

Architecture

Backend additions:

  • backend/ai_config.py: reads environment variables and reports whether DeepSeek is configured.
  • backend/subtitle_tools.py: parses, cleans, deduplicates, and builds VTT files.
  • backend/deepseek_client.py: small HTTP client for the DeepSeek-compatible chat API.
  • backend/subtitle_ai.py: orchestrates clean-and-translate processing.
  • New API endpoints in backend/main.py:
    • GET /api/ai/status
    • POST /api/ai/test
    • POST /api/videos/{video_id}/ai/subtitles

Frontend additions:

  • Admin page AI panel near the subtitle editor.
  • Buttons for 测试 AI 连接 and AI 修复并翻译字幕.
  • Status and result messages shown in plain Chinese.

Data Flow

  1. Admin uploads video and English subtitles as usual.
  2. Admin clicks AI 修复并翻译字幕.
  3. Backend loads the material and English subtitle content from SQLite.
  4. subtitle_tools parses and cleans cues locally.
  5. deepseek_client sends the cleaned cue list to DeepSeek for Chinese translation.
  6. subtitle_ai validates that translation count matches English cue count.
  7. Backend updates the existing English subtitle and upserts the Chinese subtitle.
  8. Admin page refreshes the material list and shows a report.

Error Handling

If API config is missing, return a friendly 400 with the missing setup information.

If DeepSeek returns invalid JSON or the wrong number of translations, return a readable error and leave the existing material unchanged.

If the material has no English subtitle, return a readable error saying English subtitles are required first.

If the API call times out, return a readable retry message and leave existing subtitles unchanged.

Future ASR Calibration

True timestamp calibration needs an ASR provider that can process audio and return sentence or word timestamps. The first version prepares the interface boundary but leaves ASR_PROVIDER disabled.

Later flow:

video -> extract audio -> ASR timestamps -> align cleaned English text -> DeepSeek translate -> save EN/ZH VTT

DeepSeek remains the translation and text cleanup provider. ASR can be added as a separate provider without changing the admin workflow.

Testing

Unit tests cover:

  • Empty cue removal.
  • Exact duplicate cue removal.
  • VTT rebuild output.
  • Missing DeepSeek config status.
  • Translation count validation.

Integration-style tests cover:

  • AI endpoint rejects missing API key clearly.
  • AI endpoint rejects materials without English subtitles.
  • AI endpoint updates English and Chinese subtitles when given a fake DeepSeek client.