diff --git a/README.md b/README.md index 2ad66e9d..f71c2067 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,120 @@ -# 🎵 Swing Music Extended +
+ +
+
Swing Music
-A powerful, self-hosted music streaming backend with comprehensive features and modern architecture. +
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)
** -## ✨ Features +## -### 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 +[![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) -### 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 +## -### 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 +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. -## 📦 Client Applications +## Features -This repository includes client applications as submodules: +- **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** -### 📱 Mobile App -**[swingmusic-android](./swingmusic-android)** - Android mobile application -- Modern Android app with Material Design 3 -- Offline music support -- Cross-platform music streaming +### Installation -### 🖥️ Desktop App -**[swingmusic-desktop](./swingmusic-desktop)** - Cross-platform desktop application -- Built with Tauri (Rust + Web) -- Native performance with web UI -- Windows, macOS, and Linux support +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. -### 🌐 Web Client -**[swingmusic-webclient](./swingmusic-webclient)** - Web-based client application -- Modern web interface -- Browser-based music streaming -- Responsive design +[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. -## 🚀 Quick Start +On Linux, you can install FFmpeg using: -### Backend Setup - -```bash -# Clone the repository -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 +```sh +sudo apt-get install ffmpeg libev-dev libavcodec-extra -y ``` -### 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 -# Pull the image -docker pull ghcr.io/Dvorinka/swingmusic-extended:latest +chmod a+x ./swingmusic -# Run with Docker -docker run --name swingmusic \ - -p 1970:1970 \ +./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 \ -v /path/to/music:/music \ -v /path/to/config:/config \ --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 -# Navigate to specific client -cd swingmusic-android # or swingmusic-desktop or swingmusic-webclient +> [!TIP] +> For more info, see the [Docker section](https://swingmusic.vercel.app/guide/getting-started.html#docker) on the docs. -# Follow client-specific setup instructions in each README -``` +#### Using Docker Compose -### Docker Compose +Here's a sample Docker compose file: ```yaml services: swingmusic: - image: ghcr.io/Dvorinka/swingmusic-extended:latest + image: ghcr.io/swingmx/swingmusic:latest container_name: swingmusic volumes: - /path/to/music:/music @@ -105,163 +124,122 @@ services: restart: unless-stopped ``` -## 📖 Documentation +### Contributing and Development -- **API Documentation**: Available at `/api/docs` when running -- **Configuration Guide**: See `docs/` directory -- **Development Setup**: See contributing guidelines +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 +[**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: -- Username: `admin` -- Password: `admin` +To set up this project on your computer follow the following steps: -> ⚠️ **Important**: Change the default password after first login. +```sh +# 1. Fork the project -### Environment Variables -- `PORT` - Server port (default: 1970) -- `HOST` - Server host (default: 0.0.0.0) -- `DEBUG` - Enable debug mode (default: false) +git clone https://github.com/swingmx/swingmusic.git -## 🛠️ Development +# or via SSH -### 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 +git clone git@github.com:swingmx/swingmusic.git ``` -### Running Tests +```sh +# 2. Install dependencies -```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 +uv sync ``` -## 📊 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 -- **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 +```sh +# 4. Run the program -### 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 +uv run python run.py ``` -## 🔌 API Endpoints +### License -### Authentication -- `POST /api/auth/login` - User authentication -- `POST /api/auth/logout` - User logout -- `GET /api/auth/profile` - User profile +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. -### Music Library -- `GET /api/tracks` - List tracks -- `GET /api/albums` - List albums -- `GET /api/artists` - List artists -- `GET /api/search` - Search library +### Contributors -### 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 +Shout out to the following code contributors who have helped maintain and improve Swing Music: -## 🐳 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** +
+ + + + + + + + + + + + + +
+ + +
+ @cwilvx + + 		+ + +
+ @Ericgacoki + + 		+ + +
+ @Simonh2o + + 		+ + +
+ @tcsenpai + + 		+ + +
+ @jensgrunzer1 + + 		+ + +
+ @Type-Delta + + 		+ + +
+ @MarcOrfilaCarreras + +
+ + +
+ @tralph3 + +
+