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/statusPOST /api/ai/testPOST /api/videos/{video_id}/ai/subtitles
Frontend additions:
- Admin page AI panel near the subtitle editor.
- Buttons for
测试 AI 连接andAI 修复并翻译字幕. - Status and result messages shown in plain Chinese.
Data Flow
- Admin uploads video and English subtitles as usual.
- Admin clicks
AI 修复并翻译字幕. - Backend loads the material and English subtitle content from SQLite.
subtitle_toolsparses and cleans cues locally.deepseek_clientsends the cleaned cue list to DeepSeek for Chinese translation.subtitle_aivalidates that translation count matches English cue count.- Backend updates the existing English subtitle and upserts the Chinese subtitle.
- 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.