suno-helper/README.md

ChatGPT to Suno Tampermonkey Helper

ChatGPT가 만든 Version A/B/C 형식의 SUNO 프롬프트를 파싱해서 SUNO 입력칸에 붙여넣는 Tampermonkey userscript입니다.

설치

1. Chrome에 Tampermonkey를 설치합니다.
2. 아래 설치 URL을 엽니다.
3. Tampermonkey 설치 화면에서 Install을 누릅니다.

설치 URL:

https://git.mokaya.org/shkim/suno-helper/raw/branch/master/chatgpt-suno-tampermonkey.user.js

수동 설치가 필요하면 Tampermonkey 대시보드에서 새 스크립트를 만들고 chatgpt-suno-tampermonkey.user.js 내용을 붙여넣어 저장합니다.

자동 업데이트

스크립트 메타데이터의 @updateURL / @downloadURL이 공개 Gitea raw URL을 바라봅니다. 이후 @version을 올려서 master 브랜치에 push하면 Tampermonkey가 업데이트를 감지합니다.

현재 repo는 private=false 공개 상태입니다. 다만 Gitea 서버가 비로그인 사용자에게 저장소 보기를 막도록 설정되어 있으면 raw URL도 로그인 화면으로 이동하므로, 완전한 공개 자동 업데이트를 쓰려면 서버 설정에서 비로그인 저장소 보기가 허용되어야 합니다.

사용법

1. ChatGPT 답변 페이지에서 Version A/B/C 형식이 감지되면 오른쪽 위에 작은 ChatGPT -> Suno 패널이 나타납니다.
2. 원하는 버전의 S1 또는 S2 버튼을 눌러 슬롯에 저장합니다.
3. SUNO Create 페이지로 이동합니다.
4. 오른쪽 아래 Suno Prompt Paste 패널에서 슬롯을 고르고 선택 슬롯 붙여넣기를 누릅니다.

SUNO 화면 구조가 바뀌어 자동 입력이 실패하면, 패널의 Title, Style of Music, Lyrics, Exclude 버튼으로 개별 값을 클립보드에 복사해서 수동으로 붙여넣을 수 있습니다.

SUNO 다운로드

SUNO 곡 상세/플레이어 화면에서 WAV + 커버 + 메타 다운로드를 누르면 현재 페이지에서 감지된 곡 정보를 기준으로 아래 파일을 다운로드합니다.

SUNO 라이브러리 목록 화면에서는 라이브러리 곡 감지를 누른 뒤 처리용 manifest 저장을 누릅니다. 현재 브라우저에 로드된 곡 목록을 기준으로 처리하므로, 무한 스크롤 목록에서는 먼저 아래쪽까지 스크롤해서 곡을 로드해야 합니다.

• {title}.wav: clip id가 감지되면 https://cdn1.suno.ai/{clipId}.wav 후보를 내려받습니다.
• {title}.cover.*: 페이지에서 감지된 앨범아트 URL을 내려받습니다.
• {title}.metadata.json: title, clip id, audio/image URL, 감지된 원본 메타데이터, 현재 페이지 URL을 저장합니다.
• suno-library-{date}.manifest.json: 일괄 다운로드 시 감지된 전체 곡 목록을 저장합니다.

WAV 다운로드는 SUNO 계정 권한, 변환 준비 상태, CDN 접근 정책에 따라 실패할 수 있습니다. 이 경우 metadata JSON의 detectedAudioUrls, detectedImageUrls, detectedIds를 보고 실제 페이지에서 어떤 URL이 잡혔는지 확인할 수 있습니다.

로컬 FLAC 정리

브라우저는 \\VaultOfData\AKAMedia\음악\처리됨\SUNO 같은 로컬/NAS 경로에 직접 파일을 정리하거나 WAV를 FLAC으로 인코딩할 수 없습니다. 그래서 Tampermonkey는 manifest를 만들고, 로컬 PowerShell 스크립트가 실제 다운로드/변환/정리를 담당합니다.

1. SUNO 라이브러리에서 라이브러리 곡 감지를 누릅니다.
2. 처리용 manifest 저장을 눌러 Downloads 폴더에 suno-library-YYYY-MM-DD.manifest.json을 저장합니다. 이 단계에서 브라우저가 SUNO의 convert_wav/와 wav_file/ API를 호출해 WAV URL을 준비합니다.
3. run_process_suno_library.ps1을 실행합니다.

더 편한 흐름:

1. 먼저 run_suno_companion.ps1을 실행해서 로컬 수신 프로그램을 켜둡니다.
2. SUNO 라이브러리에서 라이브러리 곡 감지를 누릅니다.
3. 로컬 프로그램으로 처리를 누릅니다.

이 경우 Tampermonkey가 manifest를 http://127.0.0.1:17873/process로 보내고, 로컬 프로그램이 자동으로 다운로드/FLAC 변환/정리를 시작합니다.

기본 출력 위치:

\\VaultOfData\AKAMedia\음악\처리됨\SUNO\YYYY-MM-DD

로컬 처리기는 manifest에 저장된 WAV URL을 다운로드하고, 실패하면 manifest의 audio URL로 fallback합니다. 이후 ffmpeg로 FLAC 변환하면서 title, artist, album, genre/style, lyrics, Suno clip id, cover art를 메타데이터로 넣습니다.

로그는 companion-logs 폴더에 저장됩니다.