# 🎵 Music Player

A modern PySide2 music player with folder-based playlist support.

## Features

- **Modern Interface**: Clean, intuitive GUI with Material Design aesthetics
- **Folder-Based Playlists**: Easily add entire folders of music to your playlist
- **Multiple Audio Formats**: Support for MP3, WAV, FLAC, OGG, and M4A files
- **Metadata Display**: Shows song titles, artists, and album information
- **Playback Controls**: Play, pause, stop, and volume control
- **Progress Tracking**: Visual progress bar with time display
- **Persistent Configuration**: Remembers your settings and window position
- **Light/Dark Themes**: Choose your preferred visual theme
- **Recent Folders**: Quick access to recently used music directories

## Installation

```bash
# Install dependencies
pip install PySide2 playsound mutagen

# Or install as part of pytola project
pip install -e .
```

## Usage

### Running the Applications

```bash
# Command-line interface (core functionality)
musicplayer

# Graphical interface (full GUI)
musicplayer-gui

# Or from Python
python -m pytola.musicplayer          # Core CLI
python -m pytola.musicplayer_gui      # GUI version
```

### Basic Operations

1. **Adding Music**: Click "📁 Add Folder" or use Ctrl+O to browse and select a music folder
2. **Playing Music**: Double-click any song in the playlist or click the Play button
3. **Controlling Playback**: Use the playback buttons (Play/Pause/Stop)
4. **Adjusting Volume**: Use the volume slider to control audio levels
5. **Tracking Progress**: Drag the progress slider to jump to different parts of the song

## Project Structure

```
musicplayer/
├── musicplayer.py          # Core functionality and CLI interface
├── musicplayer_gui.py      # Graphical user interface
├── audio_player.py         # Audio playback core logic
├── playlist_manager.py     # Playlist and file management
├── config_manager.py       # Configuration persistence
├── style_manager.py        # Theme and styling management
├── styles/                 # QSS style sheet files
│   ├── __init__.py
├── tests/                  # Unit tests
│   ├── test_audio_player.py
│   ├── test_playlist_manager.py
│   └── test_config_manager.py
├── __init__.py
├── pyproject.toml          # Project configuration
└── README.md               # This file
```

## Technical Details

### Architecture

The music player follows a clean separation of concerns:

**Core Layer** (`musicplayer.py`):
- **MusicPlayerCore**: Unified interface for all playback functionality
- **AudioPlayer**: Handles audio playback operations using playsound
- **PlaylistManager**: Manages playlists and scans folders for audio files
- **ConfigManager**: Persists user settings and preferences

**Presentation Layer** (`musicplayer_gui.py`):
- **MusicPlayerGUI**: Main GUI window with Material Design interface
- **TranslationManager**: Multi-language UI support
- **StyleManager**: Manages application themes and styling

### Dependencies

- **PySide2**: GUI framework for the user interface
- **playsound**: Simple audio playback functionality
- **mutagen**: Audio file metadata extraction

### Supported Formats

- MP3 (.mp3)
- WAV (.wav)
- FLAC (.flac)
- OGG (.ogg)
- M4A (.m4a)

## Development

### Running Tests

```bash
# Run all tests
pytest pytola/musicplayer/tests/

# Run specific test file
pytest pytola/musicplayer/tests/test_audio_player.py

# Run with coverage
pytest --cov=pytola.musicplayer pytola/musicplayer/tests/
```

### Code Style

This project follows the pytola coding standards:

- English-only comments and documentation
- Type hints for all function signatures
- Dataclasses for configuration objects
- Cached properties for computed values
- Functions limited to 60 lines maximum

## Configuration

The application stores user preferences in:

```
~/.pytola/musicplayer.json
```

Configuration includes:
- Window position and size
- Volume settings
- Theme preferences
- Recent folders and playlists
- Playback settings

## Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Follow the coding standards
4. Add tests for new functionality
5. Submit a pull request

## License

This project is part of the pytola project and follows the same licensing terms.

## Acknowledgments

- PySide2 community for the excellent GUI framework
- pygame developers for robust audio handling
- mutagen contributors for metadata parsing
