swingmusic-extended/README.md

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

For CasaOS custom-app deployment, use:

• 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