# Send SunoMaker to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "sunomaker",
    "name": "SunoMaker",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/Vitja1988/sunomaker",
    "canonicalUrl": "https://clawhub.ai/Vitja1988/sunomaker",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/sunomaker",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=sunomaker",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md",
      "_meta.json",
      "check_env.sh",
      "export_cookies.py",
      "patch_hcaptcha.py",
      "requirements.txt"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "sunomaker",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-09T13:51:30.501Z",
      "expiresAt": "2026-05-16T13:51:30.501Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=sunomaker",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=sunomaker",
        "contentDisposition": "attachment; filename=\"sunomaker-1.1.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "sunomaker"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/sunomaker"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/sunomaker",
    "downloadUrl": "https://openagent3.xyz/downloads/sunomaker",
    "agentUrl": "https://openagent3.xyz/skills/sunomaker/agent",
    "manifestUrl": "https://openagent3.xyz/skills/sunomaker/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/sunomaker/agent.md"
  }
}
```
## Documentation

### 🎵 SunoMaker - Automated Suno AI Music Generation

Designed for Linux servers without a graphical interface (Headless). Uses Xvfb Virtual Display to run Chrome in GUI mode without a monitor, bypassing Google's anti-automation systems.

Two core functions: Account Login (via Google OAuth) and Song Creation (custom lyrics + style + download).

### 0. Prerequisite Check

Before any operation, the environment must be checked:

bash {baseDir}/suno-headless/check_env.sh

Return values:

0 = OK, logged in → songs can be created directly
1 = Dependencies missing → installation required
2 = Not logged in → start the login process

### 1.1 System Dependencies

# Xvfb Virtual Display (core dependency for headless environments)
sudo apt update && sudo apt install -y xvfb

# Google Chrome Browser
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install -y google-chrome-stable

# Fonts for various languages
sudo apt install -y fonts-noto-cjk

### 1.2 Python Dependencies

cd {baseDir}/suno-headless
pip3 install -r requirements.txt
playwright install

### 2. Login Process

⚠️ Important: Never hardcode credentials in the code! Always ask the user.

Two login methods are available:

Method A: Cookie Import (🌟 Recommended! Perfectly bypasses Google security checks)
Method B: Direct Email/Password Login (can trigger Google security prompts)

### 2.1 Method A: Cookie Import (Recommended)

The most stable login method for cloud servers. Completely bypasses Google's security checks.

Steps:

If login is required, explain to the user:

🍪 Recommended Cookie Import Method (bypasses Google security checks):
Step 1: On your local computer (with a browser), run:
pip install playwright && playwright install
python3 export_cookies.py

A browser window will open. Log in to Suno manually. After a successful login, cookies will be exported automatically.
Step 2: Upload the cookie file to the server:
scp <exported-cookie-file> user@server:/root/suno_cookie/suno_cookies.json

Step 3: After uploading, perform the import.

After uploading, run the import (default path: /root/suno_cookie/suno_cookies.json):

cd {baseDir}/suno-headless
python3 suno_login.py --import-cookies

### 2.2 Method B: Email/Password Login

⚠️ Caution: On cloud servers, this can trigger Google security prompts. Prefer Method A.

If login is required, always ask the user:

Suno.com login required (via Google account). Please provide:

Gmail address
Gmail password

⚠️ Credentials are only used for this login, not stored or shared with third parties.

After user input:

cd {baseDir}/suno-headless
python3 suno_login.py --email "<user-email>" --password "<user-password>"

Headless Linux Mode Explanation:

The script automatically detects a GUI-free environment (no $DISPLAY variable)
It automatically starts an Xvfb Virtual Display, simulating a display in memory
Chrome runs in GUI mode (headless=False), but nothing is displayed on the screen
This bypasses Google's headless browser detection

### 2.3 Check Login Status

cd {baseDir}/suno-headless
python3 suno_login.py --check-only

Exit codes: 0 = Logged in, 2 = Not logged in

### 2.4 Force Re-login

# Method A: Re-import cookies
cd {baseDir}/suno-headless
python3 suno_login.py --import-cookies "<new-cookie-file>"

# Method B: Re-enter email/password
cd {baseDir}/suno-headless
python3 suno_login.py --email "<email>" --password "<password>" --force-login

### 3.1 Prerequisites

Logged in (suno_login.py --check-only returns 0)
Gemini API Key required (for automatic hCaptcha solving)

### 3.2 Get a Gemini API Key

If the user does not have a Gemini API Key:

When creating a song, Suno shows captchas. A Gemini API Key is required for automatic solving.

Visit https://aistudio.google.com/app/apikey
Click "Create API key"
Copy the generated key

Save it in an environment file:

mkdir -p ~/.suno
echo "GEMINI_API_KEY=<user-key>" > ~/.suno/.env

Or as an environment variable:

export GEMINI_API_KEY="<user-key>"

### 3.3 hCaptcha Compatibility Patch

Run this once before the first use (Suno uses its own hCaptcha domain, a patch is required):

cd {baseDir}/suno-headless
python3 patch_hcaptcha.py

### 3.4 Song Creation Command

cd {baseDir}/suno-headless
python3 suno_create_song.py \\
  --lyrics "<lyrics-content>" \\
  --style "<music-style-tags>" \\
  --title "<song-title>" \\
  --output-dir "<download-dir>"

Read lyrics from a file:

cd {baseDir}/suno-headless
python3 suno_create_song.py \\
  --lyrics-file "<lyrics-file-path>" \\
  --style "<music-style-tags>" \\
  --title "<song-title>"

Headless Mode Explanation:

suno_create_song.py automatically detects a GUI-free environment
It automatically starts an Xvfb Virtual Display, running Chrome in GUI mode in the virtual display
After the script finishes, the Virtual Display is automatically closed, no manual action needed

### 3.5 Parameter Explanation

ParameterDescriptionRequiredDefault Value--lyricsSong lyrics (alternative to --lyrics-file)✅---lyrics-filePath to the lyrics file (alternative to --lyrics)✅---styleMusic style tags (English, comma-separated)❌rock, electric guitar, energetic, male vocals--titleSong title❌My Song--output-dirMP3 download directory❌{baseDir}/output_mp3--gemini-keyGemini API Key (alternatively: environment variable or ~/.suno/.env)❌Auto-Read

### 3.6 Music Style Tags Reference

Common style tags (English, combinable):

Genres: rock, pop, jazz, blues, electronic, hip-hop, R&B, classical, folk, metal, country, reggae, latin, indie
Instruments: electric guitar, acoustic guitar, piano, synthesizer, drums, bass, violin, saxophone, trumpet
Mood: energetic, emotional, melancholic, upbeat, dark, dreamy, aggressive, peaceful, romantic
Vocals: male vocals, female vocals, choir, rap, whisper, powerful vocals, falsetto
Language: german, english, french, spanish, chinese, japanese
Other: fast tempo, slow tempo, instrumental, lo-fi, cinematic, epic

Examples:

Rock: rock, electric guitar, energetic, male vocals, english
Ballad: pop, piano, emotional, female vocals, slow tempo, english
Electronic: electronic, synthesizer, upbeat, fast tempo, dance
Hip-Hop: hip-hop, rap, bass, drums, energetic, english

### Example: Create a Rock Song on a Linux Server

# 1. Check environment (automatically detects Xvfb, Chrome, etc.)
bash {baseDir}/suno-headless/check_env.sh

# 2. If not logged in, use the cookie import method (recommended)
#    Step 1: Run export_cookies.py on the local computer
#    Step 2: scp <cookie-file> user@server:/root/suno_cookie/suno_cookies.json
#    Step 3: Import on the server (default: /root/suno_cookie/suno_cookies.json)
cd {baseDir}/suno-headless
python3 suno_login.py --import-cookies

# Or use the email/password method (can trigger Google security prompts)
# python3 suno_login.py --email "user@gmail.com" --password "password123"

# 3. Apply hCaptcha patch
python3 patch_hcaptcha.py

# 4. Create song (automatically with Xvfb Virtual Display)
python3 suno_create_song.py \\
  --lyrics "The sun rises over the city
A new day is dawning
We walk through the streets
And sing our song" \\
  --style "rock, electric guitar, energetic, male vocals, english" \\
  --title "Morning Song Rock Version"

### 5. Differences from the Original Version

Featuresuno (Original)suno-headless (This Version)Target EnvironmentmacOS / Linux with GUILinux Server without GUIDisplay ModeReal Chrome windowXvfb Virtual Display (RAM simulation)Additional DependenciesNonexvfb + PyVirtualDisplayLogin Xvfb✅ Supported✅ SupportedSong Creation Xvfb❌ Not supported✅ SupportedEnvironment CheckBasicIncl. Xvfb/Chrome/Font Check

### Xvfb Virtual Display Solution

┌─────────────────────────────────────────┐
│          Linux Server (no monitor)      │
│                                         │
│  ┌─────────────┐    ┌────────────────┐  │
│  │   Xvfb      │    │  Chrome        │  │
│  │ (Virtual    │◄───│ (GUI Mode)     │  │
│  │  Display)   │    │ headless=False │  │
│  │ :99 1280x800│    └────────────────┘  │
│  └─────────────┘           │             │
│        ▲                   │             │
│        │              Automated          │
│   PyVirtualDisplay     Suno.com Control  │
│   Auto-Lifecycle            │             │
│        │                   ▼             │
│        │            ┌────────────────┐   │
│        │            │ Song Generation│   │
│        │            │ + Download     │   │
│        │            └────────────────┘   │
└────────┼────────────────────────────────┘
         │
         ▼
     Memory (RAM)

Why not headless=True? Google OAuth detects headless browsers and blocks logins
Xvfb solution: Creates a virtual X11 display in RAM, Chrome "thinks" there's a real GUI, so Google can't detect the automation
Auto-detection: The script checks the $DISPLAY environment variable and starts Xvfb automatically if no GUI is present
Resources: Xvfb uses minimal RAM and is automatically released after the script finishes

### Login Solution

Playwright + Real Chrome browser (channel='chrome')
persistent context maintains browser state (cookies, localStorage)
headless=False + Xvfb Virtual Display bypasses Google's anti-automation
After the first login, the session is maintained through the persistent context

### Song Creation Solution

Browser automation controls the suno.com/create page
hcaptcha-challenger + Gemini API solves hCaptcha automatically
New clip ID is obtained by intercepting browser network responses
Suno's internal API (studio-api.prod.suno.com) polls the song generation status
Automatic MP3 download upon completion

### File Structure

suno-headless/
├── suno_login.py          # Login tool (Google OAuth / Cookie Import + Xvfb)
├── suno_create_song.py    # Song creation + download (Xvfb support)
├── export_cookies.py      # Cookie export tool (run on local computer)
├── patch_hcaptcha.py      # hCaptcha domain compatibility patch
├── check_env.sh           # Environment check (incl. Xvfb/Chrome check)
├── requirements.txt       # Python dependencies (incl. PyVirtualDisplay)
└── SKILL.md               # This documentation

### 7. Important Notes

Never hardcode credentials — Always ask the user (prefer cookie import)
Xvfb must be installed — sudo apt install -y xvfb, otherwise it won't run in a headless environment
Real Chrome is required — Playwright's own Chromium can be detected by Google
Suno Free accounts have a daily point limit, approx. 100 points per song
Song generation typically takes 1-3 minutes
Each creation generates 2 different song versions
If Google login is rejected: wait 10-30 minutes, then try again
Gemini API Free limit: 15 Requests/Minute, 1500/Day
hCaptcha may take several attempts, success rate depends on Gemini's image recognition

### 8. Troubleshooting

# Check environment (incl. Xvfb status)
bash {baseDir}/suno-headless/check_env.sh

# Test Xvfb manually
Xvfb :99 -screen 0 1280x800x24 &
DISPLAY=:99 google-chrome --no-sandbox --version
kill %1

# View login screenshots
ls -la /tmp/suno_debug_*.png

# Check persistent context
ls -la ~/.suno/chrome_gui_profile/

# View cookies
python3 -c "import json; d=json.load(open('$HOME/.suno/cookies.json')); print(f'{len(d)} cookies')"

# Check Gemini API Key
cat ~/.suno/.env

# View downloaded songs
ls -la {baseDir}/output_mp3/
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: Vitja1988
- Version: 1.1.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-09T13:51:30.501Z
- Expires at: 2026-05-16T13:51:30.501Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/sunomaker)
- [Send to Agent page](https://openagent3.xyz/skills/sunomaker/agent)
- [JSON manifest](https://openagent3.xyz/skills/sunomaker/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/sunomaker/agent.md)
- [Download page](https://openagent3.xyz/downloads/sunomaker)