diff --git a/README.md b/README.md index f71c2067..d109a12c 100644 --- a/README.md +++ b/README.md @@ -1,120 +1,75 @@ -
- -
-
Swing Music
+# 🎵 SwingMusic Extended Backend -
v2.1.0
- -**
[Download](https://swingmx.com/downloads) • [Get Android Client](https://github.com/swingmx/android) • Sponsor Us ❤️ • [Docs](https://swingmx.com/guide/introduction.html) • [Screenshots](https://swingmx.com) • [r/SwingMusicApp](https://www.reddit.com/r/SwingMusicApp)
** +A powerful, self-hosted music streaming backend with comprehensive features and modern architecture. -## +## ✨ Features -[![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) +### 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 +- **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 -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. +### 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 -## Features +## 🚀 Quick Start -- **Daily Mixes** - curated everyday based on your listening activity -- **Metadata normalization** - a clean and consistent library -- **Album versioning** - normalized albums and association with version labels (eg. Deluxe, Remaster, etc) -- **Related artist and albums** -- **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** +### Prerequisites +- Python 3.11+ +- FFmpeg (for audio processing) +- libev (Linux/macOS) ### Installation -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. +```bash +# Clone the repository +git clone https://github.com/Dvorinka/swingmusic-extended.git +cd swingmusic-extended -[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. +# Install dependencies +uv sync -On Linux, you can install FFmpeg using: - -```sh -sudo apt-get install ffmpeg libev-dev libavcodec-extra -y +# Start the server +uv run python run.py ``` -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. +### Docker Setup ```bash -chmod a+x ./swingmusic +# Pull the image +docker pull ghcr.io/Dvorinka/swingmusic-extended:latest -./swingmusic -``` - -The app should start at 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 \ +# Run with Docker +docker run --name swingmusic \ + -p 1970:1970 \ -v /path/to/music:/music \ -v /path/to/config:/config \ --restart unless-stopped \ - ghcr.io/swingmx/swingmusic:latest + ghcr.io/Dvorinka/swingmusic-extended:latest ``` -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. - -> [!TIP] -> For more info, see the [Docker section](https://swingmusic.vercel.app/guide/getting-started.html#docker) on the docs. - -#### Using Docker Compose - -Here's a sample Docker compose file: +### Docker Compose ```yaml services: swingmusic: - image: ghcr.io/swingmx/swingmusic:latest + image: ghcr.io/Dvorinka/swingmusic-extended:latest container_name: swingmusic volumes: - /path/to/music:/music @@ -124,122 +79,163 @@ services: restart: unless-stopped ``` -### Contributing and Development +## 📖 Documentation -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. +- **API Documentation**: Available at `/api/docs` when running +- **Configuration Guide**: See `docs/` directory +- **Development Setup**: See contributing guidelines -[**CONTRIBUTING GUIDELINES**](.github/contributing.md). +## 🔧 Configuration -> [!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. +The application starts on `http://localhost:1970` by default. -To set up this project on your computer follow the following steps: +Default credentials: +- Username: `admin` +- Password: `admin` -```sh -# 1. Fork the project +> ⚠️ **Important**: Change the default password after first login. -git clone https://github.com/swingmx/swingmusic.git +### Environment Variables +- `PORT` - Server port (default: 1970) +- `HOST` - Server host (default: 0.0.0.0) +- `DEBUG` - Enable debug mode (default: false) -# or via SSH +## 🛠️ Development -git clone git@github.com:swingmx/swingmusic.git +### Setup Development Environment + +```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 ``` -```sh -# 2. Install dependencies +### Running Tests -uv sync +```bash +# 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 ``` -> [!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 -> ``` +## 📊 Architecture -```sh -# 4. Run the program +### Backend Services +- **Flask/FastAPI** - Web framework and API server +- **SQLAlchemy** - Database ORM and migrations +- **Redis** - Caching and session management +- **Celery** - Background task processing +- **FFmpeg** - Audio processing and transcoding -uv run python run.py +### Database +- **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 ``` -### License +## 🔌 API Endpoints -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. +### Authentication +- `POST /api/auth/login` - User authentication +- `POST /api/auth/logout` - User logout +- `GET /api/auth/profile` - User profile -### Contributors +### Music Library +- `GET /api/tracks` - List tracks +- `GET /api/albums` - List albums +- `GET /api/artists` - List artists +- `GET /api/search` - Search library -Shout out to the following code contributors who have helped maintain and improve Swing Music: +### Enhanced Features +- `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 -
- - - - - - - - - - - - - -
- - -
- @cwilvx - - 		- - -
- @Ericgacoki - - 		- - -
- @Simonh2o - - 		- - -
- @tcsenpai - - 		- - -
- @jensgrunzer1 - - 		- - -
- @Type-Delta - - 		- - -
- @MarcOrfilaCarreras - -
- - -
- @tralph3 - -
-
+## 🐳 Deployment + +### Production Deployment + +1. **Environment Setup** + ```bash + export PORT=1970 + export DATABASE_URL=postgresql://user:pass@localhost/swingmusic + export REDIS_URL=redis://localhost:6379 + ``` + +2. **Database Migration** + ```bash + uv run flask db upgrade + ``` + +3. **Start Application** + ```bash + uv run gunicorn -w 4 -b 0.0.0.0:1970 "swingmusic:create_app()" + ``` + +### Systemd Service + +```ini +[Unit] +Description=SwingMusic +After=network.target + +[Service] +Type=simple +User=swingmusic +WorkingDirectory=/opt/swingmusic +ExecStart=/opt/swingmusic/venv/bin/python run.py +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +## 🤝 Contributing + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +### Development Guidelines +- Follow PEP 8 for Python code +- Write tests for new features +- Update documentation +- Use meaningful commit messages + +## 📄 License + +This project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) file for details. + +## 🔗 Links + +- **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) + +--- + +**Built with ❤️ for the music community**