SwingMusic Extended

_v2.1.4

Web Client • Desktop App • Android App • Mobile App • Sponsor Us ❤️

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

• 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

• 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

• 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

• 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:

git clone https://github.com/Dvorinka/swingmusic-extended.git
cd swingmusic-extended

2. Install dependencies:

# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

3. Install system dependencies:

FFmpeg (required for audio processing):

# 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:

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
• Desktop App: See swingmusic-extended-desktop
• Android App: See swingmusic-extended-android
• Flutter Mobile: See swingmusic-mobile

🔧 Configuration

Server Options

# 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

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

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.

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
• CASAOS_DEPLOYMENT.md

🛠️ Development

Backend Development

# 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

# 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 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
• Desktop App: Submit PRs to swingmusic-extended-desktop
• Android App: Submit PRs to swingmusic-extended-android
• Flutter Mobile: Submit PRs to swingmusic-mobile

📄 License

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

🔗 Links

• Main Repository: swingmusic-extended
• Web Client: swingmusic-extended-webclient
• Desktop App: swingmusic-extended-desktop
• Android App: swingmusic-extended-android
• Flutter Mobile: swingmusic-mobile

🙏 Acknowledgments

Based on the original SwingMusic by swingmx, extended with additional platforms and features.

---

Built with ❤️ by the SwingMusic Extended community