# Sprint G004, G005, G006, & G007 — Walkthrough

## Sprint G007 — Music Engine

The **Music Engine** completes the background music and media capabilities of the wedding invitation platform, integrating an elegant floating player with state management, volume preferences, and browser autoplay handlers.

---

## Files Created & Modified

### New Files
- [music_player.php](file:///c:/xampp/htdocs/inveetaire/app/views/components/music_player.php): Responsive floating background music player component. Supports play, pause, progress fill tracking, total duration/elapsed time indicators, vinyl rotating album disk art, and keyboard spacebar shortcuts. Scopes state storage keys to individual guest tokens to prevent local cache leakage.

### Modified Files
- [routes.php (PublicInvitation)](file:///c:/xampp/htdocs/inveetaire/app/modules/PublicInvitation/routes.php): Registered public unauthenticated route `/i/media/serve` to stream media files to visiting guests.
- [routes.php (Media)](file:///c:/xampp/htdocs/inveetaire/app/modules/Media/routes.php): Registered POST `/invitation/media/music-settings` route to store music parameters under the couple's portal.
- [MediaService.php](file:///c:/xampp/htdocs/inveetaire/app/services/MediaService.php): Updated `buildServeUrl()` to construct public serve URLs (`/i/media/serve`) so both the dashboard editor and the guest page stream audio and images without authentication conflicts.
- [InvitationModel.php](file:///c:/xampp/htdocs/inveetaire/app/modules/Invitation/InvitationModel.php): Modified `defaultMediaMeta()` to register defaults for new music settings (Enable music, Loop, Autoplay, Title, Artist, Minimized, Volume).
- [MediaController.php](file:///c:/xampp/htdocs/inveetaire/app/modules/Media/MediaController.php):
  - **`servePublic(Request $request)`**: Exposes a secure serve endpoint for unauthenticated users, verifying that the file path belongs to an active workspace with a published invitation.
  - **`saveMusicSettings(Request $request)`**: Saves enabling status, track title, artist name, loop, autoplay, volume level, and minimized attributes to the media JSON.
- [media.php (view)](file:///c:/xampp/htdocs/inveetaire/app/views/invitation/media.php): Integrated music configuration options into the Media Manager UI: Enable Background Music, Song Title, Artist Name, Autoplay, Loop, Start Minimized, and Volume slider. Submits data asynchronously via AJAX POST with immediate toast notifications.
- [identity.php (view)](file:///c:/xampp/htdocs/inveetaire/app/views/public/identity.php): Resolves music settings from the layout sections payload and renders the floating music player component dynamically.

---

## State Persistence & Autoplay Policy

- **Autoplay Handling**: Attempts HTML5 audio autoplay. If blocked by the browser, catches the promise error, fails silently without console logs, and registers temporary `click` and `touchstart` event listeners on the `document` to start playback upon the guest's first interaction.
- **Playback Persistence**: Continually saves current track position and playing state in `sessionStorage`. When the page is reloaded (e.g. following RSVP submissions or wishes submissions), extracts the saved timestamp and resumes playback seamlessly without starting the song over.

---

## Validation & Testing Results

- ✅ `PublicInvitation/routes.php` — No syntax errors
- ✅ `Media/routes.php` — No syntax errors
- ✅ `MediaService.php` — No syntax errors
- ✅ `InvitationModel.php` — No syntax errors
- ✅ `MediaController.php` — No syntax errors
- ✅ `media.php` view — No syntax errors
- ✅ `identity.php` view — No syntax errors
- ✅ `music_player.php` component — No syntax errors
- ✅ Direct file serving security is fully preserved