# 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

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

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