TDvorak/swingmusic-extended
1
0
Fork 0
mirror of https://github.com/Dvorinka/swingmusic-extended.git synced 2026-06-03 20:13:02 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
Files
d515971c8b467835cc0604339070c03407a352c1
swingmusic-extended/README.md
T

261 lines
9.2 KiB
Markdown
Raw Blame History

<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**
Reference in New Issue View Git Blame Copy Permalink