Oral Trainer Video Service
FastAPI service for the Android oral-training SDK. It provides:
- chunked video upload with SHA-256 calculation;
- files stored under
data/v/and metadata stored in SQLite; - after the first processing pass, videos can be uploaded automatically to Volcano Engine Object Storage (TOS / 火山 OSS) and the catalog/share UI will use that public URL;
- background sentence transcription through MOSS-Transcribe-Diarize;
- a browser-based administration page at
/admin; - video catalog and HTTP Range playback;
- sentence-boundary lookup compatible with the existing Android SDK;
- student recording upload and
asr-fluency-v1assessment; - the legacy JSON boundary index as a read-only fallback.
Local Run
python3.12 -m venv .venv-sentence-api
. .venv-sentence-api/bin/activate
python -m pip install -r sentence_api/requirements.txt
export ADMIN_API_KEY=local-development-key
export MOSS_TRANSCRIBE_URL=http://127.0.0.1:8001/v1/audio/transcriptions
python -m uvicorn sentence_api.main:app --host 0.0.0.0 --port 8000
Open:
http://127.0.0.1:8000/admin
http://127.0.0.1:8000/docs
When MOSS_TRANSCRIBE_URL is empty, uploaded videos still receive silence-based
boundaries, but no reference transcript is produced and assessment is disabled.
When all VOLCANO_OSS_* credentials in .env.example are configured, the first
processing pass saves sentence boundaries, uploads the source video, and only
then marks it ready. stream_url and the legacy /content endpoint then point
to the OSS/CDN URL. If the upload fails, the video is marked failed so clients
do not fall back to server-local playback.
Main Endpoints
GET /healthz
GET /api/v1/videos
GET /api/v1/videos/{sha256}
GET /api/v1/videos/{sha256}/content
GET /api/v1/videos/{sha256}/sentence-boundaries
POST /api/v1/videos/{sha256}/sentences/{index}/assessments
POST /api/v1/admin/videos
PUT /api/v1/admin/videos/raw
POST /api/v1/admin/videos/{sha256}/process
PUT /api/v1/admin/videos/{sha256}/sentences/{index}
PUT /api/v1/admin/videos/{sha256}/sentences/{index}/split
PUT /api/v1/admin/videos/{sha256}/sentences/{index}/boundary
DELETE /api/v1/admin/videos/{sha256}
Admin endpoints use X-Admin-Key when ADMIN_API_KEY is configured. Assessment
requests use X-Client-Key when CLIENT_API_KEY is configured.
Assessment
curl -X POST \
http://127.0.0.1:8000/api/v1/videos/{sha256}/sentences/0/assessments \
-F audio=@student.wav \
-F language=en
The current score intentionally measures reading content and fluency:
overall = content * 80% + fluency * 20%
fluency = duration * 35% + pauses * 40% + speech rate * 25%
pronunciation_score and prosody_score remain null until a phoneme/GOP
model is connected.
Tests
python -m pytest sentence_api/tests -q
See DEPLOYMENT.md for Docker, MOSS/Whisper, Nginx HTTP 回源, large-file upload, backup, and production operation instructions.