<div align="center" style="display: flex; justify-content: center; align-items: center;">
  <img class="lo" src='https://github.com/swingmx/swingmusic/raw/master/.github/images/logo-fill.light.svg' style="height: 4rem">
</div>
<div align="center" style="font-size: 2rem"><b>SwingMusic Extended</b></div>

<div align="center"><b><sub><code>v2.1.4</code></sub></b></div>
 
**<div align="center" style="padding-top: 1.25rem">[Web Client](https://github.com/Dvorinka/swingmusic-extended-webclient) • [Desktop App](https://github.com/Dvorinka/swingmusic-extended-desktop) • [Android App](https://github.com/Dvorinka/swingmusic-extended-android) • [Mobile App](https://github.com/Dvorinka/swingmusic-mobile) • <a href="https://github.com/sponsors/Dvorinka" target="_blank">Sponsor Us ❤️</a></div>**

##

[![Image showing the Swing Music artist page](https://raw.githubusercontent.com/swingmx/swingmusic/master/.github/images/artist.webp)](https://raw.githubusercontent.com/swing-opensource/swingmusic/master/.github/images/artist.webp)

##

SwingMusic Extended is a comprehensive, multi-platform music player ecosystem for your local audio files. Like a cooler Spotify ... but bring your own music. This monorepo contains the backend server and orchestrates all client applications.

## 🚀 Platform Overview

### 🌐 **Web Client** - [swingmusic-extended-webclient](https://github.com/Dvorinka/swingmusic-extended-webclient)
- **Status**: ✅ Fully Implemented
- **Technology**: Vue 3, TypeScript, Vite, Tailwind CSS
- **Features**: Progressive Web App, Spotify integration, universal downloader, audio quality controls
- **Installation**: `yarn install && yarn dev`

### 🖥️ **Desktop App** - [swingmusic-extended-desktop](https://github.com/Dvorinka/swingmusic-extended-desktop)
- **Status**: ✅ Fully Implemented
- **Technology**: Tauri, Rust, Vue.js
- **Features**: Native performance, system tray integration, global hotkeys, file associations
- **Installation**: `npm install && npm run dev`

### 📱 **Android App** - [swingmusic-extended-android](https://github.com/Dvorinka/swingmusic-extended-android)
- **Status**: ✅ Fully Implemented
- **Technology**: Kotlin, Jetpack Compose, Android SDK
- **Features**: Material Design 3, offline mode, analytics, background playback
- **Installation**: `./gradlew assembleDebug`

### 📲 **Flutter Mobile App** - [swingmusic-mobile](https://github.com/Dvorinka/swingmusic-mobile)
- **Status**: 🔄 In Development
- **Technology**: Flutter, Dart
- **Features**: Cross-platform mobile (iOS/Android), unified UI with web client
- **Installation**: `flutter pub get && flutter run`

## 🎯 Core Features

### Backend Server (This Repository)
- **Multi-Platform Support** - Serves all client applications
- **Advanced Audio Processing** - Cross-fade, silence detection, gapless playback
- **Metadata Management** - Automatic normalization and organization
- **Multi-User Support** - Individual user profiles and preferences
- **API Integration** - RESTful API with WebSocket support
- **Real-Time Sync** - Synchronizes across all platforms

### Universal Features Across All Platforms
- **Daily Mixes** - Curated playlists based on listening activity
- **Advanced Search** - Full-text search with filters and suggestions
- **Playlist Management** - Create, edit, and organize playlists
- **Folder View** - Browse music by directory structure
- **Statistics & Analytics** - Comprehensive listening insights
- **Lyrics Display** - Real-time lyrics synchronization
- **Last.fm Integration** - Automatic scrobbling
- **Theme Support** - Light/dark modes with system awareness

## 🏗️ Project Structure

```
SwingMusic Extended/
├── src/                          # Backend server (Python/FastAPI)
├── swingmusic-webclient/          # Vue.js web application
├── swingmusic-desktop/            # Tauri desktop application
├── swingmusic-android/            # Android native application
├── swingmusic_mobile/             # Flutter cross-platform mobile
├── services/                     # Additional services and scripts
└── docs/                         # Documentation
```

## 🚀 Quick Start

### Prerequisites
- **Python** 3.11+ for backend
- **Node.js** 19+ for web client development
- **Flutter** 3.0+ for mobile app
- **Android Studio** for Android development
- **Rust** 1.70+ for desktop development

### Backend Installation

1. **Clone this repository**:
```bash
git clone https://github.com/Dvorinka/swingmusic-extended.git
cd swingmusic-extended
```

2. **Install dependencies**:
```bash
# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt
```

3. **Install system dependencies**:

**FFmpeg** (required for audio processing):
```bash
# Ubuntu/Debian
sudo apt-get install ffmpeg libev-dev libavcodec-extra -y

# macOS
brew install ffmpeg libev

# Windows
# Download from https://ffmpeg.org/
```

4. **Run the server**:
```bash
uv run python run.py
```

The server will start at `http://localhost:1970` by default.

### Client Applications

Each client application has its own repository with detailed setup instructions:

- **Web Client**: See [swingmusic-extended-webclient](https://github.com/Dvorinka/swingmusic-extended-webclient)
- **Desktop App**: See [swingmusic-extended-desktop](https://github.com/Dvorinka/swingmusic-extended-desktop)
- **Android App**: See [swingmusic-extended-android](https://github.com/Dvorinka/swingmusic-extended-android)
- **Flutter Mobile**: See [swingmusic-mobile](https://github.com/Dvorinka/swingmusic-mobile)

## 🔧 Configuration

### Server Options
```bash
# Change port
uv run python run.py --port 1980

# Enable debug mode
uv run python run.py --debug

# Set music directory
uv run python run.py --music-dir /path/to/music

# All options
uv run python run.py --help
```

### Environment Variables
- `SWINGMUSIC_PORT` - Server port (default: 1970)
- `SWINGMUSIC_MUSIC_DIR` - Music library path
- `SWINGMUSIC_CONFIG_DIR` - Configuration directory
- `SWINGMUSIC_LOG_LEVEL` - Logging level

## 🐳 Docker Deployment

### Using Docker Compose
```yaml
services:
  swingmusic:
    image: ghcr.io/Dvorinka/swingmusic-extended:latest
    container_name: swingmusic
    volumes:
      - /path/to/music:/music
      - /path/to/config:/config
    ports:
      - "1970:1970"
    restart: unless-stopped
    environment:
      - SWINGMUSIC_PORT=1970
```

### Manual Docker
```bash
docker pull ghcr.io/Dvorinka/swingmusic-extended:latest

docker run --name swingmusic -p 1970:1970 \
  -v /path/to/music:/music \
  -v /path/to/config:/config \
  --restart unless-stopped \
  ghcr.io/Dvorinka/swingmusic-extended:latest
```

## 🛠️ Development

### Backend Development
```bash
# Install development dependencies
uv sync --dev

# Run with hot reload
uv run python run.py --reload

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src
```

### Updating Submodules
```bash
# Update all submodules
git submodule update --remote --merge

# Update specific submodule
git submodule update --remote swingmusic-webclient

# Initialize after cloning
git submodule update --init --recursive
```

## 📊 Platform Implementation Status

| Platform | Status | Features | Last Updated |
|----------|--------|----------|-------------|
| **Backend** | ✅ Complete | Full API, multi-user, real-time sync | Active |
| **Web Client** | ✅ Complete | PWA, Spotify integration, downloader | Active |
| **Desktop App** | ✅ Complete | Native performance, system integration | Active |
| **Android App** | ✅ Complete | Material Design 3, offline mode | Active |
| **Flutter Mobile** | 🔄 In Development | Cross-platform iOS/Android | In Progress |

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](.github/CONTRIBUTING.md) for details.

### Development Workflow
1. Fork this repository
2. Create a feature branch
3. Make your changes
4. Test across all platforms
5. Submit a pull request

### Platform-Specific Contributions
- **Backend**: Submit PRs to this repository
- **Web Client**: Submit PRs to [swingmusic-extended-webclient](https://github.com/Dvorinka/swingmusic-extended-webclient)
- **Desktop App**: Submit PRs to [swingmusic-extended-desktop](https://github.com/Dvorinka/swingmusic-extended-desktop)
- **Android App**: Submit PRs to [swingmusic-extended-android](https://github.com/Dvorinka/swingmusic-extended-android)
- **Flutter Mobile**: Submit PRs to [swingmusic-mobile](https://github.com/Dvorinka/swingmusic-mobile)

## 📄 License

This project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- **Main Repository**: [swingmusic-extended](https://github.com/Dvorinka/swingmusic-extended)
- **Web Client**: [swingmusic-extended-webclient](https://github.com/Dvorinka/swingmusic-extended-webclient)
- **Desktop App**: [swingmusic-extended-desktop](https://github.com/Dvorinka/swingmusic-extended-desktop)
- **Android App**: [swingmusic-extended-android](https://github.com/Dvorinka/swingmusic-extended-android)
- **Flutter Mobile**: [swingmusic-mobile](https://github.com/Dvorinka/swingmusic-mobile)

## 🙏 Acknowledgments

Based on the original [SwingMusic](https://github.com/swingmx/swingmusic) by swingmx, extended with additional platforms and features.

---

**Built with ❤️ by the SwingMusic Extended community**
