Feature Owner (original Hand-Off): Joshua Uriel Tribiana
Updated by / current owner: Patrick Babala (babalapatrick@gmail.com)
Reviewers: @clydetims (Clyde Ador), @cdnzn (Christian Denzon), @ybcole (Cole)
Module: Quest Editor Form Mode / Visual Canvas / Quest Content Cards / Learner Quest Player
Priority: P1
Status: Handoff — Updated and Published (v2.0)
Date: 09/30/2026
Issue: GitHub Issue #4 — [1.7.2] (Creator) Add audio feature in each Quest Card (closed 2026-07-16)
PRs: #667 (core feature, merged 2026-07-14), #790 (upload rework, merged 2026-08-28), #741 (audio asset fallback, merged 2026-08-06)
Related PRs: #13 (prior partial implementation), #695 (mp3 background-asset upload fix)
Companion doc: Internal Technical Guide — architecture, schema, API specs, tests. This Hand-Off stays product-facing and cross-references the ITG for engineering depth.
EXECUTIVE SUMMARY
What is this feature?
Creators can attach background audio to an individual quest card in the form editor and to an individual node in the visual canvas. Each card/node can use one of three sources — upload a local file, paste a URL, or pick from the creator's Background Assets library. The audio is stored as audio_url in the card content (and as node data.audio_url on the canvas) and is played for learners. A quest-level background_audio_url track is also played for learners with a per-quest volume.
Why does it matter?
It gives creators richer storytelling and guided content delivery at the card level, instead of relying on quest-level media only. It improves immersion, clarity, and instructional pacing.
Shipped scope (v2.0):
Background Audio control on supported form-editor cards (Text, Image, File, Link, Codeblock, Discussion, Scenario, Question).
Background Audio panel on visual-canvas nodes (via the node's Music button), including nodes without a form editor (e.g. Reflection, Quiz).
Three source options per card/node: Upload Local (≤10 MB), Via Link, From Assets.
Learner playback with an auto-playing loop, plus a bottom-right speaker toolbar (mute + volume).
Quest-level global audio plays for learners with a volume that is remembered per quest.
Published-quest protection: editing audio on the canvas confirms and moves the quest back to Draft.
Still deferred (v1.1+): waveform editing, trimming/fades, and transcoding/bitrate normalization.
USER PAIN POINT & SOLUTION
Current State (Without Feature)
Creators could add visual and text content per card but could not consistently attach card-specific audio context. Audio existed only via the dedicated Audio card or at the quest level; the visual canvas had no per-node audio, and the quest-level track was not surfaced to logged-in learners.
Pain Point
Emotional: Frustration when content feels static or under-guided.
Functional: No card-level audio attach/remove flow in the editor (and none in the canvas); no learner controls for background audio.
Business Impact: Lower engagement and weaker instructional design options.
Future State (With Feature)
Each supported editor surface includes a Background Audio control where creators upload, link, or pick audio, preview it, and remove it. Learners hear the per-card audio automatically with a mute/volume toolbar, and the quest-level track plays with a per-quest volume.
Marketing Hook
"Bring each quest card to life with optional narration and ambient audio."
4D FRAMEWORK MAPPING
Diagnose
Identifies the content-delivery gap between global quest media and card-level instructional context, and the parity gap between the form editor and the visual canvas.
Design
Adds reusable audio surfaces — CardAudioUpload (form editor), CanvasAudioSection (canvas node toolbar), and the learner AudioIndicator toolbar.
Develop
Implements per-card upload via signed URLs (direct-to-storage), immediate persistence of audio_url, form↔canvas sync, and learner hooks for per-card and quest-level playback.
Deliver
Learner cards auto-play their attached audio with mute/volume controls; the quest-level track plays with a per-quest, locally remembered volume.
USER FLOWS
Entry Point
Form editor: open a quest card's edit modal and switch to the Background Audio control.
Visual canvas: open a node's Music button (tooltip "Background Audio").
Quest level: the quest's Media section holds the quest-wide background audio and its learner-volume slider.
Success Criteria
Audio can be provided by local upload, external URL, or an existing asset.
The card/node stores
audio_urland it survives reload.The creator can preview and remove the audio.
The learner hears the audio automatically and can mute/adjust volume.
Adding/removing audio on a published quest prompts the creator to confirm a return to Draft.
Main Flow (Happy Path)
Creator opens a card (form) or node (canvas) and opens the Background Audio control.
Creator chooses a source: Upload Local, Via Link, or From Assets.
For a local file, the editor requests a signed upload URL, uploads the file directly to storage, and receives the public URL.
The card's
audio_url(or the node'sdata.audio_url) is set and saved; the editor shows a preview player.On a canvas node of a published quest, the creator confirms before the change is applied.
A learner opening the quest hears the per-card audio via the auto-playing loop and can mute or change volume in the bottom-right toolbar; the quest-level track also plays with its per-quest volume.
Edge Cases
No data: a card without
audio_urlshows no audio preview.API error: upload/save failure surfaces a toast error.
Permission denied: ownership/auth checks block the upload and update routes.
Oversized file: audio over 10 MB is rejected before upload.
Wrong file type: non-audio files are rejected.
Decision Points
IF the file exceeds 10 MB → block the upload and show a validation error.
ELSE upload the file and persist
audio_url.IF the file is not a valid audio type → block and show an error.
IF the target canvas node is on a published quest → confirm (and revert to Draft) before applying.
IF the current learner card is a Video node → suppress the per-card background audio.
IF the creator removes audio → set
audio_urlto undefined/empty and persist.
INFORMATION ARCHITECTURE
Primary Information (Always visible)
Card/node content editor.
Background Audio control with the three source tabs.
Audio attached status (preview player or empty state).
Secondary Information
Audio preview player with loop.
Upload-in-progress state.
Asset browser count (
Browse Assets (n)).
Tertiary Information (Hidden until needed)
Storage file path.
Upload response payload fields.
Ownership/access-control context.
Actions
Primary CTA: Upload Background Audio (or Apply URL / select an asset).
Secondary actions: Remove Audio, Save card edits, confirm published-quest edit.
WIREFRAMES
Key Screens:
Card edit modal with a Background Audio area and three source tabs (Upload Local / Via Link / From Assets).
Canvas node with the Music toolbar button expanded to the inline audio panel.
Audio asset picker (browse the creator's audio assets).
Audio attached / preview state (player + Remove Audio).
Upload validation error state (size/type).
Learner bottom-right speaker toolbar (mute + volume).
Annotations:
Audio is scoped to the quest/card (form) or quest/node (canvas).
audio_urlupdates in the form editor are persisted immediately.Canvas changes to a published quest require confirmation and revert the quest to Draft.
WIREFLOWS
FORM EDITOR (linear quests)+----------------------+ +----------------------+| Creator Form Editor | | CardAudioUpload |+----------------------+ +----------------------+ | | v v+----------------------+ choose source: Local | Link | Assets| Card edit modal |+----------------------+ | v+----------------------------------+| POST /get-upload-url (signed) |+----------------------------------+ | PUT file -> Supabase Storage | v+------------------------------+ +----------------------------------+| quest_content_cards.content |<------| Immediate persist (PUT /update) || audio_url | +----------------------------------++------------------------------+ | vVISUAL CANVAS (exploration quests) +----------------------------------++----------------------+ | Learner: useBackgroundAudio || NodeToolbar (Music) | | + AudioIndicator toolbar || CanvasAudioSection |--- same URL --+----------------------------------++----------------------+ | Quest-level: useGlobalBackground | | Audio (background_audio_url) | +----------------------------------+
PROTOTYPE
How to test:
Open a quest in the form editor.
Edit a supported card and open the Background Audio control.
Upload audio under 10 MB (or paste a URL, or pick an asset).
Confirm the preview appears and that the change persists after reload.
Repeat on a canvas node using the node's Music button.
Configure the quest-level background audio and learner volume in the Media section.
Open the quest as a learner: confirm per-card audio auto-plays with the toolbar, and the quest-level track plays with the saved volume.
Remove audio and confirm playback stops.
BACKEND SCHEMA
Database table
quest_content_cards— the card'scontentJSON includesaudio_url?: string.
Relevant fields:
id,quest_id,type,content(JSON),updated_at.
Also involved
quests.canvas_metadata— each node'sdata.audio_url(visual canvas).quests.background_audio_url— the quest-level track.asset_metadata.asset_type = 'AUDIO'— reusable audio assets.
Indexes and constraints:
Existing quest/content-card constraints apply.
Ownership is enforced through quest lookup + agency ownership checks in the API routes.
No schema migration was required for
audio_url(it lives in JSONB).
Full column/index detail and the ERD live in the Internal Technical Guide §3.1.
API ENDPOINTS
Changed in v2.0: the old multipart POST /api/creator/quest-content-cards/upload-media endpoint no longer exists — it was removed in PR #790. Card media now uploads through a two-step signed-URL flow.
POST /api/creator/quest-content-nodes/get-upload-url
Purpose: Validate the file and mint a short-lived signed upload URL.
Auth: Required (creator/agency ownership verified).
Body (JSON):
{ "quest_id": "uuid", "node_id": "card-or-node-id", "node_type": "audio", "file_ext": "mp3", "file_size": 1234567, "file_type": "audio/mpeg"}
Returns: { signed_url, token, path, public_url }. Audio is limited to 10 MB.
PUT (signed URL)
Purpose: The browser uploads the file bytes directly to Supabase Storage (public-assets).
Auth: The signed URL itself (valid ~60 seconds).
PUT /api/creator/quest-content-cards/update
Purpose: Persist card content (including audio_url) and sync the card into the canvas for linear quests.
Auth: Required.
GET /api/creator/quest-content-cards/list
Purpose: Fetch the card list including persisted content metadata on load/reload.
Auth: Required.
GET /api/learner/get-quest
Purpose: Deliver the quest to the learner, including canvas_metadata (per-card data.audio_url) and background_audio_url.
Auth: Learner context.
POST /api/creator/upload-background-media
Purpose: Upload the quest-level background audio/image.
Auth: Required.
DATA REQUIREMENTS
Frontend Needs
Card ID and quest ID.
Existing card content JSON (including
audio_url).Node
data.audio_urlfor canvas.Upload status (uploading/idle) and error state.
API Calls the Frontend Makes
POST /api/creator/quest-content-nodes/get-upload-urlon upload.Direct
PUTto the returned signed URL.PUT /api/creator/quest-content-cards/updateon immediate audio update (form editor).Canvas changes sync through the node save path.
GET /api/creator/quest-content-cards/liston load/reload.GET /api/learner/get-queston the learner side.
Caching Strategy
Audio previews and playback use a cache-busting query (
?t=<timestamp>) so a replaced file is not served from cache.No dedicated audio-metadata cache.
The quest-level learner volume is stored in browser
localStorageunderglobalBackgroundAudioVolume:{questId}.
PERFORMANCE CONSIDERATIONS
Upload Path
Files upload directly to storage via a signed URL, avoiding the reverse-proxy body-size limit that the old multipart route hit.
Signed URLs are valid for ~60 seconds; re-uploading the same object name overwrites it (
upsert).
Database
Uses the existing
quest_content_cardsupdate path; no schema expansion.Card updates are scoped by
id/quest_id.
API Response Time
Target sub-2s for the metadata update; file upload time varies with size/network.
SECURITY & AUTHORIZATION
Who can access this feature?
Creator: yes (authoring UI).
Reviewer: no.
Learner: playback only (no authoring UI).
Authorization Logic
Creator/agency context required.
Quest ownership is verified before upload and update.
Path segments in upload/delete requests are validated to prevent path traversal.
Data Validation
Audio size is limited to 10 MB (client and server).
File type is validated by an allow-listed MIME, with an extension fallback for browsers that report an empty/odd MIME (e.g. some
.mp3files).Non-audio files are rejected.
Published-quest protection: canvas audio edits confirm before moving the quest back to Draft.
ERROR HANDLING
400 Bad Request: missing/invalid upload metadata, invalid
node_type, file too large, invalid file type, or invalid file path.401 / 403 Unauthorized: ownership/auth scope failure.
404 Not Found: quest or card missing (or not owned by the creator/agency).
500 Server Error: storage signing/upload failure or card update failure.
Common creator-visible messages include "Audio file size must be less than 10MB", "Please enter an audio URL", "Invalid URL format", and a generic upload failure toast.
TESTING CHECKLIST
Happy Path
Upload audio on each supported form card editor (Text, Image, File, Link, Codeblock, Discussion, Scenario, Question).
Add audio on a canvas node via the Music button.
audio_urlpersists and reloads.Audio preview renders in the editor.
Learner playback works for cards with audio, with a working mute/volume toolbar.
The quest-level track plays with the per-quest volume.
Edge Cases
Oversized audio (>10 MB) is rejected.
Non-audio file is rejected.
Upload API failure shows an error.
Audio remove + persistence is verified.
Adding audio to a published quest on canvas prompts confirmation and reverts to Draft.
Per-card audio is suppressed on a Video node.
Automated coverage note (gap)
Upload-route/validation tests exist for the related quest-level media routes, but there are no automated tests for
get-upload-url,delete-media, the audio hooks, or the form-editor audio persistence. Manual QA is currently required. (See ITG §5.)
OPEN QUESTIONS
For Frontend
Should upload progress UI be more explicit (percent/progress bar)?Resolved (v2.0): an "Uploading…" state with spinner is shown; a percentage progress bar remains out of scope.Should remove action be soft (undo) before persistence?Resolved (v2.0): removal is immediate with a confirmation toast; no undo step.
For Backend
Should server enforce audio MIME + max file size in route?Resolved (v2.0): yes —get-upload-urlenforces the 10 MB audio limit and validates the file type (MIME with extension fallback).Should replacedaudio_urlfiles be cleaned up to prevent storage orphans?Resolved (v2.0):audio_urlis intentionally immediate-persist and is not auto-deleted on replace (PR #790 round 3 reverted staging because deleting a DB-referenced object broke the card's audio). Orphan cleanup for audio remains a future consideration.
OUT OF SCOPE (v1.1+)
Confirmed still out of scope (v2.0 — no change):
Audio waveform editing.
Audio trimming/fade controls.
Transcoding and bitrate-normalization pipeline.
Why: the MVP/v2 scope focuses on reliable per-card upload, persistence, and playback.
SUCCESS METRICS
High success rate for card-level and node-level audio uploads.
Stable
audio_urlpersistence across reloads (form and canvas).Increased creator usage of per-card audio in published quests.
Fewer support issues about the quest-level audio being silent for learners.
DEPENDENCIES
This feature depends on:
Quest content card API routes.
Supabase Storage upload pipeline (signed URLs).
The form-editor card modal architecture and the visual-canvas node toolbar.
These features depend on this:
Learner card-level audio playback consistency.
Rich-media authoring parity across card types.
TIMELINE & OWNERSHIP
Original owner / Hand-Off author: Joshua Uriel Tribiana (Hand-Off v1.0, July 2, 2026).
Implementation & current owner: Patrick Babala.
Reviewers: @clydetims, @cdnzn; @ybcole on the upload fixes.
QA: To assign.
Shipped: core feature 2026-07-14 (PR #667); upload rework 2026-08-28 (PR #790); audio-asset fallback 2026-08-06 (PR #741).
Estimate: complete for v2.0 scope; remaining items are the out-of-scope list above.
REFERENCES
Issue: wyzlab/WyzQuests #4 — [1.7.2] (Creator) Add audio feature in each Quest Card (closed 2026-07-16). No sub-issues exist.
Primary PR: #667 — feature/1.7.2-creator-quest-card-background-audio.
Follow-up PRs: #790 — file upload via signed URLs; #741 — empty catch blocks + audio asset fallback.
Related, not authored by the current owner: #13 — Quest content card audio integration (prior partial); #695 — resolve mp3 background asset upload failure.
Companion ITG: Internal Technical Guide — Creator Quest Card Background Audio.
VERSION HISTORY
2.0 — 2026-09-30 — Patrick Babala. Hand-Off overhaul. Updated the original v1.0 outline in place: corrected the API section (multipart
upload-media→ signed-URLget-upload-url+PUT), added the visual-canvas node audio, three-source selection, learner mute/volume toolbar, quest-level background audio with per-quest volume, and published-quest protection; resolved the Open Questions and confirmed the Out-of-Scope list. Summary of PRs: #667, #790, #741.1.0 — 2026-07-02 — Joshua Uriel Tribiana. Original Hand-Off (form-editor per-card audio,
audio_urlpersistence, preview/remove, learner renderers).