swingmusic-extended/README.md

🎵 SwingMusic Extended Backend

A powerful, self-hosted music streaming backend with comprehensive features and modern architecture.

✨ 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

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

🚀 Quick Start

Prerequisites

• Python 3.11+
• FFmpeg (for audio processing)
• libev (Linux/macOS)

Installation

# Clone the repository
git clone https://github.com/Dvorinka/swingmusic-extended.git
cd swingmusic-extended

# Install dependencies
uv sync

# Start the server
uv run python run.py

Docker Setup

# Pull the image
docker pull ghcr.io/Dvorinka/swingmusic-extended:latest

# 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/Dvorinka/swingmusic-extended:latest

Docker Compose

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

📖 Documentation

• API Documentation: Available at /api/docs when running
• Configuration Guide: See docs/ directory
• Development Setup: See contributing guidelines

🔧 Configuration

The application starts on http://localhost:1970 by default.

Default credentials:

• Username: admin
• Password: admin

⚠️ Important: Change the default password after first login.

Environment Variables

• PORT - Server port (default: 1970)
• HOST - Server host (default: 0.0.0.0)
• DEBUG - Enable debug mode (default: false)

🛠️ Development

Setup Development Environment

# 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

# 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

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

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

🔌 API Endpoints

Authentication

• POST /api/auth/login - User authentication
• POST /api/auth/logout - User logout
• GET /api/auth/profile - User profile

Music Library

• GET /api/tracks - List tracks
• GET /api/albums - List albums
• GET /api/artists - List artists
• GET /api/search - Search library

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

🐳 Deployment

Production Deployment

1. Environment Setup

   export PORT=1970
   export DATABASE_URL=postgresql://user:pass@localhost/swingmusic
   export REDIS_URL=redis://localhost:6379
   

2. Database Migration

   uv run flask db upgrade
   

3. Start Application

   uv run gunicorn -w 4 -b 0.0.0.0:1970 "swingmusic:create_app()"
   

Systemd Service

[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 file for details.

🔗 Links

• Web Client: swingmusic-extended-webclient
• Desktop App: swingmusic-extended-desktop
• Android App: swingmusic-extended-android

---

Built with ❤️ for the music community