Feat: Real shuffling #4
Description
Summary
Implement "Petal Shuffle" — a custom shuffle mode that gives users true control over shuffled playback by reordering upcoming tracks in the Spotify queue.
Background
- Spotify's built-in shuffle is often criticized for not being truly random and not giving users control.
- Petal Shuffle would take the user's current playback context (upcoming songs), shuffle them using a proper algorithm, and queue them into Spotify's playback.
- Disabling the mode or stopping playback should wipe the custom queue to restore normal behavior.
Scope
Backend (C# API)
- Create an endpoint to activate Petal Shuffle: fetch the user's current playback context, shuffle the track list, and queue the shuffled tracks into Spotify.
- Create an endpoint to deactivate Petal Shuffle: wipe/clear the user's Spotify queue of the shuffled tracks.
- Handle edge cases: no active playback, empty context, user manually skipping tracks.
Frontend (React Native)
- Add a Petal Shuffle toggle button (accessible from the playback/now-playing UI or a settings area).
- Show a visual indicator when Petal Shuffle is active.
- When deactivated, trigger the queue cleanup.
Spotify API
- Research the Spotify Web API queue endpoints (
POST /me/player/queue,GET /me/player) to determine feasibility and limitations (e.g., queue size limits, ability to clear queue).
Definition of Done
- Activate shuffle: Tapping the Petal Shuffle button fetches upcoming songs, shuffles them, and queues them into Spotify playback.
- True randomness: The shuffle algorithm produces a genuinely randomized order (not Spotify's default).
- Deactivate shuffle: Disabling Petal Shuffle clears the remaining shuffled tracks from the queue.
- Playback stop cleanup: If the user stops playback entirely, the shuffled queue is cleaned up.
- Visual indicator: The UI clearly shows when Petal Shuffle mode is active.
- No active device handling: If there is no active Spotify device, the user sees a clear error.
- Build passes: Both the C# API and the frontend compile without errors.
- Manual verification: Tested end-to-end — activate shuffle → verify tracks play in a different order → deactivate → verify queue is cleaned up.