SwingMusic Extended
v2.1.4
**
[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) • Sponsor Us ❤️
** ## [![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**