🎵 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. Install Dependencies (first time only)

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:

1. Gmail address
2. 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. Create a Song

3.1 Prerequisites

1. Logged in (suno_login.py --check-only returns 0)
2. 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.

1. Visit https://aistudio.google.com/app/apikey
2. Click "Create API key"
3. 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

Parameter	Description	Required	Default Value
--lyrics	Song lyrics (alternative to --lyrics-file)	✅	-
--lyrics-file	Path to the lyrics file (alternative to --lyrics)	✅	-
--style	Music style tags (English, comma-separated)	❌	rock, electric guitar, energetic, male vocals
--title	Song title	❌	My Song
--output-dir	MP3 download directory	❌	{baseDir}/output_mp3
--gemini-key	Gemini 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

---

4. Complete Example

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

Feature	suno (Original)	suno-headless (This Version)
Target Environment	macOS / Linux with GUI	Linux Server without GUI
Display Mode	Real Chrome window	Xvfb Virtual Display (RAM simulation)
Additional Dependencies	None	xvfb + PyVirtualDisplay
Login Xvfb	✅ Supported	✅ Supported
Song Creation Xvfb	❌ Not supported	✅ Supported
Environment Check	Basic	Incl. Xvfb/Chrome/Font Check

---

6. Technical Details

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

1. Never hardcode credentials — Always ask the user (prefer cookie import)
2. Xvfb must be installed — sudo apt install -y xvfb, otherwise it won't run in a headless environment
3. Real Chrome is required — Playwright's own Chromium can be detected by Google
4. Suno Free accounts have a daily point limit, approx. 100 points per song
5. Song generation typically takes 1-3 minutes
6. Each creation generates 2 different song versions
7. If Google login is rejected: wait 10-30 minutes, then try again
8. Gemini API Free limit: 15 Requests/Minute, 1500/Day
9. 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/