swingmusic-extended/README.md

<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
```

### CasaOS

Use this CasaOS custom-app compose.  
It runs both the main backend API and the bundled webclient from the same `swingmusic` container image.

```yaml
name: swingmusic
services:
  swingmusic:
    cpu_shares: 90
    command: []
    container_name: swingmusic
    deploy:
      resources:
        limits:
          memory: 10000M
    hostname: swingmusic
    image: ghcr.io/dvorinka/swingmusic-extended:latest
    labels:
      icon: https://cdn.jsdelivr.net/gh/IceWhaleTech/CasaOS-AppStore@main/Apps/SwingMusic/icon.png
    ports:
      - mode: ingress
        target: 1970
        published: "1970"
        protocol: tcp
    restart: unless-stopped
    volumes:
      - type: bind
        source: /DATA/AppData/swingmusic/config
        target: /config
      - type: bind
        source: /DATA/Media/Music
        target: /music
    devices: []
    cap_add: []
    environment:
      - SWINGMUSIC_CLIENT_DIR=/app/client
      - SWINGMUSIC_PORT=1970
    networks:
      - default
    privileged: false
networks:
  default:
    name: swingmusic_default
x-casaos:
  architectures:
    - amd64
  author: SwingMX
  category: Media
  description:
    en_US: >
      Swing Music is a fast, beautiful, self-hosted music player designed for
      your local audio files, offering a sleek experience akin to Spotify but
      powered by your own music library. Simply run the app and access your
      music collection effortlessly through a web browser.


      Swing Music curates Daily Mixes based on your listening habits, ensures a clean and consistent library with metadata normalization, and supports album versioning (e.g., Deluxe, Remaster) alongside related artist and album recommendations. Browse your music library via folder view, manage playlists, and enjoy a seamless listening experience with silence detection and cross-fade. Additional features include listening statistics, lyrics view, Last.fm scrobbling, multi-user support, and personalized collections for grouping albums and artists.


      With its stunning browser-based interface and robust functionality, Swing Music is the perfect choice for music enthusiasts seeking a beautiful and practical way to manage and enjoy their local music collection.
  developer: SwingMX
  hostname: ""
  icon: https://cdn.jsdelivr.net/gh/IceWhaleTech/CasaOS-AppStore@main/Apps/SwingMusic/icon.png
  index: /
  is_uncontrolled: false
  main: swingmusic
  port_map: "1970"
  scheme: http
  store_app_id: swingmusic
  tagline:
    en_US: Swing Music is a beautifully designed, self-hosted music streaming
      server. Like a cooler Spotify ... but bring your own music.
  thumbnail: https://cdn.jsdelivr.net/gh/IceWhaleTech/CasaOS-AppStore@main/Apps/SwingMusic/thumbnail.png
  tips:
    before_install:
      en_US: >
        When you first start Swing Music, it will ask you to pick music
        directory: Where do you want to look for music?

        select "Specific directories" Option, and select "/music" and rescan.


        Default Account

        | Name | Password |

        | -------- | -------- |

        | `admin` | `admin` |
  title:
    custom: ""
    en_us: Swing Music
```

Quick references:

- [`docker-compose.casaos.yml`](/home/tdvorak/Desktop/PROG+HTML/SwingMusic/docker-compose.casaos.yml)
- [`CASAOS_DEPLOYMENT.md`](/home/tdvorak/Desktop/PROG+HTML/SwingMusic/CASAOS_DEPLOYMENT.md)

## 🛠️ 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**