musicard-py 1.0.0

🎵 Generate beautiful music card images in Python with multiple themes. 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

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

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

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:

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

📚 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

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ in Python