Skip to content

code-xon/musicard-py

BranchesTags

Repository files navigation

🎵 Musicard Py

PyPI version Python versions License: MIT Downloads

Generate stunning, professional music card images in Python with advanced customization and automation features.

🎨 Beautiful Themes • 🏷️ Song Logos • 🎯 Easy API • 🚀 High Performance • 🤖 Automation • 📦 PyPI Ready

📖 Documentation • 📦 Install • 🚀 Quick Start

✨ What's New in v2.2.0

🎵 Song Logo Display System - Render official song/artist logos with custom positioning, blend modes, and effects 🎨 Advanced Visual Effects - Background blur, gradients, shadows, glassmorphism, and color filters 🚀 8K Export & Performance - Ultra HD export with 30-40% speed improvements 🤖 Automation & Metadata - Auto metadata loading, EXIF embedding, watermark system 🖥️ Enhanced CLI - Interactive mode, live preview, profiles, batch queues

📋 Table of Contents

🚀 Quick Start

Installation

pip install musicard-py

Basic Usage

from musicard import Musicard

# Create a music card instance
card = Musicard()

# Generate a stunning music card
image = card.generate_card(
    title="Bohemian Rhapsody",
    artist="Queen",
    progress=75,
    theme="classic"
)

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

⚡ Performance

Musicard Py is optimized for speed and efficiency:

  • 30-40% faster rendering compared to previous versions
  • Intelligent caching system for images, fonts, and generated cards
  • Parallel batch processing for multiple card generation
  • Ultra HD 8K export support with progressive rendering
  • Memory optimization with smart cache invalidation
  • Cross-platform performance on Windows, Linux, and macOS

Benchmarks

  • Standard card generation: ~50-100ms
  • 8K export: ~200-500ms
  • Batch processing: ~10-20 cards/second (parallel)
  • Memory usage: ~50-100MB per instance

🎨 Themes

Choose from 5 professionally designed themes, each optimized for different use cases:

🎯 Classic

Traditional, elegant design perfect for music applications

  • Right-aligned square thumbnail
  • Horizontal progress bar with animated circle indicator
  • Clean, bold typography with time display
  • Dark theme optimized for readability
  • Best for: Traditional music players, desktop apps
image = card.generate_card("Song Title", "Artist", theme="classic")

✨ Classic Pro

Enhanced classic with premium visual effects

  • Rounded thumbnail corners with subtle shadows
  • Glowing progress bar with enhanced animations
  • Improved typography spacing and hierarchy
  • Multi-layer shadows and visual depth
  • Best for: Premium music apps, social media
image = card.generate_card("Song Title", "Artist", theme="classic_pro")

🌟 Dynamic

Modern design with background image support

  • Full background image with darkness overlay control
  • Radial gradients and blur effects
  • Contemporary typography with soft shadows
  • Adaptive text contrast for any background
  • Best for: Modern streaming apps, creative projects
image = card.generate_card(
    "Song Title", "Artist",
    theme="dynamic",
    backgroundImage="album_art.jpg",
    imageDarkness=60
)

📱 Mini

Compact design optimized for mobile and small spaces

  • Left-aligned thumbnail with vertical menu bar
  • Bottom progress bar for space efficiency
  • Pause/play indicator support
  • Minimalist typography for small screens
  • Best for: Mobile apps, notifications, widgets
image = card.generate_card("Song Title", "Artist", theme="mini", paused=True)

🔮 Upcoming

Futuristic design with circular visualization

  • Center-positioned thumbnail with circular mask
  • Concentric circles with fade effects
  • Track index visualization
  • Modern circular layout with depth
  • Best for: Experimental designs, futuristic themes
image = card.generate_card("Song Title", "Artist", theme="upcoming")

🏷️ Song Logo System

Render official song and artist logos directly on your music cards with professional-grade customization.

Quick Setup

from musicard import Musicard

card = Musicard()

# Basic logo setup
card.set_song_logo("queen_logo.png")  # Local file or URL
card.set_logo_position(100, 50)       # Position on card
card.set_logo_opacity(0.8)            # Transparency level

