Suno Cards

Display your Suno AI music as dynamic, animated SVG cards in your GitHub README.

Give us your Suno handle and do nothing else. Your GitHub README stays in sync with your music — new songs, play counts, and likes appear automatically.

Live Demo · Browse Gallery · Build Your Card

Classic Layout

Player Layout

Table of Contents

How It Works
Getting Started
- Embed a Single Card (zero setup)
- Auto-Sync with GitHub Action
Style Gallery
Customization Guide
API Reference
GitHub Action Reference
Render Modes
Example Workflows
Roadmap
Architecture & Internals
Acknowledgements
Author
License

How It Works

flowchart LR
    A[Your Suno Handle] --> B[GitHub Action]
    B --> C[Suno Public API]
    C --> D[Song & Profile Data]
    D --> E[SVG Card Renderer]
    E --> F[Your README.md]

    style A fill:#7c3aed,color:#fff
    style F fill:#7c3aed,color:#fff

There are two usage modes:

Direct Embed (Zero Setup) — Paste a card URL in your README. GitHub renders the SVG live via Vercel Edge.
GitHub Action (Auto-Sync) — Add a workflow that runs on a schedule. It fetches your songs from Suno and updates your README automatically.

Getting Started

Embed a Single Card (zero setup)

No GitHub Action needed — paste a URL directly into your README:

