🎧 TOEIC Listening Items
How LinguFlow stores, authors, and plays TOEIC Listening media (Parts 1–4). Reading parts (5–7) leave audio and photo empty.
Shipped in v1.1.1 (PR #97) on the v1 bank columns.
Assessment v2 (0017 / 0018) moved media into stimulus / question version
DSL blocks (AudioBlock, ImageBlock, …) — there are no longer
questions.audio_url / image_url / passage_group columns. The part taxonomy
and R2 upload pipeline below still apply; storage shape follows
Question & Exam Design.
Related: Card Image Uploads (same R2 presign pipeline), API Documentation, Architecture & Database Schema.
🎯 What this is
Questions stay in the shared bank. Listening does not add a dedicated
clip table. Shared conversation/talk material is a Stimulus with versioned
blocks; stems are Questions that reference it. Audio/photo values remain
dual-mode (https URL or R2 object key).
Bank listings omit signed play URLs. An attempt paper may resolve short-lived play URLs for pinned stimulus/question versions so sitters never need an owner presign.
🧩 Part conventions (TOEIC)
| Part | Form | Required media | Shared how |
|---|---|---|---|
| 1 Photos | Single question | Audio + photo | — |
| 2 Question–Response | Single question | Audio | — |
| 3 Conversations | Passage set (2+ stems) | One audio on every stem | Same passageGroup + same audio key |
| 4 Talks | Passage set (2+ stems) | One audio on every stem | Same as Part 3 |
| 5 Incomplete sentences | Single question | None | — |
| 6 Text completion | Passage set | None | Shared passage + passageGroup |
| 7 Reading | Passage set | None | Shared documents joined into passage |
The API does not require media by part (drafts and later TTS can stay empty). The bank compose UI does: TOEIC Parts 1–4 cannot save without audio; Part 1 also requires a photo.
✍️ Authoring (question bank + composer)
- New TOEIC items default to Part 1. The compose part select has no “Any part” option. Scan filters still offer Any so you can list the whole bank.
- Changing the single form to a set part (3, 4, 6, 7) switches to Create passage set with that part selected. Changing a set to a solo part (1, 2, 5) switches back.
- Parts 1–2 use the single form. Parts 3–4 use the set form: required audio
once, optional script, then stems.
POST /api/questions/setscopiesaudioUrlonto every created stem. - Removing an uploaded clip or photo opens a confirm dialog first.
- Preview uses the same tape transport (
ListeningDeck) as the exam, with seek and no autoplay.
Frontend: QuestionForm.vue, PassageSetForm.vue,
frontend/src/shared/examStructure.ts (EXAM_STRUCTURES, isListeningPart(),
isSetPart()) and frontend/src/shared/listening.ts (listeningDeckKey()).
Backend mirror: app/core/exam_structure_catalog.py.
🧪 Sitting, preview, and results
| Surface | Autoplay | Seek |
|---|---|---|
Live exam (ExamView / QuestionCard) | Yes (clip starts when the item mounts) | No |
| Composer step 3 preview | No | Yes |
| Results replay | No | Yes |
| Bank / set authoring preview | No | Yes |
Parts 3–4 reuse one deck for the whole passageGroup so changing stem does
not restart the clip. Leaving an in-progress session (route change or
tab close) shows a warning; saved drafts are not deleted on leave.
Built-in seeded Part 1 items may have no R2 objects — the player shows “Audio unavailable” / “IMAGE UNAVAILABLE” rather than failing the sit.
📦 Media contract
Same presign $\rightarrow$ browser PUT $\rightarrow$ confirm flow as cards. Pass
purpose: "question" so the final key is under questions/, not cards/.
| Card | Question | |
|---|---|---|
purpose | "card" (default) | "question" |
| Final prefix | cards/{userId}/{uuid}.ext | questions/{userId}/{uuid}.ext |
| Types | PNG / JPEG / WebP | Those images plus MP3 / WAV / WEBM / M4A |
| Size (browser) | 10 MB images | 10 MB images, 15 MB audio |
Persisted URLs must be https or a key (no scheme). http:// is 422.
Session play resolution returns https://… as-is, signs R2 keys, and
returns null for http:// or a sign failure (the sit still loads).
Once a question has a submitted answer (AnswerRecord.user_answer != ""),
options, the correct answer, and media keys are frozen (409). Wording,
script (passage), tags, and difficulty stay editable.
DELETE /api/media/{file_key} refuses a key still referenced by a card or
a question.
🔌 API (listening-specific)
Question create / update / set bodies accept camelCase audioUrl and
imageUrl. Set create also accepts a shared audioUrl (copied to each stem)
and may omit passage/documents when audio is present.
Attempt paper payloads (GET /api/attempts/{id} / start responses) may add:
{
"audioUrl": "questions/<userId>/<uuid>.mp3",
"imageUrl": "questions/<userId>/<uuid>.jpg",
"audioPlayUrl": "https://…signed…",
"imagePlayUrl": "https://…signed…"
}
audioPlayUrl is session-scoped (the sitter already owns the session). Do
not switch session serialization to a question-ownership gate — built-in
items have user_id = NULL and would lose their play URL and answer key.
Media:
// POST /api/media/presign-upload
{ "filename": "clip.mp3", "contentType": "audio/mpeg", "purpose": "question" }
CORS, bucket policy, and .env reload rules are identical to
Card Image Uploads. Audio PUTs also send Content-Type,
so the bucket must allow that header.
🚫 Out of scope (this feature)
- Official 200-item TOEIC seed with real R2 clips
- TTS / generated audio
- A first-class Passage / Clip entity (sets stay a
passageGroupmarker) - Redis, CDN invalidation, or an upload queue