mediaplayer/sentence_api

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;
• 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-v1 assessment;
• 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.

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}
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.