# Vinyl - iOS/Android Audio Player App

## Project Overview
A Spotify-style audio player built with React Native + Expo that plays local files and URLs.

**Location:** `~/projects/audio-player`

## Tech Stack
- **Framework:** React Native with Expo
- **Audio:** react-native-track-player
- **Navigation:** React Navigation (tabs + stack)
- **State:** Zustand (simple, lightweight)
- **Storage:** AsyncStorage (playlists, settings)
- **Styling:** React Native StyleSheet + light/dark theme support

---

## Phase 1: Project Setup & Basic Structure

### Step 1.1: Initialize Expo Project
- Install Node.js if needed
- Create new Expo project with TypeScript template
- Set up folder structure:
  ```
  vinyl/
  ├── src/
  │   ├── components/     # Reusable UI components
  │   ├── screens/        # Tab screens
  │   ├── navigation/     # Navigation config
  │   ├── store/          # Zustand state
  │   ├── hooks/          # Custom hooks
  │   ├── utils/          # Helpers
  │   ├── theme/          # Light/dark themes
  │   └── types/          # TypeScript types
  ├── assets/             # Icons, images
  └── App.tsx
  ```

### Step 1.2: Install Core Dependencies
```bash
npx expo install react-native-track-player
npx expo install @react-navigation/native @react-navigation/bottom-tabs
npx expo install react-native-gesture-handler react-native-reanimated
npx expo install @react-native-async-storage/async-storage
npm install zustand
```

---

## Phase 2: Navigation & Theme System

### Step 2.1: Tab Navigation (Spotify-style)
Create bottom tabs:
1. **Library** - Browse local files and playlists
2. **Search** - Find songs, add URLs
3. **Now Playing** - Full player screen

### Step 2.2: Mini Player Component
- Fixed at bottom, above tab bar
- Shows: album art thumbnail, song title, play/pause button
- Tap to expand to full Now Playing screen

### Step 2.3: Theme System
- Create light and dark color palettes
- Use React Context for theme switching
- Persist preference in AsyncStorage

---

## Phase 3: Audio Playback Core

### Step 3.1: Track Player Setup
- Initialize react-native-track-player service
- Configure for background playback
- Set up playback events (play, pause, next, previous)

### Step 3.2: Player Controls
- Play/Pause
- Next/Previous track
- Seek bar (scrub through song)
- Volume control

### Step 3.3: Playback Modes
- **Single track:** Play one and stop
- **Play all:** Auto-advance through queue
- **Shuffle:** Randomize queue order
- **Repeat:** Repeat one / Repeat all / Off

### Step 3.4: Queue Management
- View current queue
- Reorder tracks (drag and drop)
- Add/remove from queue
- Clear queue

---

## Phase 4: Audio Sources

### Step 4.1: Local File Access
- Use expo-document-picker to select audio files
- Use expo-file-system for file management
- Support formats: MP3, M4A, WAV, FLAC, OGG

### Step 4.2: URL Playback
- Text input to paste audio URLs
- Validate URL format
- Stream directly or download option
- Save URL tracks to library

### Step 4.3: Download for Offline
- Download URL tracks to device storage
- Show download progress
- Manage downloaded files

---

## Phase 5: Library & Playlists

### Step 5.1: Library Screen
- List all tracks (local + saved URLs)
- Sort by: title, artist, date added
- Filter/search within library

### Step 5.2: Playlist Management
- Create new playlist
- Add tracks to playlist
- Remove tracks from playlist
- Rename/delete playlists
- Reorder tracks in playlist

### Step 5.3: Data Persistence
- Save playlists to AsyncStorage
- Save library metadata
- Remember last playing track & position

---

## Phase 6: Now Playing Screen (Full Player)

### Step 6.1: UI Components
- Large album art (or placeholder)
- Song title & artist
- Progress bar with timestamps
- Playback controls (previous, play/pause, next)
- Shuffle & repeat toggles
- Queue button

### Step 6.2: Animations
- Smooth transitions when opening/closing
- Album art animation (subtle pulse or rotation)
- Progress bar animations

---

## Phase 7: Polish & Settings

### Step 7.1: Settings Screen
- Theme toggle (light/dark/system)
- Default playback mode
- Audio quality preferences
- Clear cache/downloads

### Step 7.2: Error Handling
- Handle failed URL loads gracefully
- Offline mode detection
- File not found handling

### Step 7.3: App Icon & Splash Screen
- Design vinyl-themed icon
- Custom splash screen

---

## Build Order (Recommended)

1. **Setup** - Project init, dependencies, folder structure
2. **Navigation** - Tabs + basic screens
3. **Theme** - Light/dark mode working
4. **Audio Core** - Basic playback from hardcoded track
5. **Player UI** - Now Playing screen + Mini Player
6. **Local Files** - Pick and play local audio
7. **URL Playback** - Paste and play URLs
8. **Queue** - Queue management UI
9. **Playlists** - Create, edit, save playlists
10. **Polish** - Settings, error handling, icons

---

## Files to Create

| File | Purpose |
|------|---------|
| `App.tsx` | Entry point, providers |
| `src/navigation/TabNavigator.tsx` | Bottom tab setup |
| `src/navigation/RootNavigator.tsx` | Stack + tabs |
| `src/screens/LibraryScreen.tsx` | Library tab |
| `src/screens/SearchScreen.tsx` | Search/add URLs tab |
| `src/screens/NowPlayingScreen.tsx` | Full player |
| `src/screens/SettingsScreen.tsx` | Settings |
| `src/components/MiniPlayer.tsx` | Bottom mini player |
| `src/components/TrackList.tsx` | Reusable track list |
| `src/components/PlayerControls.tsx` | Play/pause/skip buttons |
| `src/components/ProgressBar.tsx` | Seek bar |
| `src/store/playerStore.ts` | Zustand audio state |
| `src/store/libraryStore.ts` | Zustand library/playlists |
| `src/theme/colors.ts` | Color definitions |
| `src/theme/ThemeContext.tsx` | Theme provider |
| `src/hooks/usePlayer.ts` | Player hook |
| `src/utils/audioService.ts` | Track player setup |
| `src/utils/fileUtils.ts` | File picking helpers |
| `src/types/index.ts` | TypeScript types |

---

## Testing Strategy

- **Android:** Test on physical device via Expo Go
- **iOS:** Test on physical device via Expo Go
- **Development builds:** For features requiring native code (track-player)

Note: react-native-track-player requires a development build, not just Expo Go. We'll set this up in Phase 1.
