🚀 What is BeatPrints.js?

BeatPrints.js is a visual utility to generate music posters from your favorite tracks and albums. This Node.js version brings the spirit of the original Python BeatPrints project to the JavaScript ecosystem, supporting:

• 🎨 Rich visual themes (Catppuccin, Nord, RosePine, etc.)
• 🖼️ Album/track art with Spotify scannables
• ✍️ Lyric highlights from LRClib
• 📄 Output as file or in-memory buffer

📦 Installation

pnpm add beatprints.js
# or
npm install beatprints.js

🌱 Setup

Make sure you have a .env file with your Spotify credentials:

SPOTIFY_CLIENT_ID="your-client-id"
SPOTIFY_CLIENT_SECRET="your-client-secret"

You can get these from: Spotify Developer Dashboard

🎀 Quick Poster Generation

import { Spotify, Lyrics, Poster } from 'beatprints.js';

const client = new Spotify(
    process.env.SPOTIFY_CLIENT_ID, 
    process.env.SPOTIFY_CLIENT_SECRET
);

const lrc = new Lyrics();
const poster = new Poster({ 
    filename: 'love_lost.png', 
    output: { 
        type: 'path',
        value: './path/to/output/dir'
    }
});

const search = await client.getTrack('love lost - boywithuke', 1);
const lyrics = await lrc.getLyrics(search, true);

const highLightedLyrics = await lrc.selectLines(lyrics, '31-34');

await poster.track(search, highLightedLyrics, { palette: true, accent: true });

The example above will result in this:

✨ Features

• 📀 Album and 🎧 Track poster generation
• 🖌️ Theme support: Light, Dark, Catppuccin, Nord, Gruvbox, RosePine, Everforest
• 🧠 Smart text layout & column handling
• 🎼 Lyric support via LRClib
• 🌈 Accent colors from cover palette
• 📦 Buffer or file output
• 📝 Custom fonts

📁 Output Options

// Save poster to file
new Poster({ type: 'path', value: './output', filename: 'example.png' /* optional */ });

// Return poster as Buffer (useful for APIs)
new Poster({ type: 'buffer' });

🖼️ More Examples

🎨 Themes

// Available themes: "Light", "Dark", "Catppuccin", "Gruvbox", "Nord", "RosePine", "Everforest"
await poster.track(metadata, selectedLyrics, {
    theme: 'Catppuccin'
});

📝 Loading custom fonts

If you want to add support for custom fonts not included by default (e.g., NotoSansSC for Simplified Chinese), you can register them dynamically like this:

import { registerCustomFonts } from 'beatprints.js';

// Paths to your font files. Each file should be named in the format Family-Weight.ttf
const fontPaths = [
  '/path/to/fonts/NotoSansSC/NotoSansSC-Regular.ttf',
  '/path/to/fonts/NotoSansSC/NotoSansSC-Bold.ttf',
  '/path/to/fonts/NotoSansSC/NotoSansSC-Light.ttf',
];

// Provide an alias mapping folder/family name to display name used internally
const aliases = {
  'NotoSansSC': 'Noto Sans SC',
};

// Register your custom fonts
registerCustomFonts(fontPaths, aliases);

// Now you can use "Noto Sans SC" as a font alias in rendering functions

Important

• "Make sure your font files follow the naming convention Family-Weight.ttf exactly."
• "Register all weights you intend to use (e.g. Regular, Light, Bold)."

This allows you to seamlessly extend font support without modifying internal code or defaults.

📜 License

BeatPrints.js is a derivative of the original BeatPrints by TrueMyst. Distributed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) License.

You may:

• ✅ Share and adapt the material
• ❌ Not use it for commercial purposes
• 🔁 Share alike with proper attribution

More: LICENSE

💜 Credits & Thanks

• Original concept & inspiration: TrueMyst
• Fonts, layout, ideas based on the Python version
• Color palette extraction: sharp-vibrant
• Lyrics: LRClib