Skip to main content

🎧 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)​

PartFormRequired mediaShared how
1 PhotosSingle questionAudio + photo—
2 Question–ResponseSingle questionAudio—
3 ConversationsPassage set (2+ stems)One audio on every stemSame passageGroup + same audio key
4 TalksPassage set (2+ stems)One audio on every stemSame as Part 3
5 Incomplete sentencesSingle questionNone—
6 Text completionPassage setNoneShared passage + passageGroup
7 ReadingPassage setNoneShared 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/sets copies audioUrl onto 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​

SurfaceAutoplaySeek
Live exam (ExamView / QuestionCard)Yes (clip starts when the item mounts)No
Composer step 3 previewNoYes
Results replayNoYes
Bank / set authoring previewNoYes

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

CardQuestion
purpose"card" (default)"question"
Final prefixcards/{userId}/{uuid}.extquestions/{userId}/{uuid}.ext
TypesPNG / JPEG / WebPThose images plus MP3 / WAV / WEBM / M4A
Size (browser)10 MB images10 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 passageGroup marker)
  • Redis, CDN invalidation, or an upload queue