Metadata-Version: 2.4
Name: musicard-py
Version: 2.1.2
Summary: 🎵 Generate stunning music card images in Python with multiple themes, SVG export, and advanced customization. Inspired by unburn/musicard.
Author-email: Ramkrishna <ramkrishna@code-xon.fun>
Maintainer-email: Ramkrishna <ramkrishna@code-xon.fun>
License: MIT
Project-URL: Homepage, https://github.com/code-xon/musicard-py
Project-URL: Repository, https://github.com/code-xon/musicard-py
Project-URL: Documentation, https://github.com/code-xon/musicard-py#readme
Project-URL: Issues, https://github.com/code-xon/musicard-py/issues
Project-URL: Source, https://github.com/code-xon/musicard-py
Project-URL: Tracker, https://github.com/code-xon/musicard-py/issues
Keywords: music,card,image,generator,pillow,discord,bot,canvas,svg,themes,customization
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=10.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: cairosvg>=2.7.0
Requires-Dist: diskcache>=5.6.0
Dynamic: license-file

# 🎵 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**

## Table of Contents

- [Credits](#credits)
- [Quick Start](#-quick-start)
- [Features](#-features)
- [Themes](#-themes)
- [Customization](#-customization)
- [Examples](#-examples)
- [API Reference](#-api-reference)
- [Requirements](#python-compatibility)
- [Testing](#testing)
- [Building](#building-the-package)
- [Contributing](#-contributing)
- [License](#-license)

## 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 Musicard

card = Musicard()

image = card.generate_card(
    title="Bohemian Rhapsody",
    artist="Queen",
    progress=75,
    theme="classic"
)

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

## ✨ Features

- 🎨 **Multiple Themes**: Classic, Classic Pro, Dynamic, Mini, and Upcoming designs
- 🖼️ **Image Support**: Load thumbnails and backgrounds from URLs or local files
- 📊 **Progress Bars**: Visual progress indicators with customizable styles
- 🎯 **Easy API**: Simple class-based interface with async support
- 🔧 **Customizable**: Colors, sizes, fonts, and theme-specific options
- 📦 **Lightweight**: Minimal dependencies (Pillow + requests + cairosvg + diskcache)
- ⚡ **Fast**: Generate images in milliseconds with intelligent caching
- 🖥️ **CLI Tool**: Command-line interface for quick generation and batch processing
- 🎨 **SVG Export**: Export cards as scalable vector graphics
- 📦 **Batch Processing**: Generate multiple cards simultaneously
- 💾 **Caching System**: Automatic caching of images, fonts, and generated cards
- 🎭 **Theme Presets**: Save and load custom theme configurations
- 🎨 **Advanced Features**: Rounded corners, gradients, shadows, blur effects

```python
from musicard import Musicard

# Create a music card instance
card = Musicard()

# Generate a music card
image = card.generate_card(
    title="Song Title",
    artist="Artist Name",
    thumbnail="https://example.com/thumbnail.jpg",  # or local path
    progress=50,  # 0-100
    theme="classic",
    backgroundColor="#070707",
    progressColor="#FF7A00"
)

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

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

# Async generation
import asyncio

async def generate_async():
    image = await card.async_generate_card(
        title="Song Title",
        artist="Artist Name",
        progress=75
    )
    return image
```

## 🎨 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
- Time display (start/end times)
- Perfect for traditional music apps

### Classic Pro Theme
> Enhanced classic design with improved visuals

- Rounded thumbnail corners
- Enhanced progress bar with glow effects
- Better typography and spacing
- Improved shadows and visual effects

### Dynamic Theme
> Contemporary design with background image support

- Custom background images with darkness control
- Gradient overlays
- Blurred backgrounds for text readability
- Modern typography with shadows

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

### Upcoming Theme
> Futuristic design with circular visualization

- Center-positioned thumbnail
- Concentric circles with fade effects
- Track index visualization
- Modern circular layout

## 🎨 Customization

### Custom Colors

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

![Example Music Card](output_classic.jpeg)

### 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")
```

## 🚀 New Features in v2.1.0

### SVG Export
Export your music cards as scalable vector graphics:

```python
card = Musicard()
image = card.generate_card("Song", "Artist")
card.export_svg(image, {"title": "Song", "artist": "Artist"}, "card.svg")
```

### Batch Processing
Generate multiple cards at once:

```python
configs = [
    {"title": "Song 1", "artist": "Artist 1", "theme": "classic"},
    {"title": "Song 2", "artist": "Artist 2", "theme": "mini"},
]
images = card.batch_generate(configs, "output")
```

### Intelligent Caching
Automatic caching improves performance:

```python
# View cache stats
stats = card.get_cache_stats()
print(f"Cache hits: {stats['main_cache']['hits']}")

# Clear cache if needed
card.clear_cache()
```

### Theme Presets
Save and reuse theme configurations:

```python
# Save preset
preset = {
    "theme": "classic",
    "backgroundColor": "#070707",
    "progressColor": "#FF7A00"
}
card.save_theme_preset(preset, "my_theme.json")

# Load preset
config = card.load_theme_preset("my_theme.json")
image = card.generate_card("Song", "Artist", **config)
```

## 📚 API Reference

### Musicard

#### Constructor Parameters

- `width: int` - Default image width in pixels (default: 1200)
- `height: int` - Default image height in pixels (default: 400)

#### Methods

- `generate_card(title, artist, thumbnail=None, progress=0, theme='classic', **kwargs) -> PIL.Image.Image` - Generate and return the music card image
- `async_generate_card(title, artist, thumbnail=None, progress=0, theme='classic', **kwargs) -> PIL.Image.Image` - Asynchronous version
- `batch_generate(configs, output_dir='output') -> List[PIL.Image.Image]` - Generate multiple cards in batch
- `async_batch_generate(configs, output_dir='output') -> List[PIL.Image.Image]` - Asynchronous batch generation
- `export_svg(image, data, path)` - Export card as SVG file
- `to_bytes(image, format='PNG') -> bytes` - Convert image to bytes
- `save(image, path, format=None)` - Save image to file
- `get_available_themes() -> List[str]` - Get list of available themes
- `load_template(name) -> BaseTheme` - Load a built-in template
- `load_theme_preset(preset_path) -> Dict[str, Any]` - Load theme preset from JSON
- `save_theme_preset(config, preset_path)` - Save theme configuration as preset
- `get_cache_stats() -> Dict[str, Any]` - Get cache statistics
- `clear_cache()` - Clear all caches

#### Parameters

- `title: str` - Song title (required)
- `artist: str` - Artist name (required)
- `thumbnail: Optional[str|bytes]` - Image URL, local path, or bytes
- `progress: float` - Progress value between 0 and 100 (default: 0)
- `theme: str` - Theme name: 'classic', 'classic_pro', 'dynamic', 'mini', 'upcoming'
- `**kwargs` - Theme-specific options (backgroundColor, progressColor, etc.)

### CLI Usage

```bash
# Generate from command line
musicard generate --title "Song" --artist "Artist" --theme classic --output card.png

# Generate SVG
musicard generate --title "Song" --artist "Artist" --format svg --output card.svg

# Generate from JSON config
musicard generate --config song.json --output card.png

# Batch generate from JSON array
musicard batch --input cards.json --output-dir ./output

# List available themes
musicard themes

# Clear cache
musicard cache clear
```

## Requirements

- Python 3.8+
- Pillow >= 10.0.0
- requests >= 2.25.0

## Testing

Run the test suite with pytest:

```bash
pip install pytest
pytest
```

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

### Development Setup

```bash
git clone https://github.com/code-xon/musicard-py.git
cd musicard-py
pip install -e .
pip install pytest  # for testing
```

## 📄 License

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

---

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