Creator Quest Card Background Audio | WyzQuests Documentation

Feature Owner: Joshua Uriel Tribiana
Module: Quest Editor Form Mode / Quest Content Cards
Priority: P1
Status: Handoff (To Do)
Date: 07/03/2026

EXECUTIVE SUMMARY

What is this feature?
This feature enables creators to attach background audio to individual quest cards inside the form editor. Audio is uploaded per card, stored in content metadata (audio_url), and made available to learner renderers for playback.

Why does it matter?
Creators need richer storytelling and guided content delivery without relying on quest-level media only. Per-card audio improves immersion, clarity, and instructional pacing.

What’s the MVP scope?

Upload audio to a specific quest card
Persist audio_url in card content
Show preview and remove controls in editor
Ensure learner card renderers can play attached audio

1. USER PAIN POINT & SOLUTION

Current State (Without Feature)

Creators can add visual and text content per card but cannot consistently attach card-specific audio context.

Pain Point

Emotional: Frustration when content feels static or under-guided
Functional: No card-level audio attach/remove flow in editor
Business Impact: Lower engagement and weaker instructional design options

Future State (With Feature)

Each supported quest card editor includes a Background Audio tab where creators can upload, preview, and remove card-specific audio.

Marketing Hook

“Bring each quest card to life with optional narration and ambient audio.”

2. 4D FRAMEWORK MAPPING

Diagnose

Identifies the content delivery gap between global quest media and card-level instructional context.

Design

Adds a reusable card-level audio control surface (CardAudioUpload) across supported card editors.

Develop

Implements upload, persistence, and immediate update behavior for audio_url in card content payload.

Deliver

Learner-facing card renderers consume audio_url and play background audio where configured.

3. USER FLOWS

Entry Point

Creator opens a quest card in form editor and switches to the Background Audio tab.

Success Criteria

Audio uploads successfully
Card content stores audio_url
Creator can preview/remove audio
Learner playback reflects saved audio

Main Flow (Happy Path)

Creator opens a card edit modal in form editor.
Creator selects Background Audio tab.
Creator uploads an audio file.
Upload route stores file and returns public URL.
Editor updates card content with audio_url.
Card changes are persisted and reloaded correctly.

Edge Cases

No data: Card has no audio_url and displays no audio preview.
API error: Upload/save fails and UI shows toast error.
Permission denied: Ownership/auth checks block update route.

Decision Points

IF file exceeds size limit → block upload and show validation error.
ELSE upload file and persist audio_url.
IF creator removes audio → set audio_url undefined/null and persist.

4. INFORMATION ARCHITECTURE

Primary Information (Always visible)

Card title/content editor
Audio upload input
Audio attached status

Secondary Information

Audio preview player
Upload in-progress state

Tertiary Information (Hidden until needed)

Storage file path
Upload response payload fields
Ownership/access control context

Actions

Primary CTA:

Upload Background Audio

Secondary Actions:

Remove Audio
Save card edits

5. WIREFRAMES

Key Screens:

Card edit modal with Background Audio tab
Audio upload control state
Audio attached/preview state
Upload validation error state
Audio removed state

Annotations:

Audio upload uses quest/card scoped form-data payload.
audio_url updates are persisted immediately in edit flow.

6. WIREFLOWS

+----------------------+
| Creator Form Editor  |
+----------------------+
           |
           v
+----------------------+
| CardAudioUpload      |
+----------------------+
           |
           v
+----------------------+
| useQuestFileUpload   |
+----------------------+
           |
           v
+------------------------------------------------------+
| POST /api/creator/quest-content-cards/upload-media   |
+------------------------------------------------------+
           |
      +----+----+
      |         |
      |         |
      v         v
+-------------------------------+   +--------------------------------------+
| Supabase Storage              |   | quest_content_cards.content.audio_url |
| public-assets                 |   +--------------------------------------+
+-------------------------------+                 |
                                                  v
                                  +-------------------------------+
                                  | Immediate local state update  |
                                  +-------------------------------+
                                                  |
                                                  v
                  +------------------------------------------------------+
                  | PUT /api/creator/quest-content-cards/update          |
                  +------------------------------------------------------+
                                                  |
                                                  v
                                  +--------------------------------------+
                                  | Learner renderers consume audio_url  |
                                  +--------------------------------------+

