🎵 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:

CODEBLOCK0

Return values:

• - 0 = OK, logged in → songs can be created directly
• INLINECODE1 = Dependencies missing → installation required
• INLINECODE2 = Not logged in → start the login process

1. Install Dependencies (first time only)

1.1 System Dependencies

CODEBLOCK1

1.2 Python Dependencies

CODEBLOCK2

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):

CODEBLOCK5

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. 1. Gmail address
2. Gmail password

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

After user input:

CODEBLOCK6

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

CODEBLOCK7

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

2.4 Force Re-login

CODEBLOCK8

3. Create a Song

3.1 Prerequisites

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

Save it in an environment file:

CODEBLOCK9

Or as an environment variable:

CODEBLOCK10

3.3 hCaptcha Compatibility Patch

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

CODEBLOCK11

3.4 Song Creation Command

CODEBLOCK12

Read lyrics from a file:

CODEBLOCK13

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

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: INLINECODE22
• Ballad: INLINECODE23
• Electronic: INLINECODE24
• Hip-Hop: INLINECODE25

4. Complete Example

Example: Create a Rock Song on a Linux Server

CODEBLOCK14

5. Differences from the Original Version

6. Technical Details

Xvfb Virtual Display Solution

CODEBLOCK15

• - 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')
• INLINECODE30 maintains browser state (cookies, localStorage)
• INLINECODE31 + 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

CODEBLOCK16

7. Important Notes

1. 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

CODEBLOCK17