5.6 KiB
Speaking Lab Content Library Design
Goal
Turn the current Speaking Lab prototype into a local product prototype with a real content library. The first implementation focuses on content management: admins can add a video with metadata, choose either a local video file or a video/HLS URL, upload English and Chinese subtitles at the same time, and see the content persist after refresh.
Scope
In scope:
- Add backend video library APIs.
- Save uploaded video files under
uploads/videos/. - Save uploaded subtitle files under
uploads/subtitles/. - Store video metadata and subtitle records in SQLite.
- Load the video list from the backend on page startup.
- Keep existing playback, subtitle display, search, tag filtering, and transcript-click behavior where possible.
Out of scope for this phase:
- Editing or deleting videos from the web UI.
- Replacing subtitles after a video has been created.
- Real user authentication or permissions.
- Learning records, favorites, watch-later, playback progress, or AI speaking feedback.
- Server deployment, Docker, domains, HTTPS, or cloud storage.
Recommended Approach
Use the minimal content-library API approach.
The backend keeps the current FastAPI + SQLite structure. The frontend admin form submits a FormData payload to the backend instead of creating temporary browser-only object URLs. The backend decides whether the video source is an uploaded file or an external URL, saves files when present, writes database rows, and returns a normalized video object for the frontend to render.
API Design
Add these endpoints:
GET /api/videos
GET /api/videos/{video_id}
POST /api/videos
POST /api/videos accepts multipart form data:
title
speaker
description
tags
video_file optional
video_url optional
subtitle_en optional
subtitle_zh optional
Validation rules:
titleis required.- At least one of
video_fileorvideo_urlis required. - If both
video_fileandvideo_urlare present, the uploaded file wins. - Subtitle files are optional.
- Uploaded subtitles must use
.srtor.vtt. - Uploaded videos should use common browser-playable video formats such as
.mp4,.webm,.mov, or.m4v. - Tags are submitted as comma-separated text and returned to the frontend as an array.
Data Design
Reuse the existing videos and subtitles tables.
videos usage:
title: required video title.speaker: speaker or source label.description: optional description.tags: JSON string, for example["technology", "design"].video_url: final playable URL. For uploaded files this is a local static URL such as/uploads/videos/example.mp4; for external sources this is the original video or HLS URL.status: set topublishedfor this phase.
subtitles usage:
video_id: parent video.language_code:enorzh.language_name:Englishor中文.format:srtorvtt.file_path: local static URL such as/uploads/subtitles/example.srt.content: raw subtitle text.
The frontend can continue parsing subtitle content into cues with the existing parser.
Frontend Behavior
On page startup, the frontend calls GET /api/videos and renders the returned videos in the existing material list. The existing local demo videos remain as an empty-library fallback only; they are not automatically inserted into the database.
When an admin submits the existing backstage form:
- Build
FormDatafrom title, speaker, description, tags, video file, video URL, English subtitle, and Chinese subtitle. - Submit it to
POST /api/videos. - Disable the submit button and show an adding state while the request is running.
- On success, insert the returned video at the top of the list, clear the form, and select the new video.
- On failure, show the backend error message.
Existing behavior to preserve:
- Search by title, speaker, description, and tags.
- Tag filtering.
- Bilingual subtitle display.
- Click transcript line to jump the video.
- Current subtitle highlighting during playback.
Error Handling
Backend errors should be clear enough for a non-technical local user:
- Missing title:
标题不能为空 - Missing video source:
请上传视频文件或填写视频地址 - Unsupported subtitle file:
字幕只支持 .srt 或 .vtt - Unsupported video file:
视频文件格式不支持 - File save failure:
保存文件失败,请重试
The frontend can use a simple alert for this phase. A toast or notification system is out of scope.
Testing
Manual verification:
-
Start the app:
cd F:\ooo\speaking-practice-local python -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000 -
Open
http://127.0.0.1:8000. -
Log in with an email containing
admin. -
Add a video using an external video or HLS URL plus English and Chinese subtitles.
-
Refresh the page and confirm the video remains in the list.
-
Add a video using a local video file plus subtitles.
-
Refresh the page and confirm the local video remains playable.
-
Confirm subtitles render and transcript clicks jump playback.
-
Open
http://127.0.0.1:8000/docsand confirm the three video APIs are visible.
Future Work
Likely next phases after this content-library slice:
- Add edit and delete actions for videos.
- Persist real user accounts and admin permissions.
- Move favorites, watch-later, and playback progress from
localStorageto SQLite. - Add import/export or backup for the local content library.
- Package a beginner-friendly local startup script.
- Later, prepare server deployment once the local product loop is stable.