# Generate with logo
image = card.generate_card(
    title="Bohemian Rhapsody",
    artist="Queen",
    thumbnail="album_art.jpg",
    theme="classic"
)
card.save(image, "queen_with_logo.png")

Advanced Logo Features

# Blend modes for creative effects
card.set_logo_blend_mode("overlay")    # overlay, multiply, screen, normal

# Auto logo with fallback
card.enable_auto_logo(True)            # Uses thumbnail if logo fails

# Visual enhancements
card.set_logo_position(120, 60)
card.set_logo_opacity(0.9)
card.set_logo_blend_mode("screen")     # Creates glowing effect

Logo Capabilities

Feature Description Example
Auto-Positioning Smart placement based on theme layout card.set_logo_position(100, 50)
Blend Modes Professional compositing effects overlay, multiply, screen
Opacity Control Fine-tune transparency (0.0-1.0) card.set_logo_opacity(0.8)
Auto-Resize Scales logos to fit perfectly Automatic
Fallback Support Uses thumbnail if logo unavailable enable_auto_logo(True)
URL Support Load from web or local files "https://..." or "logo.png"
Glow Effects Automatic shadows for visibility Built-in

Real-World Examples

# Spotify-style branding
card.set_song_logo("spotify_logo.png")
card.set_logo_position(50, 50)
card.set_logo_opacity(0.7)
card.set_logo_blend_mode("overlay")

# Artist branding
card.set_song_logo("taylor_swift_logo.png")
card.set_logo_position(200, 100)
card.set_logo_opacity(0.6)
card.set_logo_blend_mode("multiply")

# Festival branding
card.set_song_logo("coachella_logo.png")
card.set_logo_position(150, 80)
card.set_logo_opacity(0.5)
card.set_logo_blend_mode("screen")

🎭 Profiles & Automation

Save, reuse, and automate your music card configurations for consistent branding.

Profile Management

from musicard import Musicard

card = Musicard()

# Create a branded profile
brand_profile = {
    "theme": "classic_pro",
    "backgroundColor": "#1a1a1a",
    "progressColor": "#8B5CF6",
    "nameColor": "#ffffff",
    "authorColor": "#cccccc",
    "logoOpacity": 0.8,
    "backgroundBlurLevel": 0.3,
    "watermarkEnabled": True,
    "watermarkText": "MyMusic App"
}

# Save profile
card.save_theme_preset(brand_profile, "brand_profile.json")

# Load and use profile
card.use_profile("brand_profile")
image = card.generate_card(
    title="Blinding Lights",
    artist="The Weeknd",
    thumbnail="weeknd_album.jpg"
)
card.save(image, "branded_card.png")

Automation Features

# Watermark system
card.enable_watermark(True)
card.set_watermark_text("© 2024 MyMusic")

# Background effects
card.enable_background_blur(0.5)        # Blur level 0.0-1.0

# Export quality
card.set_export_quality("8k")           # standard, high, 8k

# Batch processing with profiles
configs = [
    {"title": "Song 1", "artist": "Artist 1", "profile": "brand_profile"},
    {"title": "Song 2", "artist": "Artist 2", "profile": "brand_profile"}
]
images = card.batch_generate(configs, "output/")

CLI Profile Usage

# Save current settings as profile
musicard profile save my_brand

# Use profile in CLI
musicard generate --title "Song" --artist "Artist" --profile my_brand --output card.png

# List available profiles
musicard profile list

🎨 Customization

Custom Colors

card.save("my_music_card.png")

Example Music Card

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

🎵 Basic Music Card

from musicard import Musicard

card = Musicard()

# Simple card
image = card.generate_card(
    title="Levitating",
    artist="Dua Lipa",
    progress=75,
    theme="classic"
)
card.save(image, "dua_lipa_card.png")

🏷️ With Song Logo

card = Musicard()

# Configure logo
card.set_song_logo("dua_lipa_logo.png")
card.set_logo_position(100, 50)
card.set_logo_opacity(0.8)
card.set_logo_blend_mode("overlay")

