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

```bash
# 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

```bash
# 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

```yaml
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

```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

```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
```

## 📊 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**
   ```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**