7. PROTOTYPE

How to test:

Open a quest in form editor.
Edit a supported card and open Background Audio tab.
Upload audio under size threshold.
Confirm preview appears and save persists after reload.
Remove audio and confirm playback is gone in learner view.

8. BACKEND SCHEMA

Database Tables

quest_content_cards

Relevant fields:

id
quest_id
type
content (JSON)
updated_at

Content shape includes:

audio_url?: string

Indexes and constraints:

Existing quest/content-card constraints apply.
Ownership enforced through quest lookup + agency ownership checks in API routes.

9. API ENDPOINTS

POST /api/creator/quest-content-cards/upload-media

Purpose: Upload media file for a quest content card
Auth: Required

Request (FormData):

file
quest_id
card_type
card_id
upload_field (audio_url for this feature)

Success response:

{
  "success": true,
  "file_url": "https://...",
  "file_path": "quests/{quest_id}/content-cards/{card_id}/content.ext",
  "link": "https://...",
  "card": { "id": "...", "content": { "audio_url": "https://..." } }
}

PUT /api/creator/quest-content-cards/update

Purpose: Persist card content updates
Auth: Required

Request (JSON):

{
  "id": "card-id",
  "content": {
    "audio_url": "https://..."
  }
}

GET /api/creator/quest-content-cards/list

Purpose: Fetch card list including persisted content metadata
Auth: Required

10. DATA REQUIREMENTS

Frontend Needs

Card ID and quest ID
Existing card content JSON
audio_url field
Upload status and error state

API Calls Frontend Will Make

POST /api/creator/quest-content-cards/upload-media on upload action
PUT /api/creator/quest-content-cards/update on immediate audio update
GET /api/creator/quest-content-cards/list on load/reload

Caching Strategy

Editor relies on live fetch/update behavior and local state sync.
No dedicated audio metadata cache currently.

11. PERFORMANCE CONSIDERATIONS

Database Optimization

Uses existing quest_content_cards update path.
No schema expansion required for MVP.

Query Optimization Notes

Card updates are scoped by id and quest_id.
Upload path includes minimal post-upload content update payload.

API Response Time

Target: sub-2s for metadata update, variable for file upload based on file size/network.

12. SECURITY & AUTHORIZATION

Who can access this feature?

Creator: ✓
Reviewer: ✗
Learner: ✗ (authoring UI)

Authorization Logic

Creator/agency context required.
Quest ownership verified before upload/update.

Data Validation

Required upload fields validated in route.
Valid card_type enforced.
Client-side audio size check currently set at 10MB.

13. ERROR HANDLING

Common Errors

400 Bad Request: missing upload metadata or invalid card type
401/403 Unauthorized: ownership/auth scope failure
404 Not Found: quest or card missing
500 Server Error: storage upload or card update failure

14. TESTING CHECKLIST

Happy Path

Upload audio on each supported card editor
audio_url persists and reloads
Audio preview renders in editor
Learner playback works for cards with audio_url

Edge Cases

Oversized audio file validation
Invalid card type rejection
Upload API failure handling
Audio remove + persistence verification

15. OPEN QUESTIONS

For Frontend

Should upload progress UI be more explicit (percent/progress bar)?
Should remove action be soft (undo) before persistence?

For Backend

Should server enforce audio MIME + max file size in route?
Should replaced audio_url files be cleaned up to prevent storage orphans?

16. OUT OF SCOPE (v1.1+)

Not building in this scope:

Audio waveform editing
Audio trimming/fade controls
Transcoding and bitrate normalization pipeline

Why: MVP focuses on reliable per-card upload and persistence.

17. SUCCESS METRICS

How will we know this feature is successful?

High success rate for card-level audio uploads
Stable audio_url persistence across reloads
Increased creator usage of per-card audio in published quests

18. DEPENDENCIES

This feature depends on:

Quest content card API routes
Supabase storage upload pipeline
Form editor card modal architecture

These features depend on this:

Learner card-level audio playback consistency
Rich media authoring parity across card types

19. TIMELINE & OWNERSHIP

Week (12) Implementation

New Owner: Patrick Babala
QA: To assign

Estimated Completion: End of assigned sprint window after QA signoff