image = card.generate_card(
    title="Levitating",
    artist="Dua Lipa",
    thumbnail="dua_album.jpg",
    progress=75,
    theme="classic"
)
card.save(image, "dua_with_logo.png")

🎨 Advanced Visual Effects

card = Musicard()

# Visual enhancements
card.enable_background_blur(0.4)
card.enable_watermark(True)
card.set_watermark_text("Now Playing")

# Custom colors and effects
image = card.generate_card(
    title="Watermelon Sugar",
    artist="Harry Styles",
    theme="dynamic",
    backgroundImage="harry_bg.jpg",
    imageDarkness=50,
    progressColor="#E91E63",
    nameColor="#ffffff"
)
card.save(image, "harry_styles_card.png")

🤖 Discord Bot Integration

import discord
from musicard import Musicard
import asyncio

@bot.command()
async def nowplaying(ctx, *, song_info):
    # Parse song info (you'd implement this)
    title, artist = parse_song_info(song_info)

    card = Musicard()

    # Add branding
    card.set_song_logo("bot_logo.png")
    card.enable_watermark(True)
    card.set_watermark_text(f"Requested by {ctx.author.name}")

    image = await card.async_generate_card(
        title=title,
        artist=artist,
        progress=50,  # You'd get real progress
        theme="classic_pro"
    )

    # Send to Discord
    buffer = io.BytesIO()
    image.save(buffer, format="PNG")
    buffer.seek(0)

    embed = discord.Embed(title="🎵 Now Playing")
    embed.set_image(url="attachment://nowplaying.png")

    await ctx.send(
        embed=embed,
        file=discord.File(buffer, "nowplaying.png")
    )

📦 Batch Processing

from musicard import Musicard

card = Musicard()

# Batch configurations
songs = [
    {
        "title": "Song 1",
        "artist": "Artist 1",
        "progress": 30,
        "theme": "classic",
        "logo": "artist1_logo.png"
    },
    {
        "title": "Song 2",
        "artist": "Artist 2",
        "progress": 70,
        "theme": "dynamic",
        "backgroundImage": "bg2.jpg"
    }
]

# Process batch
images = card.batch_generate(songs, "batch_output/")

# Or async batch
images = await card.async_batch_generate(songs, "batch_output/")

🌐 Web Application

from flask import Flask, send_file, request
from musicard import Musicard
import io

app = Flask(__name__)
card = Musicard()

@app.route('/generate-card')
def generate_card():
    title = request.args.get('title', 'Unknown')
    artist = request.args.get('artist', 'Unknown')
    theme = request.args.get('theme', 'classic')

    image = card.generate_card(title, artist, theme=theme)

    # Return as PNG
    buffer = io.BytesIO()
    image.save(buffer, format="PNG")
    buffer.seek(0)

    return send_file(buffer, mimetype='image/png')

📱 Mobile App API

from fastapi import FastAPI, HTTPException
from musicard import Musicard
from pydantic import BaseModel
import base64

app = FastAPI()
card = Musicard()

class CardRequest(BaseModel):
    title: str
    artist: str
    progress: float = 0.0
    theme: str = "mini"
    logo_url: str = None

@app.post("/generate-card")
async def generate_card(request: CardRequest):
    try:
        # Configure card
        if request.logo_url:
            card.set_song_logo(request.logo_url)

        image = await card.async_generate_card(
            title=request.title,
            artist=request.artist,
            progress=request.progress,
            theme=request.theme
        )

        # Convert to base64 for mobile apps
        buffer = io.BytesIO()
        image.save(buffer, format="PNG")
        img_base64 = base64.b64encode(buffer.getvalue()).decode()

        return {"image": img_base64, "format": "png"}

    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

📚 API Reference

Musicard Class

The main class for generating music card images.

Constructor

Musicard(width: int = 1200, height: int = 400)

Parameters:

  • width (int): Default image width in pixels
  • height (int): Default image height in pixels

Core Methods

Method Description Returns
generate_card(title, artist, thumbnail=None, progress=0, theme='classic', **kwargs) Generate music card image PIL.Image.Image
async_generate_card(...) Asynchronous card generation PIL.Image.Image
batch_generate(configs, output_dir='output') Generate multiple cards List[PIL.Image.Image]
async_batch_generate(...) Async batch generation List[PIL.Image.Image]