[![My Song](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID)](https://suno.com/song/YOUR_SONG_UUID)

The id parameter accepts:

A full UUID: a885e43c-6918-456f-a5f0-0e8e29e61066
A Suno URL: https://suno.com/song/a885e43c-6918-456f-a5f0-0e8e29e61066
A short code: https://suno.com/s/YourShortCode

Tip: Use the interactive builder to customize the card visually, then copy the generated embed code.

Auto-Sync with GitHub Action

Step 1 — Add markers to your README

## My Suno Music

<!-- SUNO-CARDS:START -->
<!-- SUNO-CARDS:END -->

Step 2 — Create `.github/workflows/suno-cards.yml`

name: Update Suno cards

on:
  schedule:
    - cron: '0 */6 * * *'   # Every 6 hours
  workflow_dispatch:

permissions:
  contents: write

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ChanMeng666/github-readme-suno-cards@v0.1
        with:
          handle: YOUR_SUNO_HANDLE
          sort: play_count
          max: 6
      - uses: EndBug/add-and-commit@v9
        with:
          message: 'chore(suno-cards): refresh'
          add: './README.md'

Step 3 — Done!

Every 6 hours (or on manual trigger), the Action fetches your public songs, sorts them, and writes the cards between your markers.

Style Gallery

All examples below use a real demo song. Replace a885e43c-6918-456f-a5f0-0e8e29e61066 with your own song UUID and copy the code to your README.

Tip: Use the interactive card builder to customize any style visually, then copy the generated embed code.

Layouts + Presets

There are 2 layouts x 2 color presets = 4 base combinations.

Classic + Default

Info-dense layout with purple accent — title, author, tags, stats, model badge, animated equalizer.

Copy embed code

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID)](https://suno.com/song/YOUR_SONG_UUID)

Classic + Suno

Info-dense layout with Suno's official navy + gold palette.

Copy embed code

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&preset=suno)](https://suno.com/song/YOUR_SONG_UUID)

Player + Default

Suno-style music player with progress bar, play button, and SUNO logo — using the default purple theme.

Copy embed code

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&layout=player)](https://suno.com/song/YOUR_SONG_UUID)

Player + Suno

The full Suno official look — player layout with navy + gold palette.

Copy embed code

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&layout=player&preset=suno)](https://suno.com/song/YOUR_SONG_UUID)

Theme Variants

Each card supports three theme modes:

Theme	Behavior
`auto` (default)	Switches with GitHub's dark/light setting via `prefers-color-scheme`
`dark`	Always dark background
`light`	Always light background

Classic — Light

Copy embed code

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&theme=light)](https://suno.com/song/YOUR_SONG_UUID)

Player + Suno — Light

Copy embed code

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&layout=player&preset=suno&theme=light)](https://suno.com/song/YOUR_SONG_UUID)

Classic + Suno — Light

Copy embed code

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&preset=suno&theme=light)](https://suno.com/song/YOUR_SONG_UUID)

Player + Default — Light

Copy embed code

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&layout=player&theme=light)](https://suno.com/song/YOUR_SONG_UUID)

Toggle Showcases

View toggle variations — fine-tune which elements appear on your card

All toggles accept true or false.

Minimal Classic — Title and cover only

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&show_tags=false&show_plays=false&show_likes=false&show_model_badge=false&show_equalizer=false&show_new_badge=false&show_author=false)](https://suno.com/song/YOUR_SONG_UUID)

Full Info Classic — Every element visible

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&show_progress=true&show_logo=true&show_link_icon=true)](https://suno.com/song/YOUR_SONG_UUID)

Full Info Player — Player with tags, author, and stats

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&layout=player&preset=suno&show_tags=true&show_author=true&show_plays=true&show_likes=true)](https://suno.com/song/YOUR_SONG_UUID)

Player — No Equalizer

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&layout=player&preset=suno&show_equalizer=false)](https://suno.com/song/YOUR_SONG_UUID)

Player — With Stats

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&layout=player&show_plays=true&show_likes=true)](https://suno.com/song/YOUR_SONG_UUID)

Custom Accent Colors

View custom accent color examples — override the accent with any hex value using accent_color

Use the accent_color parameter with any hex value (without the #).

Red Accent (`ff6b6b`)

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&layout=player&preset=suno&accent_color=ff6b6b)](https://suno.com/song/YOUR_SONG_UUID)

Teal Accent (`2dd4bf`)

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&accent_color=2dd4bf)](https://suno.com/song/YOUR_SONG_UUID)

Orange Accent (`fb923c`)

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&layout=player&accent_color=fb923c)](https://suno.com/song/YOUR_SONG_UUID)

Pink Accent (`f472b6`)

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&accent_color=f472b6)](https://suno.com/song/YOUR_SONG_UUID)

Green Accent (`22c55e`)

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&layout=player&accent_color=22c55e)](https://suno.com/song/YOUR_SONG_UUID)

Blue Accent (`38bdf8`)

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&accent_color=38bdf8)](https://suno.com/song/YOUR_SONG_UUID)

Profile & Card Stack

Profile Summary Card

Show your Suno profile stats at a glance — avatar, handle, total plays, likes, followers.

Copy embed code

[![](https://github-readme-suno-cards.vercel.app/api/profile?handle=YOUR_HANDLE)](https://suno.com/@YOUR_HANDLE)

Auto-Discovered Card Stack

Your top songs, sorted and stacked together. Use the max parameter to control how many.

Copy embed code

[![](https://github-readme-suno-cards.vercel.app/api/cards?handle=YOUR_HANDLE&sort=play_count&max=3)](https://suno.com/@YOUR_HANDLE)

Customization Guide

flowchart TB
    A["1. Pick a layout"] --> B["2. Pick a color preset"]
    B --> C["3. Pick a theme"]
    C --> D["4. Toggle elements on/off"]
    D --> E["5. Override colors (optional)"]
    E --> F["6. Copy the URL"]

    style A fill:#7c3aed,color:#fff
    style F fill:#7c3aed,color:#fff

Or use the interactive builder for a visual drag-and-drop experience.

Layout options

Layout	Description	Best for
`classic`	Info-dense Spotify-style card with tags, stats, badges	Detailed song info
`player`	Suno-style music player with progress bar and play button	Clean, visual look

Color presets

Preset	Colors	Vibe
`default`	Purple accent on dark/light background	Modern, neutral
`suno`	Navy + gold palette matching Suno's brand	Official look

Theme modes

Theme	Behavior
`auto`	Follows GitHub's dark/light toggle via CSS `prefers-color-scheme`
`dark`	Always dark background
`light`	Always light background

Element toggles (11 options)

Each element can be shown or hidden independently. Defaults vary by layout.

Toggle	Classic default	Player default	Controls
`show_equalizer`	`true`	`true`	Animated equalizer bars on cover
`show_tags`	`true`	`false`	Genre/mood tag chips
`show_plays`	`true`	`false`	Play count
`show_likes`	`true`	`false`	Like count
`show_author`	`true`	`false`	Author byline
`show_duration`	`true`	`false`	Duration pill on cover
`show_model_badge`	`true`	`false`	Suno model badge (v4.5/v5)
`show_new_badge`	`true`	`false`	NEW ribbon on recent songs
`show_progress`	`false`	`true`	Progress bar + play button
`show_logo`	`false`	`true`	SUNO logo in bottom-right
`show_link_icon`	`false`	`true`	Link icon in top-right

Color overrides

Fine-tune any color with hex values (with or without #):

Parameter	Description
`bg_color`	Card background
`text_color`	Title / primary text
`subtext_color`	Secondary text
`accent_color`	Equalizer bars, chips, progress bar
`border_color`	Card border

Example — Full custom colors:

[![](https://github-readme-suno-cards.vercel.app/api/card?id=YOUR_SONG_UUID&layout=player&bg_color=1a1a2e&text_color=eaeaea&accent_color=e94560)](https://suno.com/song/YOUR_SONG_UUID)

API Reference

API Reference — 3 endpoints, all parameters

Endpoints

Endpoint	Description
`GET /api/card?id=<uuid\|url\|short>`	Single song card (SVG)
`GET /api/profile?handle=<handle>`	Profile summary card (SVG)
`GET /api/cards?handle=<handle>`	Stacked multi-card auto-discovery (SVG)
`GET /song/<uuid>`	Pretty URL alias for `/api/card?id=<uuid>`

Base URL: https://github-readme-suno-cards.vercel.app

`/api/card` Parameters

Parameter	Type	Default	Description
`id`	string	required	Song UUID, Suno URL, or short code
`layout`	`classic` \| `player`	`classic`	Card layout
`preset`	`default` \| `suno`	`default`	Color preset
`theme`	`auto` \| `dark` \| `light`	`auto`	Theme mode
`lang`	`en` \| `zh` \| `ja`	`en`	Language
`width`	`200`–`1200`	auto	Card width in pixels
`show_equalizer`	boolean	layout-dep.	Animated equalizer
`show_tags`	boolean	layout-dep.	Tag chips
`show_plays`	boolean	layout-dep.	Play count
`show_likes`	boolean	layout-dep.	Like count
`show_author`	boolean	layout-dep.	Author byline
`show_duration`	boolean	layout-dep.	Duration pill
`show_model_badge`	boolean	layout-dep.	Model badge
`show_new_badge`	boolean	layout-dep.	NEW ribbon
`show_progress`	boolean	layout-dep.	Progress bar
`show_logo`	boolean	layout-dep.	SUNO logo
`show_link_icon`	boolean	layout-dep.	Link icon
`max_tags`	`0`–`20`	auto	Max tag chips
`bg_color`	hex	preset	Background color
`text_color`	hex	preset	Primary text color
`subtext_color`	hex	preset	Secondary text color
`accent_color`	hex	preset	Accent color
`border_color`	hex	preset	Border color

`/api/profile` Parameters

Parameter	Type	Default	Description
`handle`	string	required	Suno user handle
`theme`	`auto` \| `dark` \| `light`	`auto`	Theme mode
`lang`	`en` \| `zh` \| `ja`	`en`	Language
`width`	`200`–`1200`	auto	Card width
`bg_color`, `text_color`, `subtext_color`, `accent_color`, `border_color`	hex	preset	Color overrides

`/api/cards` Parameters

Includes all /api/card visual parameters, plus:

Parameter	Type	Default	Description
`handle`	string	required	Suno handle
`sort`	`created_at` \| `play_count` \| `upvote_count` \| `name`	`created_at`	Sort order
`max`	`1`–`20`	`6`	Max cards
`include_tags`	CSV	—	Only songs matching these tags
`exclude_tags`	CSV	—	Exclude songs matching these tags
`min_duration`	seconds	—	Minimum duration
`max_duration`	seconds	—	Maximum duration
`min_plays`	integer	—	Minimum play count
`min_likes`	integer	—	Minimum like count
`pinned_first`	boolean	`true`	Prioritize pinned songs
`featured`	CSV of UUIDs	—	Pin specific songs above all
`allow_explicit`	boolean	`true`	Include explicit songs
`show_profile_card`	boolean	`true`	Show profile card above songs

Caching

Upstream (Suno API calls): revalidated every 3600s (card) or 600s (profile/cards)
Downstream (HTTP response): Cache-Control: s-maxage=3600, stale-while-revalidate=86400
GitHub's Camo proxy caches SVGs — changes may take up to an hour to appear

GitHub Action Reference

GitHub Action Reference — all inputs & outputs

Data Source (pick one)

Input	Default	Description
`handle`	—	Your Suno handle (auto-discovery mode)
`manifest_path`	`./suno-songs.yml`	Path to YAML manifest of song IDs
`song_ids`	—	Comma-separated UUIDs inline

Filters & Ranking

Input	Default	Description
`sort`	`created_at`	`created_at` \| `play_count` \| `upvote_count` \| `name`
`max`	`6`	Max song cards (1–20)
`include_tags`	—	CSV substring filter (case-insensitive)
`exclude_tags`	—	CSV substring filter
`min_duration` / `max_duration`	—	Seconds
`min_plays` / `min_likes`	—	Integer floors
`pinned_first`	`true`	Respect `is_pinned` above sort order
`featured`	—	CSV of UUIDs pinned above everything
`allow_explicit`	`true`	Include explicit-tagged songs
`show_profile_card`	`true`	Emit profile card above song cards

Visual Style

Input	Default	Description
`layout`	`classic`	`classic` or `player`
`preset`	`default`	`default` (purple) or `suno` (navy + gold)
`theme`	`auto`	`auto` / `dark` / `light`
`lang`	`en`	`en` / `zh` / `ja`
`width`	—	Card width in px (200–1200)
`bg_color`	—	Background hex (with or without `#`)
`text_color`	—	Primary text color
`accent_color`	—	Accent color
`show_progress`	layout-dep.	Progress bar + play button
`show_logo`	layout-dep.	SUNO logo in bottom-right
`show_link_icon`	layout-dep.	Link icon in top-right

Output & Format

Input	Default	Description
`render_mode`	`service`	`service` (live) or `local` (pre-render SVGs)
`local_cards_dir`	`.suno-cards`	Output dir in local mode
`readme_path`	`./README.md`	Path to README
`comment_tag_name`	`SUNO-CARDS`	Marker name (allows multiple instances)
`output_type`	`markdown`	`markdown` or `html` (with `<picture>` theme switching)
`output_only`	`false`	Skip README write, emit via outputs only
`base_url`	`https://github-readme-suno-cards.vercel.app`	Self-hosted service override

Action Outputs

Output	Description
`profile`	JSON-encoded `SunoProfile`
`clips`	JSON-encoded array of `SunoSong`
`cards_block`	The markdown/HTML block written to README
`rendered_files`	JSON array of SVG paths (local mode only)

Render Modes

Render Modes — Service vs Local

flowchart LR
    subgraph service["Service Mode (default)"]
        S1["README links to<br/>github-readme-suno-cards.vercel.app"] --> S2["SVG rendered on-the-fly"]
        S2 --> S3["Always up-to-date<br/>play counts, badges"]
    end

    subgraph local["Local Mode"]
        L1["Action pre-renders SVGs"] --> L2["Committed to .suno-cards/"]
        L2 --> L3["Zero external dependency<br/>works offline, in mirrors"]
    end

Service (default)

The Action writes markdown pointing at the hosted Vercel service. Cards auto-update whenever anyone views your README — play counts, NEW badges, and any data change reflects live.

# No extra config needed — service mode is the default
- uses: ChanMeng666/github-readme-suno-cards@v0.1
  with:
    handle: YOUR_HANDLE

Local

The Action pre-renders SVGs with embedded base64 cover images into .suno-cards/ in your repo. Zero dependency on any hosted service.

- uses: ChanMeng666/github-readme-suno-cards@v0.1
  with:
    handle: YOUR_HANDLE
    render_mode: local
    local_cards_dir: '.suno-cards'

Example Workflows

Example Workflows — ready-to-copy workflow files

See examples/ for ready-to-copy workflow files:

File	Mode	Description
`auto-discovery.yml`	Service	Zero-config auto-discovery — just your handle
`manifest-mode.yml`	Service	Explicit song list via YAML manifest
`local-mode.yml`	Local	Pre-render SVGs to your repo
`suno-songs.yml`	—	Sample manifest file

Roadmap

Roadmap

v0.2

Waveform card variant (Action local mode only) — download MP3, compute amplitude samples, render SVG <path>
Lyrics excerpt card — parse [Chorus] from structured prompt, render as card subtitle
Playlist card — render Suno playlists
JSON API — /api/song.json and /api/profile.json for third-party tools
PNG export — /api/card.png via @resvg/resvg

v0.3

Vercel KV play-count history — trending arrows (+15 this week), weekly summaries
RSS/Atom feed per handle — /api/feed/{handle}.xml

v0.4+

Cover-art color extraction for per-song gradient backgrounds
Song-DNA radar chart card
Year-in-review card

Architecture & Internals

Architecture & Internals — monorepo structure, rendering technique, web app

Monorepo Architecture

graph TB
    subgraph Monorepo["pnpm Monorepo"]
        subgraph packages["packages/"]
            Parser["@suno-cards/parser<br/>Suno API client<br/>+ Valibot schemas"]
            Render["@suno-cards/render<br/>SVG card primitives<br/>(pure, no network I/O)"]
        end

        subgraph apps["apps/"]
            Web["@suno-cards/web<br/>Next.js 15 on<br/>Vercel Edge Runtime"]
        end

        subgraph action["action/"]
            Action["GitHub Action<br/>Node 20<br/>esbuild-bundled"]
        end
    end

    Parser --> Web
    Parser --> Action
    Render --> Web
    Render --> Action

    SunoAPI["Suno Public API<br/>studio-api-prod.suno.com"] --> Parser
    Web --> Vercel["Vercel Edge<br/>~20ms warm"]
    Action --> GH["GitHub Actions<br/>Scheduled / Manual"]

Package Breakdown

Package	Role
`packages/parser`	Suno API client + Valibot schemas. Zero HTML scraping — uses only public `studio-api-prod.suno.com` endpoints.
`packages/render`	SVG card primitives. Pure functions, no network I/O. Template-literal SVG with `<foreignObject>` for CJK-friendly rich text.
`apps/web`	Next.js 15 on Vercel Edge Runtime. 3 API routes + 3-page React frontend with Tailwind CSS.
`action`	Node 20 GitHub Action. Bundled with esbuild, committed `dist/index.js`.

Rendering Technique

SVG with <foreignObject> for CJK-friendly rich text layout
CSS @media (prefers-color-scheme) for auto dark/light theming
CSS @keyframes on HTML <span>s inside foreignObject for the animated equalizer bars
Dual-layer caching: Vercel Data Cache for upstream Suno calls + HTTP Cache-Control for downstream GitHub Camo proxy

Web App

The project includes a full 3-page React frontend at github-readme-suno-cards.vercel.app:

Page	URL	Description
Home	github-readme-suno-cards.vercel.app	Hero showcase, feature highlights, featured card styles
Gallery	github-readme-suno-cards.vercel.app/gallery	Browse 20+ curated presets with layout/preset/theme filters
Builder	github-readme-suno-cards.vercel.app/builder	Interactive card builder with live preview, toggles, color pickers, and embed code generator

Data Source Compliance

Uses only the public https://studio-api-prod.suno.com endpoints that Suno publishes as their oEmbed provider. No cookies, no session tokens, no reverse-engineered auth.

Acknowledgements

The card primitives borrow ideas from several excellent projects:

github-readme-medium-recent-article — Next.js + Vercel architecture
github-readme-youtube-cards — dual-mode Action + service, theme switching
blog-post-workflow — esbuild bundling, marker-replace regex, CI dist-diff verification
spotify-github-profile — CSS-animated equalizer overlay technique

Author

Chan Meng

License

MIT

Made with music by Suno

Chan Meng
Need a custom app like this one? I build them — let's talk.

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
.github		.github
action		action
apps/web		apps/web
docs		docs
examples		examples
og		og
packages		packages
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
GOVERNANCE.md		GOVERNANCE.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
action.yml		action.yml
biome.json		biome.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
vercel.json		vercel.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Suno Cards

Display your Suno AI music as dynamic, animated SVG cards in your GitHub README.

How It Works

Getting Started

Embed a Single Card (zero setup)

Auto-Sync with GitHub Action

Step 1 — Add markers to your README

Step 2 — Create .github/workflows/suno-cards.yml

Step 3 — Done!

Style Gallery

Layouts + Presets

Classic + Default

Classic + Suno

Player + Default

Player + Suno

Theme Variants

Classic — Light

Player + Suno — Light

Classic + Suno — Light

Player + Default — Light

Toggle Showcases

Minimal Classic — Title and cover only

Full Info Classic — Every element visible

Full Info Player — Player with tags, author, and stats

Player — No Equalizer

Player — With Stats

Custom Accent Colors

Red Accent (ff6b6b)

Teal Accent (2dd4bf)

Orange Accent (fb923c)

Pink Accent (f472b6)

Green Accent (22c55e)

Blue Accent (38bdf8)

Profile & Card Stack

Profile Summary Card

Auto-Discovered Card Stack

Customization Guide

API Reference

Endpoints

/api/card Parameters

/api/profile Parameters

/api/cards Parameters

Caching

GitHub Action Reference

Data Source (pick one)

Filters & Ranking

Visual Style

Output & Format

Action Outputs

Render Modes

Service (default)

Local

Example Workflows

Roadmap

v0.2

v0.3

v0.4+

Architecture & Internals

Monorepo Architecture

Package Breakdown

Rendering Technique

Web App

Data Source Compliance

Acknowledgements

Author

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Step 2 — Create `.github/workflows/suno-cards.yml`

Red Accent (`ff6b6b`)

Teal Accent (`2dd4bf`)

Orange Accent (`fb923c`)

Pink Accent (`f472b6`)

Green Accent (`22c55e`)

Blue Accent (`38bdf8`)

`/api/card` Parameters

`/api/profile` Parameters

`/api/cards` Parameters

Packages