Rewrite README with clean, professional documentation

- Updated with comprehensive feature descriptions - Added modern installation and setup instructions - Included detailed project structure and architecture - Added troubleshooting and development guidelines - Standardized format across all repositories - Removed unnecessary content and outdated information
2026-06-03 20:13:02 +00:00 · 2026-03-17 18:05:53 +01:00
parent 4338dd1d9c
commit af366e3899
1 changed files with 185 additions and 189 deletions
@@ -1,120 +1,75 @@
-<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>
+# 🎵 SwingMusic Extended Backend

-<div align="center"><b><sub><code>v2.1.0</code></sub></b></div>
- 
-**<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>**
+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 <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 \
+# 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

-<div align="left">
-  <table>
-    <tr>
-      <td align="center">
-        <a href="https://github.com/cwilvx">
-          <img src="https://github.com/cwilvx.png" width="80px;"/>
-          <br />
-          <sub><b>@cwilvx</b></sub>
-        </a>
-      </td>
-      <td align="center">
-        <a href="https://github.com/Ericgacoki">
-          <img src="https://github.com/Ericgacoki.png" width="80px;" alt=""/>
-          <br />
-          <sub><b>@Ericgacoki</b></sub>
-        </a>
-      </td>
-      <td align="center">
-        <a href="https://github.com/Simonh2o">
-          <img src="https://github.com/Simonh2o.png" width="80px;"/>
-          <br />
-          <sub><b>@Simonh2o</b></sub>
-        </a>
-      </td>
-      <td align="center">
-        <a href="https://github.com/tcsenpai">
-          <img src="https://github.com/tcsenpai.png" width="80px;"/>
-          <br />
-          <sub><b>@tcsenpai</b></sub>
-        </a>
-      </td>
-      <td align="center">
-        <a href="https://github.com/jensgrunzer1">
-          <img src="https://github.com/jensgrunzer1.png" width="80px;"/>
-          <br />
-          <sub><b>@jensgrunzer1</b></sub>
-        </a>
-      </td>
-      <td align="center">
-        <a href="https://github.com/Type-Delta">
-          <img src="https://github.com/Type-Delta.png" width="80px;" alt=""/>
-          <br />
-          <sub><b>@Type-Delta</b></sub>
-        </a>
-      </td>
-     <td align="center">
-        <a href="https://github.com/MarcOrfilaCarreras">
-          <img src="https://github.com/MarcOrfilaCarreras.png" width="80px;" alt=""/>
-          <br />
-          <sub><b>@MarcOrfilaCarreras</b></sub>
-        </a>
-      </td>
-    </tr>
-    <tr>
-    <td align="center">
-      <a href="https://github.com/tralph3">
-        <img src="https://github.com/tralph3.png" width="80px;" alt=""/>
-        <br />
-          <sub><b>@tralph3</b></sub>
-        </a>
-      </td>
-    </tr>
-  </table>
-</div>
+## 🐳 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**