# Sprint G007 — Music Engine

## Objective

The Media Engine (G004), Image Processing Engine (G005), and Guest & Invitation Engine (G006) have already been completed.

Do NOT redesign or replace any existing architecture.

Your responsibility is to review the existing implementation first, then extend it into a production-ready Music Engine that integrates naturally with the current Invitation architecture.

This sprint must reuse the existing Media Engine.

---

# Phase 1 — Architecture Review (Mandatory)

Before writing any code, review the current implementation.

Analyze:

- Media Engine
- Image Processing Engine
- Invitation Builder
- Public Invitation
- Theme Rendering
- Existing MediaService
- Existing storage hierarchy
- Existing JSON metadata
- Existing routes
- Existing controllers

Determine whether the current architecture is suitable.

If it already is:

- Extend it.
- Do NOT redesign it.
- Only introduce changes when there is a clear architectural benefit.

---

# Existing Architecture

The following already exist:

- Media Engine
- Image Processing Engine
- music_cover slot
- music_file slot
- MediaService
- ImageProcessor

These components must remain the primary source of truth.

Do NOT create another upload system.

---

# Objective

Transform the existing music upload capability into a complete Music Engine.

The Music Engine should provide:

- Background music
- Floating music player
- Play / Pause
- Progress indicator
- Music cover
- Song information
- Theme integration
- Automatic state management

---

# Music Configuration

Each invitation should support:

- Enable / Disable music
- Song title
- Artist name (optional)
- Music cover
- Audio file
- Autoplay
- Loop
- Start minimized
- Volume preference (optional)

Reuse the existing invitation configuration whenever possible.

Do NOT redesign the JSON structure unless absolutely necessary.

---

# Floating Music Player

Create a reusable floating player.

Requirements:

- Responsive
- Minimal
- Elegant
- Theme independent

Functions:

- Play
- Pause
- Progress
- Current Time
- Duration
- Cover image
- Song title

The player should work across every invitation theme.

---

# Browser Compatibility

Modern browsers often block autoplay.

Handle this gracefully.

Requirements:

- Attempt autoplay when enabled.
- If autoplay is blocked:
    - Display a Play button.
    - Do not display browser errors.
- Resume playback after user interaction.

---

# Performance

Optimise loading.

Requirements:

- Lazy load audio.
- Avoid blocking initial page rendering.
- Do not preload large audio unnecessarily.
- Reuse existing MediaService serving mechanism.

---

# Integration

The player must integrate naturally into the Public Invitation.

Flow:

Invitation

↓

Load Theme

↓

Load Media

↓

Load Music Configuration

↓

Render Floating Player

↓

Play Music

Do not duplicate business logic.

---

# Accessibility

Support:

- Keyboard controls
- Mobile devices
- Touch controls
- Screen resizing

---

# UI

Maintain the current design philosophy.

The player should feel premium.

Avoid overly large controls.

Support both desktop and mobile.

---

# Security

Reuse all existing Media Engine protections.

Review:

- Audio serving
- Authorization
- File validation
- Path traversal prevention

Improve only if necessary.

---

# Storage

Reuse:

storage/uploads/couples/

Reuse:

- music_cover
- music_file

Do NOT introduce new storage locations unless absolutely necessary.

---

# Deliverables

Produce:

- Updated MediaService (only if required)
- Updated Invitation configuration
- Music player component
- Updated Public Invitation integration
- Updated documentation

Avoid database migrations unless absolutely necessary.

---

# Validation

Before completing the sprint:

- Verify every modified file.
- Ensure no syntax errors.
- Verify desktop compatibility.
- Verify mobile compatibility.
- Verify autoplay behaviour.
- Verify fallback behaviour.
- Verify Media Engine compatibility.
- Verify Image Processing compatibility.
- Verify Public Invitation compatibility.

---

# Important

This sprint extends the existing architecture.

Do NOT redesign the application.

Prioritise:

- Maintainability
- Scalability
- Backward Compatibility
- Premium User Experience
- Minimal Breaking Changes

Always review the current implementation before introducing any modifications.

# Additional

The Music Player must preserve playback state during page interactions whenever possible.

Examples:

- Opening RSVP modal should not restart the music.
- Closing gallery modal should not restart the music.
- Theme interactions should not recreate the audio element.