mirror of
https://github.com/Dvorinka/swingmusic-extended.git
synced 2026-06-05 13:03:02 +00:00
Update README with stylized format and improved styling
This commit is contained in:
Tomas Dvorak
@@ -1,101 +1,120 @@
|
|||||||
# 🎵 Swing Music Extended
|
<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>Swing Music</b></div>
|
||||||
|
|
||||||
A powerful, self-hosted music streaming backend with comprehensive features and modern architecture.
|
<div align="center"><b><sub><code>v2.1.0</code></sub></b></div>
|
||||||
|
|
||||||
## ✨ Features
|
**<div align="center" style="padding-top: 1.25rem">[Download](https://swingmx.com/downloads) • [Get Android Client](https://github.com/swingmx/android) • <a href="https://github.com/sponsors/swingmx" target="_blank">Sponsor Us ❤️</a> • [Docs](https://swingmx.com/guide/introduction.html) • [Screenshots](https://swingmx.com) • [r/SwingMusicApp](https://www.reddit.com/r/SwingMusicApp)</div>**
|
||||||
|
|
||||||
### Core Functionality
|
##
|
||||||
- **Multi-format Audio Support** - MP3, FLAC, OGG, WAV, and more
|
|
||||||
- **Smart Metadata Management** - Automatic tagging and normalization
|
|
||||||
- **Advanced Search** - Full-text search across tracks, albums, and artists
|
|
||||||
- **Playlist Management** - Create, edit, and organize playlists
|
|
||||||
- **User Management** - Multi-user support with authentication
|
|
||||||
- **Folder Browsing** - Navigate your music library by directory structure
|
|
||||||
|
|
||||||
### Enhanced Features
|
[](https://raw.githubusercontent.com/swing-opensource/swingmusic/master/.github/images/artist.webp)
|
||||||
- **Spotify Integration** - Import playlists and metadata from Spotify
|
|
||||||
- **Universal Downloader** - Download from multiple streaming services
|
|
||||||
- **Audio Quality Dashboard** - Monitor and control audio quality settings
|
|
||||||
- **Mobile Offline Support** - Sync music for offline listening
|
|
||||||
- **Music Catalog Browser** - Advanced library exploration
|
|
||||||
- **Recap Features** - Year-end listening statistics and insights
|
|
||||||
- **Real-time Updates** - Track system changes and updates
|
|
||||||
|
|
||||||
### API & Services
|
##
|
||||||
- **RESTful API** - Complete REST API for all features
|
|
||||||
- **WebSocket Support** - Real-time updates and notifications
|
|
||||||
- **Advanced Analytics** - Comprehensive listening statistics
|
|
||||||
- **Lyrics Integration** - Fetch and display lyrics
|
|
||||||
- **Last.fm Scrobbling** - Automatic scrobbling support
|
|
||||||
|
|
||||||
## 📦 Client Applications
|
Swing Music is a fast and beautiful, self-hosted music player for your local audio files. Like a cooler Spotify ... but bring your own music. Just run the app and enjoy your music library in a web browser.
|
||||||
|
|
||||||
This repository includes client applications as submodules:
|
## Features
|
||||||
|
|
||||||
### 📱 Mobile App
|
- **Daily Mixes** - curated everyday based on your listening activity
|
||||||
**[swingmusic-android](./swingmusic-android)** - Android mobile application
|
- **Metadata normalization** - a clean and consistent library
|
||||||
- Modern Android app with Material Design 3
|
- **Album versioning** - normalized albums and association with version labels (eg. Deluxe, Remaster, etc)
|
||||||
- Offline music support
|
- **Related artist and albums**
|
||||||
- Cross-platform music streaming
|
- **Folder view** - Browse your music library by folders
|
||||||
|
- **Playlist management**
|
||||||
|
- **Beautiful browser based UI**
|
||||||
|
- **Silence detection** - Combine cross-fade with silence detection to create a seamless listening experience
|
||||||
|
- **Collections** - Group albums and artists based on your preferences
|
||||||
|
- **Statistics** - Get insights into your listening activity
|
||||||
|
- **Lyrics view**
|
||||||
|
- **Android client**
|
||||||
|
- **Last.fm scrobbling**
|
||||||
|
- **Multi-user support**
|
||||||
|
- **Cross-platform** - Windows, Linux, MacOS (coming soon), arm64, x86
|
||||||
|
- **Blazingly fast**
|
||||||
|
- **Pure awesomeness**
|
||||||
|
|
||||||
### 🖥️ Desktop App
|
### Installation
|
||||||
**[swingmusic-desktop](./swingmusic-desktop)** - Cross-platform desktop application
|
|
||||||
- Built with Tauri (Rust + Web)
|
|
||||||
- Native performance with web UI
|
|
||||||
- Windows, macOS, and Linux support
|
|
||||||
|
|
||||||
### 🌐 Web Client
|
Swing Music is available as pre-compiled binaries for Windows and Linux. Just download the latest release from the [downloads page](https://swingmusic.vercel.app/downloads) and launch it.
|
||||||
**[swingmusic-webclient](./swingmusic-webclient)** - Web-based client application
|
|
||||||
- Modern web interface
|
|
||||||
- Browser-based music streaming
|
|
||||||
- Responsive design
|
|
||||||
|
|
||||||
## 🚀 Quick Start
|
[FFmpeg](https://ffmpeg.org/) is needed for the audio silence skip feature, so you need to install it first. On windows, you can follows [this tutorial](https://phoenixnap.com/kb/ffmpeg-windows) to install FFmpeg.
|
||||||
|
|
||||||
### Backend Setup
|
On Linux, you can install FFmpeg using:
|
||||||
|
|
||||||
```bash
|
```sh
|
||||||
# Clone the repository
|
sudo apt-get install ffmpeg libev-dev libavcodec-extra -y
|
||||||
git clone --recurse-submodules https://github.com/Dvorinka/swingmusic-extended.git
|
|
||||||
cd swingmusic-extended
|
|
||||||
|
|
||||||
# Install dependencies
|
|
||||||
uv sync
|
|
||||||
|
|
||||||
# Start the server
|
|
||||||
uv run python run.py
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Docker Setup
|
The `libev` package is needed on Linux and MacOS. You can install it on other system as shown:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# Arch Linux
|
||||||
|
pacman -S libev
|
||||||
|
|
||||||
|
# Fedora, CentOS
|
||||||
|
dnf install libev-devel
|
||||||
|
|
||||||
|
# MacOS
|
||||||
|
brew install libev
|
||||||
|
```
|
||||||
|
|
||||||
|
Then make the file executable first.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Pull the image
|
chmod a+x ./swingmusic
|
||||||
docker pull ghcr.io/Dvorinka/swingmusic-extended:latest
|
|
||||||
|
|
||||||
# Run with Docker
|
./swingmusic
|
||||||
docker run --name swingmusic \
|
```
|
||||||
-p 1970:1970 \
|
|
||||||
|
The app should start at <http://localhost:1970> by default. Open it in your browser to configure and use Swing Music. You can change the default port by using the `--port` flag.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./swingmusic --port 1980
|
||||||
|
```
|
||||||
|
|
||||||
|
> [!IMPORTANT]
|
||||||
|
> The default password for user `admin` is "admin". Please change the password via the settings after first login.
|
||||||
|
|
||||||
|
To stream your music from your Android device, you can download the [Android mobile client](https://github.com/swingmx/android).
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
Options flags can be passed when starting the app in the terminal to tweak runtime settings or perform tasks. You can use the `-h` flag to see all supported options.
|
||||||
|
|
||||||
|
> [!TIP]
|
||||||
|
> You can read more about options in [the docs](https://swingmusic.vercel.app/guide/getting-started.html#options).
|
||||||
|
|
||||||
|
### Docker
|
||||||
|
|
||||||
|
Pull the latest Docker image and run it:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
docker pull ghcr.io/swingmx/swingmusic:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
```sh
|
||||||
|
docker run --name swingmusic -p 1970:1970 \
|
||||||
-v /path/to/music:/music \
|
-v /path/to/music:/music \
|
||||||
-v /path/to/config:/config \
|
-v /path/to/config:/config \
|
||||||
--restart unless-stopped \
|
--restart unless-stopped \
|
||||||
ghcr.io/Dvorinka/swingmusic-extended:latest
|
ghcr.io/swingmx/swingmusic:latest
|
||||||
```
|
```
|
||||||
|
|
||||||
### Client Applications
|
Don't forget to replace `/path/to/music` and `/path/to/config` with the appropriate values. In addition, specify the the `/music` directory as the root directory. Using the `Home Directory` option won't work.
|
||||||
|
|
||||||
```bash
|
> [!TIP]
|
||||||
# Navigate to specific client
|
> For more info, see the [Docker section](https://swingmusic.vercel.app/guide/getting-started.html#docker) on the docs.
|
||||||
cd swingmusic-android # or swingmusic-desktop or swingmusic-webclient
|
|
||||||
|
|
||||||
# Follow client-specific setup instructions in each README
|
#### Using Docker Compose
|
||||||
```
|
|
||||||
|
|
||||||
### Docker Compose
|
Here's a sample Docker compose file:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
services:
|
services:
|
||||||
swingmusic:
|
swingmusic:
|
||||||
image: ghcr.io/Dvorinka/swingmusic-extended:latest
|
image: ghcr.io/swingmx/swingmusic:latest
|
||||||
container_name: swingmusic
|
container_name: swingmusic
|
||||||
volumes:
|
volumes:
|
||||||
- /path/to/music:/music
|
- /path/to/music:/music
|
||||||
@@ -105,163 +124,122 @@ services:
|
|||||||
restart: unless-stopped
|
restart: unless-stopped
|
||||||
```
|
```
|
||||||
|
|
||||||
## 📖 Documentation
|
### Contributing and Development
|
||||||
|
|
||||||
- **API Documentation**: Available at `/api/docs` when running
|
Swing Music is looking for contributors. If you're interested, please join us at the [Swing Music Community](https://t.me/+9n61PFcgKhozZDE0) group on Telegram. For more information, take a look at https://github.com/swing-opensource/swingmusic/issues/186.
|
||||||
- **Configuration Guide**: See `docs/` directory
|
|
||||||
- **Development Setup**: See contributing guidelines
|
|
||||||
|
|
||||||
## 🔧 Configuration
|
[**CONTRIBUTING GUIDELINES**](.github/contributing.md).
|
||||||
|
|
||||||
The application starts on `http://localhost:1970` by default.
|
> [!TIP]
|
||||||
|
> This project runs on Python 3.11 or newer and uses [uv](https://docs.astral.sh/uv) to manage dependencies. Please [install uv](https://docs.astral.sh/uv/getting-started/installation/) before continuing for an easy setup.
|
||||||
|
|
||||||
Default credentials:
|
To set up this project on your computer follow the following steps:
|
||||||
- Username: `admin`
|
|
||||||
- Password: `admin`
|
|
||||||
|
|
||||||
> ⚠️ **Important**: Change the default password after first login.
|
```sh
|
||||||
|
# 1. Fork the project
|
||||||
|
|
||||||
### Environment Variables
|
git clone https://github.com/swingmx/swingmusic.git
|
||||||
- `PORT` - Server port (default: 1970)
|
|
||||||
- `HOST` - Server host (default: 0.0.0.0)
|
|
||||||
- `DEBUG` - Enable debug mode (default: false)
|
|
||||||
|
|
||||||
## 🛠️ Development
|
# or via SSH
|
||||||
|
|
||||||
### Setup Development Environment
|
git clone git@github.com:swingmx/swingmusic.git
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone and setup
|
|
||||||
git clone https://github.com/Dvorinka/swingmusic-extended.git
|
|
||||||
cd swingmusic-extended
|
|
||||||
|
|
||||||
# Install development dependencies
|
|
||||||
uv sync --dev
|
|
||||||
|
|
||||||
# Run in development mode
|
|
||||||
uv run python run.py --debug
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Running Tests
|
```sh
|
||||||
|
# 2. Install dependencies
|
||||||
|
|
||||||
```bash
|
uv sync
|
||||||
# Run all tests
|
|
||||||
uv run pytest
|
|
||||||
|
|
||||||
# Run with coverage
|
|
||||||
uv run pytest --cov=src
|
|
||||||
|
|
||||||
# Run specific test file
|
|
||||||
uv run pytest tests/test_api.py
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 📊 Architecture
|
> [!TIP]
|
||||||
|
> The `libev` package is needed on Linux and MacOS. You can install it on other system as shown:
|
||||||
|
>
|
||||||
|
> ```sh
|
||||||
|
> # Arch Linux
|
||||||
|
> pacman -S libev
|
||||||
|
>
|
||||||
|
> # Fedora, CentOS
|
||||||
|
> dnf install libev-devel
|
||||||
|
>
|
||||||
|
> # MacOS
|
||||||
|
> brew install libev
|
||||||
|
> ```
|
||||||
|
|
||||||
### Backend Services
|
```sh
|
||||||
- **Flask/FastAPI** - Web framework and API server
|
# 4. Run the program
|
||||||
- **SQLAlchemy** - Database ORM and migrations
|
|
||||||
- **Redis** - Caching and session management
|
|
||||||
- **Celery** - Background task processing
|
|
||||||
- **FFmpeg** - Audio processing and transcoding
|
|
||||||
|
|
||||||
### Database
|
uv run python run.py
|
||||||
- **SQLite** (default) - Single-user deployments
|
|
||||||
- **PostgreSQL** (recommended) - Multi-user production
|
|
||||||
- **MySQL** - Alternative production database
|
|
||||||
|
|
||||||
### File Structure
|
|
||||||
```
|
|
||||||
src/swingmusic/
|
|
||||||
├── api/ # API endpoints and routes
|
|
||||||
├── db/ # Database models and migrations
|
|
||||||
├── services/ # Business logic and services
|
|
||||||
├── utils/ # Utility functions
|
|
||||||
├── migrations/ # Database migration files
|
|
||||||
└── logs/ # Application logs
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🔌 API Endpoints
|
### License
|
||||||
|
|
||||||
### Authentication
|
This software is provided to you with terms stated in the [AGPLv3 License](https://github.com/swingmx/swingmusic/blob/master/LICENSE) or any later version. Read the full text in the `LICENSE` file located at the root of this repository.
|
||||||
- `POST /api/auth/login` - User authentication
|
|
||||||
- `POST /api/auth/logout` - User logout
|
|
||||||
- `GET /api/auth/profile` - User profile
|
|
||||||
|
|
||||||
### Music Library
|
### Contributors
|
||||||
- `GET /api/tracks` - List tracks
|
|
||||||
- `GET /api/albums` - List albums
|
|
||||||
- `GET /api/artists` - List artists
|
|
||||||
- `GET /api/search` - Search library
|
|
||||||
|
|
||||||
### Enhanced Features
|
Shout out to the following code contributors who have helped maintain and improve Swing Music:
|
||||||
- `GET /api/spotify/search` - Spotify search
|
|
||||||
- `POST /api/download/universal` - Universal downloader
|
|
||||||
- `GET /api/analytics/dashboard` - Analytics data
|
|
||||||
- `GET /api/lyrics/{track_id}` - Track lyrics
|
|
||||||
|
|
||||||
## 🐳 Deployment
|
<div align="left">
|
||||||
|
<table>
|
||||||
### Production Deployment
|
<tr>
|
||||||
|
<td align="center">
|
||||||
1. **Environment Setup**
|
<a href="https://github.com/cwilvx">
|
||||||
```bash
|
<img src="https://github.com/cwilvx.png" width="80px;"/>
|
||||||
export PORT=1970
|
<br />
|
||||||
export DATABASE_URL=postgresql://user:pass@localhost/swingmusic
|
<sub><b>@cwilvx</b></sub>
|
||||||
export REDIS_URL=redis://localhost:6379
|
</a>
|
||||||
```
|
</td>
|
||||||
|
<td align="center">
|
||||||
2. **Database Migration**
|
<a href="https://github.com/Ericgacoki">
|
||||||
```bash
|
<img src="https://github.com/Ericgacoki.png" width="80px;" alt=""/>
|
||||||
uv run flask db upgrade
|
<br />
|
||||||
```
|
<sub><b>@Ericgacoki</b></sub>
|
||||||
|
</a>
|
||||||
3. **Start Application**
|
</td>
|
||||||
```bash
|
<td align="center">
|
||||||
uv run gunicorn -w 4 -b 0.0.0.0:1970 "swingmusic:create_app()"
|
<a href="https://github.com/Simonh2o">
|
||||||
```
|
<img src="https://github.com/Simonh2o.png" width="80px;"/>
|
||||||
|
<br />
|
||||||
### Systemd Service
|
<sub><b>@Simonh2o</b></sub>
|
||||||
|
</a>
|
||||||
```ini
|
</td>
|
||||||
[Unit]
|
<td align="center">
|
||||||
Description=SwingMusic
|
<a href="https://github.com/tcsenpai">
|
||||||
After=network.target
|
<img src="https://github.com/tcsenpai.png" width="80px;"/>
|
||||||
|
<br />
|
||||||
[Service]
|
<sub><b>@tcsenpai</b></sub>
|
||||||
Type=simple
|
</a>
|
||||||
User=swingmusic
|
</td>
|
||||||
WorkingDirectory=/opt/swingmusic
|
<td align="center">
|
||||||
ExecStart=/opt/swingmusic/venv/bin/python run.py
|
<a href="https://github.com/jensgrunzer1">
|
||||||
Restart=always
|
<img src="https://github.com/jensgrunzer1.png" width="80px;"/>
|
||||||
|
<br />
|
||||||
[Install]
|
<sub><b>@jensgrunzer1</b></sub>
|
||||||
WantedBy=multi-user.target
|
</a>
|
||||||
```
|
</td>
|
||||||
|
<td align="center">
|
||||||
## 🤝 Contributing
|
<a href="https://github.com/Type-Delta">
|
||||||
|
<img src="https://github.com/Type-Delta.png" width="80px;" alt=""/>
|
||||||
1. Fork the repository
|
<br />
|
||||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
<sub><b>@Type-Delta</b></sub>
|
||||||
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
</a>
|
||||||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
</td>
|
||||||
5. Open a Pull Request
|
<td align="center">
|
||||||
|
<a href="https://github.com/MarcOrfilaCarreras">
|
||||||
### Development Guidelines
|
<img src="https://github.com/MarcOrfilaCarreras.png" width="80px;" alt=""/>
|
||||||
- Follow PEP 8 for Python code
|
<br />
|
||||||
- Write tests for new features
|
<sub><b>@MarcOrfilaCarreras</b></sub>
|
||||||
- Update documentation
|
</a>
|
||||||
- Use meaningful commit messages
|
</td>
|
||||||
|
</tr>
|
||||||
## 📄 License
|
<tr>
|
||||||
|
<td align="center">
|
||||||
This project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) file for details.
|
<a href="https://github.com/tralph3">
|
||||||
|
<img src="https://github.com/tralph3.png" width="80px;" alt=""/>
|
||||||
## 🔗 Links
|
<br />
|
||||||
|
<sub><b>@tralph3</b></sub>
|
||||||
- **Web Client**: [swingmusic-extended-webclient](https://github.com/Dvorinka/swingmusic-extended-webclient)
|
</a>
|
||||||
- **Desktop App**: [swingmusic-extended-desktop](https://github.com/Dvorinka/swingmusic-extended-desktop)
|
</td>
|
||||||
- **Android App**: [swingmusic-extended-android](https://github.com/Dvorinka/swingmusic-extended-android)
|
</tr>
|
||||||
|
</table>
|
||||||
---
|
</div>
|
||||||
|
|
||||||
**Built with ❤️ for the music community**
|
|
||||||
|
|||||||
Reference in New Issue
Block a user