English | 한국어

SoundBadge

Your code has a soundtrack. Show it.

Turn a YouTube link into a music taste badge for your GitHub profile.

[NEW] Receipt Template — A multi-track ticket for your profile!

---

Your GitHub profile says a lot about you — your languages, your contributions, your streak. But it says nothing about what's playing in your headphones right now.

SoundBadge fixes that. Paste a YouTube link, pick a style, and drop a live music card into your README. It renders on-the-fly as an SVG — no build step, no tokens, no auth.

---

Quick Start

1. Go to the SoundBadge Builder, paste a YouTube URL, pick a theme, and copy the code.

2. Or just copy this directly:

![My Music](https://sound-badge.vercel.app/api/card.svg?url=https://www.youtube.com/watch?v=27KI1NUxpFA&theme=stream)

3. Paste it into your GitHub README.md.

That's it.

---

Examples

Templates

Five purpose-built templates — from minimal badges to full player UIs.

Badge

One-line inline badge. Fits anywhere.

Color variants

Variant	Preview
blue
green
red
purple
orange

Clean

A clean, minimal card. Supports all layouts and multi-track.

Stream

Streaming player UI with animated equalizer and progress bar.

Color variants

Variant	Preview
green
purple
blue
pink
red

Terminal

For the devs. Monospace font, terminal chrome, cursor blink.

Neon

Glowing neon with glassmorphism grid and pulsing border.

Color variants

Variant	Preview
green
pink
cyan

Receipt

Vertical multi-track layout mimicking a store receipt or concert ticket.

Color variants

Variant	Preview
receipt
dark_ticket

---

Classic Themes

Eight classic card themes with thumbnail, title, and channel info.

Minimal	Mono	Pastel
Sunset	Midnight	Glass
Retro	Neon (Legacy)

Note: The classic neon theme is now neon-legacy since neon refers to the new Neon template.

---

Customization

Layouts

Classic themes and the Clean template support three layout sizes:

Compact (320×80)	Regular (420×120)	Wide (600×160)

Tags & Labels

Add context with tags and a custom label:

?tags=kpop,chill,vibe&label=Now Playing

• Tags: Up to 3 comma-separated tags
• Label: Up to 40 characters

Multi-Track

Multi-Track

The stream, terminal, neon, clean, and receipt templates support multiple YouTube URLs — pass multiple url parameters:

?url=https://www.youtube.com/watch?v=VIDEO_1&url=https://www.youtube.com/watch?v=VIDEO_2&theme=stream

Up to 5 tracks per card.

---

API Reference

GET /api/card.svg

Dynamically generates an SVG card image.

Parameter	Required	Default	Description
url	Yes	—	YouTube URL (video or playlist). Repeat for multi-track (&url=...&url=...).
theme	No	minimal	Theme or template name (see Examples)
layout	No	regular	Card size: compact, regular, or wide
tags	No	—	Comma-separated tags (max 3)
label	No	—	Card label text (max 40 chars)
variant	No	—	Color variant for templates that support it

Base URL:

https://sound-badge.vercel.app/api/card.svg

Theme values:

Type	Values
Classic	minimal, mono, neon-legacy, pastel, sunset, midnight, glass, retro
Templates	badge, clean, stream, terminal, neon, receipt

Variant values:

Template	Variants
badge	blue, green, red, purple, orange
stream	green, purple, blue, pink, red
neon	green, pink, cyan
receipt	receipt, dark_ticket

---

Use It in Your README

Markdown

![Now Playing](https://sound-badge.vercel.app/api/card.svg?url=https://www.youtube.com/watch?v=27KI1NUxpFA&theme=stream)

HTML (recommended for more control)

<a href="https://www.youtube.com/watch?v=27KI1NUxpFA">
  <img src="https://sound-badge.vercel.app/api/card.svg?url=https://www.youtube.com/watch?v=27KI1NUxpFA&amp;theme=stream" alt="Now Playing" />
</a>

Wrapping with <a> makes the card clickable — it opens the YouTube video.

Dark / Light Mode

GitHub supports theme-specific images. Show different cards for dark and light mode:

<a href="https://www.youtube.com/watch?v=27KI1NUxpFA">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://sound-badge.vercel.app/api/card.svg?url=https://www.youtube.com/watch?v=27KI1NUxpFA&amp;theme=mono" />
    <source media="(prefers-color-scheme: light)" srcset="https://sound-badge.vercel.app/api/card.svg?url=https://www.youtube.com/watch?v=27KI1NUxpFA&amp;theme=minimal" />
    <img src="https://sound-badge.vercel.app/api/card.svg?url=https://www.youtube.com/watch?v=27KI1NUxpFA&amp;theme=minimal" alt="Now Playing" />
  </picture>
</a>

---

Try the Builder

Don't want to write URLs by hand? Use the SoundBadge Builder.

Paste a YouTube link, pick a theme, tweak the options, and copy the ready-to-use code for your README.

---

Self-Hosting

Requirements

• Node.js 18+
• bun
• YouTube Data API v3 key

Setup

# 1. Clone the repo
git clone https://github.com/gguip1/SoundBadge.git
cd SoundBadge

# 2. Install dependencies
bun install

# 3. Set up environment variables
cp .env.example .env.local
# Edit .env.local and add your YouTube API key

# 4. Start development server
bun dev

Environment Variables

Variable	Required	Description
YOUTUBE_API_KEY	Yes	YouTube Data API v3 key

Deploy to Vercel

---

Tech Stack

• Next.js 16 — App Router + Edge Runtime
• TypeScript — Strict mode
• Tailwind CSS 4 — Builder UI styling
• Vercel Edge Functions — Low-latency SVG generation
• YouTube Data API v3 — Video metadata

---

Contributing

Contributions welcome — new themes, templates, bug fixes, anything goes.

See CONTRIBUTING.md for details.

---

License

Apache License 2.0

---

Stop hiding your music taste behind your commit history.

Try the Builder