95 lines
3.0 KiB
Markdown
95 lines
3.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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
|
|
|
|
```bash
|
|
python -m pytest sentence_api/tests -q
|
|
```
|
|
|
|
See [DEPLOYMENT.md](DEPLOYMENT.md) for Docker, MOSS/Whisper, Nginx HTTP 回源,
|
|
large-file
|
|
upload, backup, and production operation instructions.
|