{
  "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": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/sunomaker",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=sunomaker",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "_meta.json",
      "check_env.sh",
      "export_cookies.py",
      "patch_hcaptcha.py",
      "requirements.txt"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "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."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "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."
        },
        {
          "label": "Upgrade existing",
          "body": "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."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-07T17:22:31.273Z",
      "expiresAt": "2026-05-14T17:22:31.273Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
        "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "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."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/sunomaker",
    "agentPageUrl": "https://openagent3.xyz/skills/sunomaker/agent",
    "manifestUrl": "https://openagent3.xyz/skills/sunomaker/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/sunomaker/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "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."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "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."
      },
      {
        "label": "Upgrade existing",
        "body": "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."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "🎵 SunoMaker - Automated Suno AI Music Generation",
        "body": "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.\n\nTwo core functions: Account Login (via Google OAuth) and Song Creation (custom lyrics + style + download)."
      },
      {
        "title": "0. Prerequisite Check",
        "body": "Before any operation, the environment must be checked:\n\nbash {baseDir}/suno-headless/check_env.sh\n\nReturn values:\n\n0 = OK, logged in → songs can be created directly\n1 = Dependencies missing → installation required\n2 = Not logged in → start the login process"
      },
      {
        "title": "1.1 System Dependencies",
        "body": "# Xvfb Virtual Display (core dependency for headless environments)\nsudo apt update && sudo apt install -y xvfb\n\n# Google Chrome Browser\nwget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -\necho \"deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main\" | sudo tee /etc/apt/sources.list.d/google-chrome.list\nsudo apt update && sudo apt install -y google-chrome-stable\n\n# Fonts for various languages\nsudo apt install -y fonts-noto-cjk"
      },
      {
        "title": "1.2 Python Dependencies",
        "body": "cd {baseDir}/suno-headless\npip3 install -r requirements.txt\nplaywright install"
      },
      {
        "title": "2. Login Process",
        "body": "⚠️ Important: Never hardcode credentials in the code! Always ask the user.\n\nTwo login methods are available:\n\nMethod A: Cookie Import (🌟 Recommended! Perfectly bypasses Google security checks)\nMethod B: Direct Email/Password Login (can trigger Google security prompts)"
      },
      {
        "title": "2.1 Method A: Cookie Import (Recommended)",
        "body": "The most stable login method for cloud servers. Completely bypasses Google's security checks.\n\nSteps:\n\nIf login is required, explain to the user:\n\n🍪 Recommended Cookie Import Method (bypasses Google security checks):\nStep 1: On your local computer (with a browser), run:\npip install playwright && playwright install\npython3 export_cookies.py\n\nA browser window will open. Log in to Suno manually. After a successful login, cookies will be exported automatically.\nStep 2: Upload the cookie file to the server:\nscp <exported-cookie-file> user@server:/root/suno_cookie/suno_cookies.json\n\nStep 3: After uploading, perform the import.\n\nAfter uploading, run the import (default path: /root/suno_cookie/suno_cookies.json):\n\ncd {baseDir}/suno-headless\npython3 suno_login.py --import-cookies"
      },
      {
        "title": "2.2 Method B: Email/Password Login",
        "body": "⚠️ Caution: On cloud servers, this can trigger Google security prompts. Prefer Method A.\n\nIf login is required, always ask the user:\n\nSuno.com login required (via Google account). Please provide:\n\nGmail address\nGmail password\n\n⚠️ Credentials are only used for this login, not stored or shared with third parties.\n\nAfter user input:\n\ncd {baseDir}/suno-headless\npython3 suno_login.py --email \"<user-email>\" --password \"<user-password>\"\n\nHeadless Linux Mode Explanation:\n\nThe script automatically detects a GUI-free environment (no $DISPLAY variable)\nIt automatically starts an Xvfb Virtual Display, simulating a display in memory\nChrome runs in GUI mode (headless=False), but nothing is displayed on the screen\nThis bypasses Google's headless browser detection"
      },
      {
        "title": "2.3 Check Login Status",
        "body": "cd {baseDir}/suno-headless\npython3 suno_login.py --check-only\n\nExit codes: 0 = Logged in, 2 = Not logged in"
      },
      {
        "title": "2.4 Force Re-login",
        "body": "# Method A: Re-import cookies\ncd {baseDir}/suno-headless\npython3 suno_login.py --import-cookies \"<new-cookie-file>\"\n\n# Method B: Re-enter email/password\ncd {baseDir}/suno-headless\npython3 suno_login.py --email \"<email>\" --password \"<password>\" --force-login"
      },
      {
        "title": "3.1 Prerequisites",
        "body": "Logged in (suno_login.py --check-only returns 0)\nGemini API Key required (for automatic hCaptcha solving)"
      },
      {
        "title": "3.2 Get a Gemini API Key",
        "body": "If the user does not have a Gemini API Key:\n\nWhen creating a song, Suno shows captchas. A Gemini API Key is required for automatic solving.\n\nVisit https://aistudio.google.com/app/apikey\nClick \"Create API key\"\nCopy the generated key\n\nSave it in an environment file:\n\nmkdir -p ~/.suno\necho \"GEMINI_API_KEY=<user-key>\" > ~/.suno/.env\n\nOr as an environment variable:\n\nexport GEMINI_API_KEY=\"<user-key>\""
      },
      {
        "title": "3.3 hCaptcha Compatibility Patch",
        "body": "Run this once before the first use (Suno uses its own hCaptcha domain, a patch is required):\n\ncd {baseDir}/suno-headless\npython3 patch_hcaptcha.py"
      },
      {
        "title": "3.4 Song Creation Command",
        "body": "cd {baseDir}/suno-headless\npython3 suno_create_song.py \\\n  --lyrics \"<lyrics-content>\" \\\n  --style \"<music-style-tags>\" \\\n  --title \"<song-title>\" \\\n  --output-dir \"<download-dir>\"\n\nRead lyrics from a file:\n\ncd {baseDir}/suno-headless\npython3 suno_create_song.py \\\n  --lyrics-file \"<lyrics-file-path>\" \\\n  --style \"<music-style-tags>\" \\\n  --title \"<song-title>\"\n\nHeadless Mode Explanation:\n\nsuno_create_song.py automatically detects a GUI-free environment\nIt automatically starts an Xvfb Virtual Display, running Chrome in GUI mode in the virtual display\nAfter the script finishes, the Virtual Display is automatically closed, no manual action needed"
      },
      {
        "title": "3.5 Parameter Explanation",
        "body": "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"
      },
      {
        "title": "3.6 Music Style Tags Reference",
        "body": "Common style tags (English, combinable):\n\nGenres: rock, pop, jazz, blues, electronic, hip-hop, R&B, classical, folk, metal, country, reggae, latin, indie\nInstruments: electric guitar, acoustic guitar, piano, synthesizer, drums, bass, violin, saxophone, trumpet\nMood: energetic, emotional, melancholic, upbeat, dark, dreamy, aggressive, peaceful, romantic\nVocals: male vocals, female vocals, choir, rap, whisper, powerful vocals, falsetto\nLanguage: german, english, french, spanish, chinese, japanese\nOther: fast tempo, slow tempo, instrumental, lo-fi, cinematic, epic\n\nExamples:\n\nRock: rock, electric guitar, energetic, male vocals, english\nBallad: pop, piano, emotional, female vocals, slow tempo, english\nElectronic: electronic, synthesizer, upbeat, fast tempo, dance\nHip-Hop: hip-hop, rap, bass, drums, energetic, english"
      },
      {
        "title": "Example: Create a Rock Song on a Linux Server",
        "body": "# 1. Check environment (automatically detects Xvfb, Chrome, etc.)\nbash {baseDir}/suno-headless/check_env.sh\n\n# 2. If not logged in, use the cookie import method (recommended)\n#    Step 1: Run export_cookies.py on the local computer\n#    Step 2: scp <cookie-file> user@server:/root/suno_cookie/suno_cookies.json\n#    Step 3: Import on the server (default: /root/suno_cookie/suno_cookies.json)\ncd {baseDir}/suno-headless\npython3 suno_login.py --import-cookies\n\n# Or use the email/password method (can trigger Google security prompts)\n# python3 suno_login.py --email \"user@gmail.com\" --password \"password123\"\n\n# 3. Apply hCaptcha patch\npython3 patch_hcaptcha.py\n\n# 4. Create song (automatically with Xvfb Virtual Display)\npython3 suno_create_song.py \\\n  --lyrics \"The sun rises over the city\nA new day is dawning\nWe walk through the streets\nAnd sing our song\" \\\n  --style \"rock, electric guitar, energetic, male vocals, english\" \\\n  --title \"Morning Song Rock Version\""
      },
      {
        "title": "5. Differences from the Original Version",
        "body": "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"
      },
      {
        "title": "Xvfb Virtual Display Solution",
        "body": "┌─────────────────────────────────────────┐\n│          Linux Server (no monitor)      │\n│                                         │\n│  ┌─────────────┐    ┌────────────────┐  │\n│  │   Xvfb      │    │  Chrome        │  │\n│  │ (Virtual    │◄───│ (GUI Mode)     │  │\n│  │  Display)   │    │ headless=False │  │\n│  │ :99 1280x800│    └────────────────┘  │\n│  └─────────────┘           │             │\n│        ▲                   │             │\n│        │              Automated          │\n│   PyVirtualDisplay     Suno.com Control  │\n│   Auto-Lifecycle            │             │\n│        │                   ▼             │\n│        │            ┌────────────────┐   │\n│        │            │ Song Generation│   │\n│        │            │ + Download     │   │\n│        │            └────────────────┘   │\n└────────┼────────────────────────────────┘\n         │\n         ▼\n     Memory (RAM)\n\nWhy not headless=True? Google OAuth detects headless browsers and blocks logins\nXvfb solution: Creates a virtual X11 display in RAM, Chrome \"thinks\" there's a real GUI, so Google can't detect the automation\nAuto-detection: The script checks the $DISPLAY environment variable and starts Xvfb automatically if no GUI is present\nResources: Xvfb uses minimal RAM and is automatically released after the script finishes"
      },
      {
        "title": "Login Solution",
        "body": "Playwright + Real Chrome browser (channel='chrome')\npersistent context maintains browser state (cookies, localStorage)\nheadless=False + Xvfb Virtual Display bypasses Google's anti-automation\nAfter the first login, the session is maintained through the persistent context"
      },
      {
        "title": "Song Creation Solution",
        "body": "Browser automation controls the suno.com/create page\nhcaptcha-challenger + Gemini API solves hCaptcha automatically\nNew clip ID is obtained by intercepting browser network responses\nSuno's internal API (studio-api.prod.suno.com) polls the song generation status\nAutomatic MP3 download upon completion"
      },
      {
        "title": "File Structure",
        "body": "suno-headless/\n├── suno_login.py          # Login tool (Google OAuth / Cookie Import + Xvfb)\n├── suno_create_song.py    # Song creation + download (Xvfb support)\n├── export_cookies.py      # Cookie export tool (run on local computer)\n├── patch_hcaptcha.py      # hCaptcha domain compatibility patch\n├── check_env.sh           # Environment check (incl. Xvfb/Chrome check)\n├── requirements.txt       # Python dependencies (incl. PyVirtualDisplay)\n└── SKILL.md               # This documentation"
      },
      {
        "title": "7. Important Notes",
        "body": "Never hardcode credentials — Always ask the user (prefer cookie import)\nXvfb must be installed — sudo apt install -y xvfb, otherwise it won't run in a headless environment\nReal Chrome is required — Playwright's own Chromium can be detected by Google\nSuno Free accounts have a daily point limit, approx. 100 points per song\nSong generation typically takes 1-3 minutes\nEach creation generates 2 different song versions\nIf Google login is rejected: wait 10-30 minutes, then try again\nGemini API Free limit: 15 Requests/Minute, 1500/Day\nhCaptcha may take several attempts, success rate depends on Gemini's image recognition"
      },
      {
        "title": "8. Troubleshooting",
        "body": "# Check environment (incl. Xvfb status)\nbash {baseDir}/suno-headless/check_env.sh\n\n# Test Xvfb manually\nXvfb :99 -screen 0 1280x800x24 &\nDISPLAY=:99 google-chrome --no-sandbox --version\nkill %1\n\n# View login screenshots\nls -la /tmp/suno_debug_*.png\n\n# Check persistent context\nls -la ~/.suno/chrome_gui_profile/\n\n# View cookies\npython3 -c \"import json; d=json.load(open('$HOME/.suno/cookies.json')); print(f'{len(d)} cookies')\"\n\n# Check Gemini API Key\ncat ~/.suno/.env\n\n# View downloaded songs\nls -la {baseDir}/output_mp3/"
      }
    ],
    "body": "🎵 SunoMaker - Automated Suno AI Music Generation\n\nDesigned 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.\n\nTwo core functions: Account Login (via Google OAuth) and Song Creation (custom lyrics + style + download).\n\n0. Prerequisite Check\n\nBefore any operation, the environment must be checked:\n\nbash {baseDir}/suno-headless/check_env.sh\n\n\nReturn values:\n\n0 = OK, logged in → songs can be created directly\n1 = Dependencies missing → installation required\n2 = Not logged in → start the login process\n1. Install Dependencies (first time only)\n1.1 System Dependencies\n# Xvfb Virtual Display (core dependency for headless environments)\nsudo apt update && sudo apt install -y xvfb\n\n# Google Chrome Browser\nwget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -\necho \"deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main\" | sudo tee /etc/apt/sources.list.d/google-chrome.list\nsudo apt update && sudo apt install -y google-chrome-stable\n\n# Fonts for various languages\nsudo apt install -y fonts-noto-cjk\n\n1.2 Python Dependencies\ncd {baseDir}/suno-headless\npip3 install -r requirements.txt\nplaywright install\n\n2. Login Process\n\n⚠️ Important: Never hardcode credentials in the code! Always ask the user.\n\nTwo login methods are available:\n\nMethod A: Cookie Import (🌟 Recommended! Perfectly bypasses Google security checks)\nMethod B: Direct Email/Password Login (can trigger Google security prompts)\n2.1 Method A: Cookie Import (Recommended)\n\nThe most stable login method for cloud servers. Completely bypasses Google's security checks.\n\nSteps:\n\nIf login is required, explain to the user:\n\n🍪 Recommended Cookie Import Method (bypasses Google security checks):\n\nStep 1: On your local computer (with a browser), run:\n\npip install playwright && playwright install\npython3 export_cookies.py\n\n\nA browser window will open. Log in to Suno manually. After a successful login, cookies will be exported automatically.\n\nStep 2: Upload the cookie file to the server:\n\nscp <exported-cookie-file> user@server:/root/suno_cookie/suno_cookies.json\n\n\nStep 3: After uploading, perform the import.\n\nAfter uploading, run the import (default path: /root/suno_cookie/suno_cookies.json):\n\ncd {baseDir}/suno-headless\npython3 suno_login.py --import-cookies\n\n2.2 Method B: Email/Password Login\n\n⚠️ Caution: On cloud servers, this can trigger Google security prompts. Prefer Method A.\n\nIf login is required, always ask the user:\n\nSuno.com login required (via Google account). Please provide:\n\nGmail address\nGmail password\n\n⚠️ Credentials are only used for this login, not stored or shared with third parties.\n\nAfter user input:\n\ncd {baseDir}/suno-headless\npython3 suno_login.py --email \"<user-email>\" --password \"<user-password>\"\n\n\nHeadless Linux Mode Explanation:\n\nThe script automatically detects a GUI-free environment (no $DISPLAY variable)\nIt automatically starts an Xvfb Virtual Display, simulating a display in memory\nChrome runs in GUI mode (headless=False), but nothing is displayed on the screen\nThis bypasses Google's headless browser detection\n2.3 Check Login Status\ncd {baseDir}/suno-headless\npython3 suno_login.py --check-only\n\n\nExit codes: 0 = Logged in, 2 = Not logged in\n\n2.4 Force Re-login\n# Method A: Re-import cookies\ncd {baseDir}/suno-headless\npython3 suno_login.py --import-cookies \"<new-cookie-file>\"\n\n# Method B: Re-enter email/password\ncd {baseDir}/suno-headless\npython3 suno_login.py --email \"<email>\" --password \"<password>\" --force-login\n\n3. Create a Song\n3.1 Prerequisites\nLogged in (suno_login.py --check-only returns 0)\nGemini API Key required (for automatic hCaptcha solving)\n3.2 Get a Gemini API Key\n\nIf the user does not have a Gemini API Key:\n\nWhen creating a song, Suno shows captchas. A Gemini API Key is required for automatic solving.\n\nVisit https://aistudio.google.com/app/apikey\nClick \"Create API key\"\nCopy the generated key\n\nSave it in an environment file:\n\nmkdir -p ~/.suno\necho \"GEMINI_API_KEY=<user-key>\" > ~/.suno/.env\n\n\nOr as an environment variable:\n\nexport GEMINI_API_KEY=\"<user-key>\"\n\n3.3 hCaptcha Compatibility Patch\n\nRun this once before the first use (Suno uses its own hCaptcha domain, a patch is required):\n\ncd {baseDir}/suno-headless\npython3 patch_hcaptcha.py\n\n3.4 Song Creation Command\ncd {baseDir}/suno-headless\npython3 suno_create_song.py \\\n  --lyrics \"<lyrics-content>\" \\\n  --style \"<music-style-tags>\" \\\n  --title \"<song-title>\" \\\n  --output-dir \"<download-dir>\"\n\n\nRead lyrics from a file:\n\ncd {baseDir}/suno-headless\npython3 suno_create_song.py \\\n  --lyrics-file \"<lyrics-file-path>\" \\\n  --style \"<music-style-tags>\" \\\n  --title \"<song-title>\"\n\n\nHeadless Mode Explanation:\n\nsuno_create_song.py automatically detects a GUI-free environment\nIt automatically starts an Xvfb Virtual Display, running Chrome in GUI mode in the virtual display\nAfter the script finishes, the Virtual Display is automatically closed, no manual action needed\n3.5 Parameter Explanation\nParameter\tDescription\tRequired\tDefault Value\n--lyrics\tSong lyrics (alternative to --lyrics-file)\t✅\t-\n--lyrics-file\tPath to the lyrics file (alternative to --lyrics)\t✅\t-\n--style\tMusic style tags (English, comma-separated)\t❌\trock, electric guitar, energetic, male vocals\n--title\tSong title\t❌\tMy Song\n--output-dir\tMP3 download directory\t❌\t{baseDir}/output_mp3\n--gemini-key\tGemini API Key (alternatively: environment variable or ~/.suno/.env)\t❌\tAuto-Read\n3.6 Music Style Tags Reference\n\nCommon style tags (English, combinable):\n\nGenres: rock, pop, jazz, blues, electronic, hip-hop, R&B, classical, folk, metal, country, reggae, latin, indie\nInstruments: electric guitar, acoustic guitar, piano, synthesizer, drums, bass, violin, saxophone, trumpet\nMood: energetic, emotional, melancholic, upbeat, dark, dreamy, aggressive, peaceful, romantic\nVocals: male vocals, female vocals, choir, rap, whisper, powerful vocals, falsetto\nLanguage: german, english, french, spanish, chinese, japanese\nOther: fast tempo, slow tempo, instrumental, lo-fi, cinematic, epic\n\nExamples:\n\nRock: rock, electric guitar, energetic, male vocals, english\nBallad: pop, piano, emotional, female vocals, slow tempo, english\nElectronic: electronic, synthesizer, upbeat, fast tempo, dance\nHip-Hop: hip-hop, rap, bass, drums, energetic, english\n4. Complete Example\nExample: Create a Rock Song on a Linux Server\n# 1. Check environment (automatically detects Xvfb, Chrome, etc.)\nbash {baseDir}/suno-headless/check_env.sh\n\n# 2. If not logged in, use the cookie import method (recommended)\n#    Step 1: Run export_cookies.py on the local computer\n#    Step 2: scp <cookie-file> user@server:/root/suno_cookie/suno_cookies.json\n#    Step 3: Import on the server (default: /root/suno_cookie/suno_cookies.json)\ncd {baseDir}/suno-headless\npython3 suno_login.py --import-cookies\n\n# Or use the email/password method (can trigger Google security prompts)\n# python3 suno_login.py --email \"user@gmail.com\" --password \"password123\"\n\n# 3. Apply hCaptcha patch\npython3 patch_hcaptcha.py\n\n# 4. Create song (automatically with Xvfb Virtual Display)\npython3 suno_create_song.py \\\n  --lyrics \"The sun rises over the city\nA new day is dawning\nWe walk through the streets\nAnd sing our song\" \\\n  --style \"rock, electric guitar, energetic, male vocals, english\" \\\n  --title \"Morning Song Rock Version\"\n\n5. Differences from the Original Version\nFeature\tsuno (Original)\tsuno-headless (This Version)\nTarget Environment\tmacOS / Linux with GUI\tLinux Server without GUI\nDisplay Mode\tReal Chrome window\tXvfb Virtual Display (RAM simulation)\nAdditional Dependencies\tNone\txvfb + PyVirtualDisplay\nLogin Xvfb\t✅ Supported\t✅ Supported\nSong Creation Xvfb\t❌ Not supported\t✅ Supported\nEnvironment Check\tBasic\tIncl. Xvfb/Chrome/Font Check\n6. Technical Details\nXvfb Virtual Display Solution\n┌─────────────────────────────────────────┐\n│          Linux Server (no monitor)      │\n│                                         │\n│  ┌─────────────┐    ┌────────────────┐  │\n│  │   Xvfb      │    │  Chrome        │  │\n│  │ (Virtual    │◄───│ (GUI Mode)     │  │\n│  │  Display)   │    │ headless=False │  │\n│  │ :99 1280x800│    └────────────────┘  │\n│  └─────────────┘           │             │\n│        ▲                   │             │\n│        │              Automated          │\n│   PyVirtualDisplay     Suno.com Control  │\n│   Auto-Lifecycle            │             │\n│        │                   ▼             │\n│        │            ┌────────────────┐   │\n│        │            │ Song Generation│   │\n│        │            │ + Download     │   │\n│        │            └────────────────┘   │\n└────────┼────────────────────────────────┘\n         │\n         ▼\n     Memory (RAM)\n\nWhy not headless=True? Google OAuth detects headless browsers and blocks logins\nXvfb solution: Creates a virtual X11 display in RAM, Chrome \"thinks\" there's a real GUI, so Google can't detect the automation\nAuto-detection: The script checks the $DISPLAY environment variable and starts Xvfb automatically if no GUI is present\nResources: Xvfb uses minimal RAM and is automatically released after the script finishes\nLogin Solution\nPlaywright + Real Chrome browser (channel='chrome')\npersistent context maintains browser state (cookies, localStorage)\nheadless=False + Xvfb Virtual Display bypasses Google's anti-automation\nAfter the first login, the session is maintained through the persistent context\nSong Creation Solution\nBrowser automation controls the suno.com/create page\nhcaptcha-challenger + Gemini API solves hCaptcha automatically\nNew clip ID is obtained by intercepting browser network responses\nSuno's internal API (studio-api.prod.suno.com) polls the song generation status\nAutomatic MP3 download upon completion\nFile Structure\nsuno-headless/\n├── suno_login.py          # Login tool (Google OAuth / Cookie Import + Xvfb)\n├── suno_create_song.py    # Song creation + download (Xvfb support)\n├── export_cookies.py      # Cookie export tool (run on local computer)\n├── patch_hcaptcha.py      # hCaptcha domain compatibility patch\n├── check_env.sh           # Environment check (incl. Xvfb/Chrome check)\n├── requirements.txt       # Python dependencies (incl. PyVirtualDisplay)\n└── SKILL.md               # This documentation\n\n7. Important Notes\nNever hardcode credentials — Always ask the user (prefer cookie import)\nXvfb must be installed — sudo apt install -y xvfb, otherwise it won't run in a headless environment\nReal Chrome is required — Playwright's own Chromium can be detected by Google\nSuno Free accounts have a daily point limit, approx. 100 points per song\nSong generation typically takes 1-3 minutes\nEach creation generates 2 different song versions\nIf Google login is rejected: wait 10-30 minutes, then try again\nGemini API Free limit: 15 Requests/Minute, 1500/Day\nhCaptcha may take several attempts, success rate depends on Gemini's image recognition\n8. Troubleshooting\n# Check environment (incl. Xvfb status)\nbash {baseDir}/suno-headless/check_env.sh\n\n# Test Xvfb manually\nXvfb :99 -screen 0 1280x800x24 &\nDISPLAY=:99 google-chrome --no-sandbox --version\nkill %1\n\n# View login screenshots\nls -la /tmp/suno_debug_*.png\n\n# Check persistent context\nls -la ~/.suno/chrome_gui_profile/\n\n# View cookies\npython3 -c \"import json; d=json.load(open('$HOME/.suno/cookies.json')); print(f'{len(d)} cookies')\"\n\n# Check Gemini API Key\ncat ~/.suno/.env\n\n# View downloaded songs\nls -la {baseDir}/output_mp3/"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/Vitja1988/sunomaker",
    "publisherUrl": "https://clawhub.ai/Vitja1988/sunomaker",
    "owner": "Vitja1988",
    "version": "1.1.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "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"
  }
}