Files
speaking-practice/docs/superpowers/specs/2026-06-01-speaking-lab-content-library-design.md
T
2026-06-03 00:34:42 +08:00

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.

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:

  • title is required.
  • At least one of video_file or video_url is required.
  • If both video_file and video_url are present, the uploaded file wins.
  • Subtitle files are optional.
  • Uploaded subtitles must use .srt or .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 to published for this phase.

subtitles usage:

  • video_id: parent video.
  • language_code: en or zh.
  • language_name: English or 中文.
  • format: srt or vtt.
  • 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:

  1. Build FormData from title, speaker, description, tags, video file, video URL, English subtitle, and Chinese subtitle.
  2. Submit it to POST /api/videos.
  3. Disable the submit button and show an adding state while the request is running.
  4. On success, insert the returned video at the top of the list, clear the form, and select the new video.
  5. 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:

  1. Start the app:

    cd F:\ooo\speaking-practice-local
    python -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000
    
  2. Open http://127.0.0.1:8000.

  3. Log in with an email containing admin.

  4. Add a video using an external video or HLS URL plus English and Chinese subtitles.

  5. Refresh the page and confirm the video remains in the list.

  6. Add a video using a local video file plus subtitles.

  7. Refresh the page and confirm the local video remains playable.

  8. Confirm subtitles render and transcript clicks jump playback.

  9. Open http://127.0.0.1:8000/docs and 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 localStorage to 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.