Export & Utility Methods

Method Description Returns
to_bytes(image, format='PNG') Convert image to bytes bytes
save(image, path, format=None) Save image to file None
export_svg(image, data, path) Export as SVG None
get_available_themes() Get theme list List[str]

Song Logo Methods (v2.2.0)

Method Description Parameters
set_song_logo(path_or_url) Set logo image path_or_url: str
set_logo_position(x, y) Set logo position x: int, y: int
set_logo_opacity(value) Set logo transparency value: float (0.0-1.0)
set_logo_blend_mode(mode) Set blend mode mode: str
enable_auto_logo(enabled) Toggle auto logo enabled: bool

Visual Effects Methods (v2.2.0)

Method Description Parameters
enable_background_blur(level) Background blur effect level: float (0.0-1.0)
enable_watermark(enabled) Toggle watermark enabled: bool
set_watermark_text(text) Set watermark text text: str
set_export_quality(mode) Set export quality mode: str

Profile & Preset Methods

Method Description Parameters
use_profile(profile_name) Load profile profile_name: str
load_theme_preset(path) Load preset from file path: str
save_theme_preset(config, path) Save preset to file config: dict, path: str

Cache Management

Method Description Returns
get_cache_stats() Get cache statistics Dict[str, Any]
clear_cache() Clear all caches None

Method Parameters

generate_card() Parameters

Parameter Type Default Description
title str - Song title (required)
artist str - Artist name (required)
thumbnail `str bytes None`
progress float 0 Progress percentage (0-100)
theme str 'classic' Theme name
**kwargs - - Theme-specific options

Theme-Specific Options

# Common options
backgroundColor: str = "#070707"    # Background color
progressColor: str = "#FF7A00"      # Progress bar color
nameColor: str = "#FF7A00"          # Title color
authorColor: str = "#FFFFFF"        # Artist color

# Dynamic theme options
backgroundImage: str               # Background image path/URL
imageDarkness: int = 50            # Background darkness (0-100)

# Time display (classic themes)
startTime: str = "0:00"            # Start time text
endTime: str = "4:00"              # End time text
timeColor: str = "#FF7A00"         # Time text color

Blend Modes

Supported logo blend modes:

  • 'normal' - Standard overlay
  • 'multiply' - Darkens background
  • 'overlay' - Dynamic light/dark effect
  • 'screen' - Lightens background

Export Quality Modes

  • 'standard' - Default quality (1200x400)
  • 'high' - High quality (2400x800)
  • '8k' - Ultra HD (7680x2560)

🖥️ CLI Usage

Musicard Py includes a powerful command-line interface for quick generation and automation.

Basic Generation

# Simple card generation
musicard generate --title "Blinding Lights" --artist "The Weeknd" --output card.png

# With thumbnail and progress
musicard generate \
  --title "Blinding Lights" \
  --artist "The Weeknd" \
  --thumbnail "album.jpg" \
  --progress 75 \
  --theme classic \
  --output weeknd_card.png

Song Logo Integration

# Set logo for future generations
musicard logo set "weeknd_logo.png"
musicard logo position 100 50
musicard logo opacity 0.8
musicard logo blend overlay

# Enable auto logo fallback
musicard logo auto on

# Generate with logo
musicard generate --title "Song" --artist "Artist" --output card.png

Advanced Features

# Export in different formats
musicard generate --title "Song" --artist "Artist" --format svg --output card.svg

# 8K quality export
musicard export 8k --config song.json --output card_8k.png

# Background blur effect
musicard generate --title "Song" --artist "Artist" --blur 0.5 --output blurred.png

# Add watermark
musicard generate --title "Song" --artist "Artist" --watermark "MyApp" --output card.png

Profile Management

# Save current configuration as profile
musicard profile save my_brand

# Use profile
musicard generate --profile my_brand --title "Song" --artist "Artist" --output card.png

# List profiles
musicard profile list

# Delete profile
musicard profile delete my_brand

