Update CLAUDE.md to include player system details and enhance testing coverage information

CLAUDE.md

@@ -27,11 +27,11 @@ This is a soundboard application with a FastAPI backend and React frontend.
 - **Framework**: FastAPI with SQLModel for database ORM
 - **Database**: SQLite with aiosqlite async driver
 - **Authentication**: JWT tokens with OAuth2 support (Google, GitHub)
-- **Dependencies**: FastAPI, SQLModel, aiosqlite, bcrypt, PyJWT, pydantic-settings, uvicorn, ffmpeg-python, yt-dlp
+- **Dependencies**: FastAPI, SQLModel, aiosqlite, bcrypt, PyJWT, pydantic-settings, uvicorn, ffmpeg-python, yt-dlp, python-vlc
 - **Structure**:
-  - `app/api/v1/`: API endpoints for v1 (auth.py, main.py, sounds.py, socket.py)
+  - `app/api/v1/`: API endpoints for v1 (auth.py, main.py, sounds.py, socket.py, player.py)
   - `app/models/`: Database models (User, Sound, Playlist, Extraction, Plan, UserOAuth, CreditTransaction, SoundPlayed, etc.)
-  - `app/services/`: Business logic layer (auth.py, oauth.py, socket.py, sound_scanner.py, sound_normalizer.py, extraction.py, extraction_processor.py, credit.py)
+  - `app/services/`: Business logic layer (auth.py, oauth.py, socket.py, player.py, sound_scanner.py, sound_normalizer.py, extraction.py, extraction_processor.py, credit.py)
   - `app/repositories/`: Data access layer (base.py, user.py, user_oauth.py, sound.py, extraction.py, credit_transaction.py, playlist.py)
   - `app/schemas/`: Pydantic schemas for API requests/responses (auth.py)
   - `app/core/`: Configuration, database setup, logging, dependencies, seeds
@@ -88,7 +88,7 @@ This is a soundboard application with a FastAPI backend and React frontend.
 - Frontend uses TypeScript 5.8+ with strict mode enabled
 - Comprehensive linting: Ruff (backend), ESLint (frontend)
 - Type checking: mypy (backend), TypeScript (frontend)
-- Testing: pytest with asyncio support and coverage reporting (76+ repository tests)
+- Testing: pytest with asyncio support and coverage reporting (90+ comprehensive tests including repository, service, and integration tests)
 - Logs stored in `backend/logs/app.log` with rotation
 - Audio files stored in `backend/sounds/` directory structure (originals, normalized, extracted)
 - Database file at `backend/data/soundboard.db`
@@ -151,6 +151,73 @@ Enhanced sound management with comprehensive duplicate prevention and integrity
 - **API Integration**: Sound creation, update, deletion with duplicate prevention
 - **Testing**: 15 comprehensive tests covering all sound operations including constraint validation
 
+## Player System
+
+Comprehensive audio player service with VLC backend for playlist management and audio playback.
+
+### Player Features
+- **VLC Integration**: Uses VLC media player as the backend for reliable audio playback
+- **Playlist Management**: Dynamic playlist loading and reloading with state persistence
+- **Intelligent Track Handling**: Smart playlist reload logic with track position tracking
+- **Multiple Playback Modes**: Continuous, loop, loop-one, random, and single play modes
+- **Play Count Tracking**: Automatic play count updates with 20% threshold detection
+- **Real-time Position Tracking**: Background thread for position updates and auto-advance
+- **WebSocket Broadcasting**: Real-time state updates via WebSocket connections
+- **Credit Integration**: Automatic credit deduction for VLC-based sound plays
+
+### Playlist Reload Logic
+- **ID-based Comparison**: Compares playlist IDs to determine reload behavior
+- **Playlist Change Handling**: When playlist ID changes, stops player and resets to first track
+- **Track Position Tracking**: When same playlist, tracks if current song moved to different index
+- **Missing Track Handling**: When current track removed, stops player and sets first available track
+- **Empty Playlist Support**: Graceful handling of empty playlists with state clearing
+- **State Consistency**: Ensures player state remains consistent across all reload scenarios
+
+### Player State Management
+- **Status Tracking**: Playing, paused, stopped states with proper transitions
+- **Sound Information**: Current track ID, index, position, duration tracking
+- **Playlist Metadata**: Playlist ID, name, length, total duration, and sound list
+- **Volume Control**: Volume management with range validation (0-100)
+- **Position Tracking**: Real-time playback position with seek functionality
+
+### Database Integration
+- **Play History**: Records `SoundPlayed` entries for player-based plays (no user association)
+- **Sound Statistics**: Updates sound play counts automatically when 20% threshold reached
+- **Playlist Synchronization**: Syncs with database playlist changes via reload mechanism
+- **Session Management**: Proper async database session handling with connection cleanup
+
+### Technical Implementation
+- **Service**: `app/services/player.py` - Core player logic with VLC integration
+- **State Management**: PlayerState class for comprehensive state tracking
+- **Background Threading**: Position tracking thread for non-blocking operations
+- **Async Operations**: Full async/await support for database operations
+- **Error Handling**: Comprehensive error handling with graceful degradation
+- **Memory Management**: Proper cleanup of resources and background tasks
+
+### Player Modes
+- **Continuous**: Plays through playlist once then stops
+- **Loop**: Repeats entire playlist indefinitely
+- **Loop One**: Repeats current track indefinitely
+- **Random**: Plays tracks in random order
+- **Single**: Plays current track once then stops
+
+### API Integration
+- **REST Endpoints**: Player control via HTTP API (`app/api/v1/player.py`)
+- **WebSocket Events**: Real-time state broadcasting to connected clients
+- **Authentication**: Supports both authenticated and unauthenticated playback
+- **Global Service**: Singleton player service accessible throughout the application
+
+### Testing Coverage
+- **49 comprehensive tests** covering all player functionality including:
+  - State management and serialization
+  - Playback control (play, pause, stop, seek)
+  - Playlist reload scenarios with ID changes
+  - Track position tracking and updates
+  - Helper method validation
+  - Mode switching and volume control
+  - Play count tracking and credit integration
+  - Error handling and edge cases
+
 ## Repository Pattern & Testing
 
 Comprehensive repository pattern implementation with full test coverage for data access layer.
@@ -422,7 +489,7 @@ backend/sounds/originals/extracted/thumbnails/  # Extracted thumbnails
 - **Full mypy Compliance**: Complete type checking across all Python code
 - **Async/Await Patterns**: Proper async programming throughout the stack
 - **Error Handling**: Comprehensive exception handling with detailed logging
-- **Test Coverage**: 76+ repository tests with 100% critical path coverage
+- **Test Coverage**: 90+ comprehensive tests with 100% critical path coverage including repository, service, and integration tests
 
 ### Performance Optimizations
 - **Lazy Loading Management**: Proper SQLAlchemy relationship loading