# 🎵 musicard-py

[![PyPI version](https://badge.fury.io/py/musicard-py.svg)](https://pypi.org/project/musicard-py/)
[![Python versions](https://img.shields.io/pypi/pyversions/musicard-py.svg)](https://pypi.org/project/musicard-py/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Generate stunning music card images in Python with ease! Inspired by [unburn/musicard](https://github.com/unburn/musicard) by Unburn.

✨ **Beautiful Themes** • 🚀 **Easy to Use** • 🎨 **Customizable** • 📦 **PyPI Ready**

## Credits

This package is inspired by the JavaScript project **musicard**, created by **Unburn**.
Original source: [https://github.com/unburn/musicard](https://github.com/unburn/musicard)

## 🚀 Quick Start

```bash
pip install musicard-py
```

```python
from musicard import MusicCard

card = MusicCard(
    title="Bohemian Rhapsody",
    artist="Queen",
    progress=0.75,
    theme="classic"
)

card.save("my_music_card.png")
```

## ✨ Features

- 🎨 **Multiple Themes**: Classic, Modern, and Mini designs
- 🖼️ **Image Support**: Load thumbnails from URLs or local files
- 📊 **Progress Bars**: Visual progress indicators with customizable styles
- 🎯 **Easy API**: Simple class-based interface
- 🔧 **Customizable**: Colors, sizes, and theme-specific options
- 📦 **Lightweight**: Minimal dependencies (Pillow + requests)
- ⚡ **Fast**: Generate images in milliseconds

```python
from musicard import MusicCard

# Create a music card
card = MusicCard(
    title="Song Title",
    artist="Artist Name",
    thumbnail="https://example.com/thumbnail.jpg",  # or local path
    progress=0.5,  # 0.0 to 1.0
    theme="classic",
    background_color="#070707",
    progress_color="#FF7A00"
)

# Generate PIL Image
image = card.generate()

# Save to file
card.save("music_card.png")

# Get PNG bytes
png_bytes = card.to_bytes()
```

## 🎨 Themes

### Classic Theme
> Dark, elegant design with thumbnail on the right

- Square thumbnail positioning
- Horizontal progress bar with circle indicator
- Clean typography with bold title
- Perfect for traditional music apps

### Modern Theme
> Contemporary gradient design with smooth aesthetics

- Gradient background
- Rounded progress bar elements
- Modern typography
- Great for modern applications

### Mini Theme
> Compact design for small spaces

- Thumbnail on the left
- Vertical menu bar
- Bottom progress bar
- Pause indicator support
- Ideal for mobile or compact UIs

## 🎨 Customization

### Custom Colors

```python
card = MusicCard(
    title="Song Title",
    artist="Artist Name",
    progress=0.6,
    theme="classic",
    background_color="#1a1a1a",
    progress_color="#00ff88",
    name_color="#ffffff"
)
```

### Custom Themes

Create your own theme by extending `BaseTheme`:

```python
from musicard.themes.base_theme import BaseTheme
from PIL import Image, ImageDraw

class MyCustomTheme(BaseTheme):
    def render(self, image, draw, metadata):
        # Your custom rendering logic
        title = metadata['title']
        # Draw your theme...
        pass
```

## 📖 Examples

### Discord Bot Integration

```python
import discord
from musicard import MusicCard

@bot.command()
async def nowplaying(ctx, title, artist, progress=0.5):
    card = MusicCard(title, artist, progress=progress, theme="modern")
    image_bytes = card.to_bytes()

    await ctx.send(file=discord.File(io.BytesIO(image_bytes), "nowplaying.png"))
```

### Batch Generation

```python
songs = [
    ("Song 1", "Artist 1", 0.3),
    ("Song 2", "Artist 2", 0.7),
    ("Song 3", "Artist 3", 0.9),
]

for title, artist, progress in songs:
    card = MusicCard(title, artist, progress=progress, theme="mini")
    card.save(f"{title.replace(' ', '_')}.png")
```

## 📚 API Reference

### MusicCard

- `title: str` - Song title
- `artist: str` - Artist name
- `thumbnail: str` - Image URL or path
- `progress: float` - Progress (0.0-1.0)
- `width: int` - Image width
- `height: int` - Image height
- `theme: str` - Theme name ('classic', 'modern', or 'mini')

Methods:
- `generate() -> PIL.Image` - Generate the image
- `to_bytes() -> bytes` - Get PNG bytes
- `save(path: str)` - Save to file

## Python Compatibility

- Python 3.8+

## Dependencies

- Pillow
- requests

## Building the package

```bash
python -m build
```

## Uploading to TestPyPI

```bash
twine upload --repository testpypi dist/*
```

## Uploading to PyPI

```bash
twine upload dist/*
```

## 🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your 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

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

<p align="center">Made with ❤️ in Python</p>