mediaplayer/sentence_api/README.md

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

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.