Batch Processing

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

# Batch generate multiple cards
musicard batch --input songs.json --output-dir ./cards/

# Queue system for large batches
musicard queue add songs.json
musicard queue start
musicard queue status

Interactive & Preview

# Live ASCII preview
musicard preview --live --title "Song" --artist "Artist"

# Dry run (shows what would be generated)
musicard render --dry-run --config song.json

# Interactive mode
musicard interactive

Cache & Maintenance

# View cache statistics
musicard cache stats

# Clear cache
musicard cache clear

# List available themes
musicard themes

CLI Configuration File

Create ~/.musicard.json for default settings:

{
  "default_theme": "classic",
  "default_quality": "high",
  "auto_logo": true,
  "watermark": "My Music App",
  "background_blur": 0.3
}

Batch JSON Format

[
  {
    "title": "Song 1",
    "artist": "Artist 1",
    "progress": 50,
    "theme": "classic",
    "thumbnail": "album1.jpg",
    "logo": "logo1.png"
  },
  {
    "title": "Song 2",
    "artist": "Artist 2",
    "progress": 75,
    "theme": "dynamic",
    "backgroundImage": "bg.jpg"
  }
]

🔧 Installation

From PyPI (Recommended)

pip install musicard-py

From Source

git clone https://github.com/code-xon/musicard-py.git
cd musicard-py
pip install -e .

Requirements

  • Python: 3.8 or higher
  • Dependencies:
    • Pillow >= 10.0.0 (image processing)
    • requests >= 2.25.0 (HTTP requests)
    • cairosvg >= 2.7.0 (SVG export)
    • diskcache >= 5.6.0 (caching)

🧪 Testing

Run Test Suite

# Install test dependencies
pip install pytest

# Run all tests
pytest

# Run with coverage
pip install pytest-cov
pytest --cov=musicard --cov-report=html

Test Categories

  • Unit Tests: Core functionality and utilities
  • Integration Tests: Full card generation pipeline
  • Performance Tests: Rendering speed benchmarks
  • CLI Tests: Command-line interface validation

📋 Changelog

See CHANGELOG.md for a complete list of changes and version history.

🤝 Contributing

We welcome contributions! Musicard Py is an open-source project and we appreciate any help.

Ways to Contribute

  • 🐛 Bug Reports: Found a bug? Open an issue
  • 💡 Feature Requests: Have an idea? Suggest it
  • 🛠️ Code Contributions: Fix bugs or add features
  • 📚 Documentation: Improve docs or examples
  • 🎨 Themes: Create new themes or improve existing ones

Development Workflow

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/your-username/musicard-py.git
  3. Create a feature branch: git checkout -b feature/amazing-feature
  4. Make your changes with tests
  5. Run tests: pytest
  6. Format code: black musicard/
  7. Commit changes: git commit -m 'Add amazing feature'
  8. Push to branch: git push origin feature/amazing-feature
  9. Open a Pull Request

Guidelines

  • Code Style: Follow PEP 8, use Black for formatting
  • Type Hints: Add type annotations to new code
  • Tests: Include tests for new features
  • Documentation: Update docs for API changes
  • Compatibility: Ensure cross-platform support

Development Setup

git clone https://github.com/code-xon/musicard-py.git
cd musicard-py

# Install in development mode
pip install -e .[dev]

# Install development tools
pip install pytest black ruff mypy pre-commit

# Setup pre-commit hooks
pre-commit install

📄 License

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

🙏 Credits

Musicard Py is inspired by the original musicard JavaScript project by Unburn.

Contributors

  • Ramkrishna - Creator and maintainer
  • Community - Bug reports, feature requests, and contributions

Dependencies

Made with ❤️ in Python

📦 PyPI • 📚 Documentation • 🐛 Issues • 💬 Discussions

About

musicard-py is a futuristic music card canvas library

musicard-py.code-xon.fun/

Topics

python svg cli music-card musicard

Resources

Readme

License

MIT license

Contributing

Contributing
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

🚀 Release: Musicard Python v2.2.0 Latest
Dec 4, 2025
+ 1 release

Contributors

Languages