musicard-py 2.1.0

🎵 Generate stunning music card images in Python with multiple themes, SVG export, and advanced customization. Inspired by unburn/musicard.

🎵 musicard-py

Generate stunning music card images in Python with ease! Inspired by unburn/musicard by Unburn.

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

Table of Contents

• Credits
• Quick Start
• Features
• Themes
• Customization
• Examples
• API Reference
• Requirements
• Testing
• Building
• Contributing
• License

Credits

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

🚀 Quick Start

pip install musicard-py

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

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

card.save("my_music_card.png")

Custom Themes

Create your own theme by extending BaseTheme:

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

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

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:

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:

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:

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

# 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

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

pip install pytest
pytest

Building the package

python -m build

Uploading to TestPyPI

twine upload --repository testpypi dist/*

Uploading to PyPI

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

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

---

Made with ❤️ in Python