YuE2 로컬 음악 생성 웹 UI 사용 설명서

확인일: 2026-09-24 · 주소: http://127.0.0.1:8087/

이 문서는 현재 설치된 yue2.cpp 내장 Web UI를 설명합니다. 폴더 이름은 YuE2-Groove이지만 GROOVE의 Python UI나 VoiceStudio 화면은 아닙니다. 화면의 접힌 설정, 저장 대화상자, 생성 결과 메뉴까지 포함합니다.

• 화면 버전 표시: 27e48f9 (2026-09-15)
• 실행 서버 /props 버전: e8b39f7 (2026-09-18) — 화면과 서버의 버전 표기가 다릅니다.
• 모델: YuE2-3B-Q8_0.gguf + YuE2-Vae-F32.gguf
• 오디오 출력: 48 kHz 스테레오
• 아래 기본값은 현재 서버가 반환하는 값입니다. 추천값은 별도로 표시하며, 모든 곡에서 품질이나 12GB 이하 사용량을 보장하지는 않습니다.

1. 처음 사용할 때

1. Name에 곡 이름을 적습니다.
2. Style에 언어·장르·악기·보컬·분위기를 적습니다.
3. Lyrics에 가사를 넣습니다. [Verse], [Chorus] 등으로 구간을 구분할 수 있습니다.
4. 새 곡은 Score와 Audio codes를 비웁니다.
5. Mode = Full, LM batch = 1, 고급 설정의 Batch = 1로 시작합니다.
6. 짧은 시험은 Duration = 60, Steps = 16; 최종 시도는 Steps = 32를 기준으로 삼습니다.
7. Generate를 누르고 결과 카드가 나타날 때까지 기다립니다.
8. 결과의 Menu → Download audio로 음원을 저장합니다. 재현용 설정도 필요하면 Edit prompt → Save → JSON으로 따로 저장합니다.

숫자 칸에 흐리게 보이는 값은 기본값 안내(placeholder)입니다. 빈칸은 0이 아니라 서버 기본값을 사용한다는 뜻입니다. 설정을 접는 것만으로 값이 초기화되지는 않습니다.

2. 상단 도구와 화면 설정

옵션	설명	사용법·주의
Dark	어두운 화면 테마	화면 표시만 바뀌며 생성 음질에는 영향이 없습니다.
스피커 옆 슬라이더	웹페이지 재생 음량, 0~1	현재 확인값 0.5. 다운로드 음원의 음량을 바꾸는 기능은 아닙니다.
Open	저장한 프롬프트 또는 오디오 열기	.json, .yaml, .yml 설정을 불러옵니다. .mp3, .wav도 결과 카드로 가져올 수 있습니다. 오디오를 열기만 해서는 자동 채보되지 않습니다.
Save	현재 입력 설정 저장	Save format 창에서 JSON 또는 YAML 선택. 음원 저장이 아닙니다.
Save format → JSON	구조화된 설정 파일 저장	재사용·문제 재현에 적합합니다.
Save format → YAML	읽고 편집하기 쉬운 설정 파일 저장	들여쓰기가 의미를 가지므로 편집 시 주의합니다.
Save format → Cancel	저장 대화상자 닫기	생성 작업의 Cancel과 다릅니다.
Reset	이름과 프롬프트 입력 초기화	작성 중인 입력이 지워집니다. 결과 음원 목록을 지우는 버튼은 아닙니다. 먼저 Save 권장.

파일은 브라우저 다운로드 위치에 저장됩니다. 모델을 D:에 설치했다고 다운로드도 자동으로 D:에 저장되는 것은 아닙니다. 저장 후 실제 경로를 확인하세요.

3. 기본 입력: Name / Style / Lyrics / Score

항목	의미	작성법
Name	결과를 구별하는 곡 이름	예: 僕らの夏は終わらない. 음악 스타일 지시가 아니라 이름표로 생각하면 됩니다.
Style	음악 생성 지시문	언어, 장르, 템포 느낌, 악기, 보컬, 녹음 분위기를 구체적으로 적습니다. 서로 충돌하는 요구를 너무 많이 넣지 않는 편이 좋습니다.
Lyrics	실제로 부를 가사	원하는 언어로 입력합니다. 반복 후렴은 실제 가사를 다시 적는 편이 명확합니다. 괄호 속 연출 지시가 실제로 불리거나 무시될 수도 있습니다.
Score	ABC 표기법의 텍스트 악보	점수·평가가 아닙니다. 멜로디와 코드의 설계도입니다. 새 작곡은 빈칸으로 두면 모델이 작성합니다.
Clear score (×)	Score만 비우기	Style과 Lyrics는 유지됩니다. Audio codes는 별도로 지워야 완전히 새 연주를 만들 수 있습니다.

일본 청춘 콘서트 스타일 예시

Japanese youth pop rock, live summer concert, uplifting and emotional,
energetic band, bright electric guitars, driving drums, melodic bass,
expressive lead vocal, huge sing-along chorus, audience chanting woah-oh,
call and response, handclaps, live crowd ambience, nostalgic hopeful finale

관중 합창·박수·현장감은 생성 지시일 뿐 보장되는 개별 트랙이 아닙니다. 가사 후렴에 ウォーオー처럼 실제로 부를 짧은 구절을 반복하면 의도를 더 명확하게 전달할 수 있습니다. 이 화면에는 관중 음량만 따로 조절하는 믹서가 없습니다.

Score 간단 예시

X:1
L:1/8
M:4/4
K:Cmaj
"C"c2 e2 g2 c'2|

M은 박자, L은 기본 음 길이, K는 조성, 따옴표 안의 C는 코드입니다. 이는 짧은 문법 예시이지 완성된 노래 악보가 아닙니다. ABC에 익숙하지 않다면 직접 작성하지 말고 생성 결과의 악보를 재사용하세요.

4. LM configuration — 곡의 설계와 길이

LM은 악보와 음악 토큰을 순서대로 생성하는 단계입니다.

옵션	기본값	의미와 사용법
Mode	Full	아래 세 모드 중 선택합니다.
Duration	360초	목표 길이/생성 예산입니다. 정확히 해당 길이를 보장하지 않으며 먼저 끝날 수 있습니다. Semantic Max tokens와 함께 길이를 제한합니다.
LM batch	1	서로 다른 악보·음악 토큰을 가진 곡의 개수. 현재 실행기는 --max-batch 1이므로 1로 사용합니다.
LM seed	-1	악보·멜로디·길이 등을 결정하는 토큰 샘플링 난수값. -1은 무작위, 42 같은 고정 정수는 비교 실험용입니다.
Clear LM configuration (×)	—	이 그룹의 명시적 입력을 비워 기본 설정으로 돌립니다.

Mode 세 가지

화면 표시	의미	선택할 때
Full: the score carries the chords	코드가 포함된 악보 사용/생성	일반적인 새 곡의 출발점. 코드 포함 Score를 넣을 때도 선택합니다.
Melody: the score carries no chords	코드 없는 멜로디 악보 사용/생성	멜로디 중심 악보를 제공하거나 화성의 자유도를 남기고 싶을 때.
Off: no score, written or supplied	악보 단계를 사용하지 않음	악보 없이 직접 음악 토큰을 생성하는 실험용. Score를 활용하려면 선택하지 않습니다.

Full은 단순히 반주를 켜는 옵션이 아니며 Melody도 무반주 보컬 모드가 아닙니다.

5. Score sampling — 악보 생성 방식

Score를 자동 작성하는 단계의 설정입니다. 이미 악보를 제공했거나 악보 단계를 생략했다면 이 값을 바꿔도 새 악보 샘플링 효과를 기대할 수 없습니다.

옵션	기본값	설명·사용법
Temperature	0.7	선택의 무작위성. 낮추면 보수적, 높이면 다양해지는 경향. 먼저 기본값을 쓰세요.
Top P	0.9	누적 확률 기준으로 후보를 좁힙니다. 낮을수록 선택 폭이 좁아집니다.
Top K	30	확률이 높은 상위 K개 후보만 고려합니다. 작은 값은 선택을 제한합니다.
Repetition penalty	1.005	최근 토큰의 반복 억제 정도. 1은 억제 없음. 너무 높이면 필요한 음악적 반복도 방해할 수 있습니다.
Penalty window	100	반복 억제에 참고할 최근 토큰 수. 단위는 초가 아닙니다.
Min tokens	32	정상 종료 토큰을 허용하기 전의 최소 악보 토큰 수. 최소 곡 길이가 아닙니다.
Max tokens	4096	악보 토큰 생성 상한. 과도하게 낮추면 악보가 중간에 잘릴 수 있습니다.
Clear score sampling (×)	—	위 7개 설정을 비워 기본값으로 돌립니다. Score 텍스트는 지우지 않습니다.

악보 토큰은 텍스트 단위이므로 악보 토큰 ÷ 25 = 초로 계산하면 안 됩니다.

6. Semantic sampling — 실제 음악 진행 생성

악보·가사·스타일을 바탕으로 노래의 시간 흐름을 담은 음악 토큰을 만듭니다.

옵션	기본값	설명·사용법
CFG scale	-1	조건 유도 강도. -1은 자동 규칙이며, 아래 설명 참고.
Temperature	1.0	음악 토큰 선택의 다양성. 극단적인 증가는 불안정한 결과를 낼 수 있습니다.
Top P	0.95	누적 확률 기반 후보 제한. 우선 기본값 유지.
Top K	100	상위 후보 개수. 우선 기본값 유지.
Repetition penalty	1.2	최근 음악 토큰 반복 억제. 후렴 반복을 직접 제어하는 옵션은 아닙니다.
Penalty window	50	최근 몇 토큰에 반복 억제를 적용할지 결정합니다.
Min tokens	200	정상 조기 종료를 막는 최소 토큰 수. 25토큰/초이므로 대략 8초에 해당합니다.
Max tokens	9000	음악 토큰 상한. 약 360초에 해당합니다. 상한에 닿으면 자연스러운 마무리 전에 잘릴 수 있습니다.
Audio codes	빈칸	기존 노래의 음악 토큰. 새 곡은 비우고, 같은 연주의 재합성에는 유지합니다. 수동 편집 비권장.
Clear semantic sampling (×)	—	CFG, 샘플링 값과 Audio codes도 함께 비웁니다. Score는 유지됩니다.

CFG scale에서 중요한 점

• 자동값 -1: Full/Melody는 실제 CFG 1.0, Off는 1.01을 사용합니다.
• 정확히 1.0: 단일 분기를 사용하므로 이 단계의 계산·캐시 부담이 줄어듭니다.
• 1.0과 다른 값: 두 분기를 사용하는 경로로 바뀝니다. 1.01도 1.0과 메모리 비용이 같지 않습니다.
• 크게 설정한다고 무조건 더 좋은 음악이 나오지는 않습니다. 12GB에서는 우선 1을 사용하세요.
• 화면에 있는 CFG는 Semantic 단계 설정입니다. 별도의 음향 합성 CFG 조절기는 아닙니다.

길이 설정의 관계

실제 길이는 대략 Duration과 Semantic Max tokens ÷ 25 중 작은 예산 안에서 정해집니다. 모델의 종료 판단에 따라 더 짧아집니다.

목표 예산	Duration	Semantic Max tokens의 대응값
1분	60	약 1500
2분	120	약 3000
3분	180	약 4500
4분	240	약 6000
6분	360	약 9000

보통 Max tokens는 기본 9000으로 두고 Duration만 줄여도 됩니다. 토큰 수와 초의 변환에는 종료 처리에 따른 작은 차이가 있을 수 있습니다. 목표 시간을 채우려고 Min tokens를 무리하게 올리면 반복이나 부자연스러운 연장이 생길 수 있습니다.

두 샘플링 그룹의 입력 범위

서버 검증 기준: Temperature 0

5, Top P는 0 초과

1 이하, Top K는 1 이상 정수, Repetition penalty는 양수, Penalty window는 1

100 정수, Max tokens는 1 이상 정수, Min tokens는 0

Max tokens 정수입니다. 허용 범위가 곧 권장 범위는 아닙니다. 숫자 칸에는 단위 없이 숫자만 넣으세요.

7. Advanced and post-processing — 소리 합성과 파일 출력

옵션	기본값	설명·사용법
Steps	32	음악 토큰을 소리의 잠재 표현으로 만드는 반복 계산 횟수. 16은 빠른 시험용, 32는 기본 최종값. 늘리면 느려지며 음질이 반드시 좋아지지는 않습니다.
Batch	1	동일한 음악 토큰에서 음향 노이즈를 바꾼 변형 개수. UI 도움말상 최대 9. 12GB에서는 1 권장.
Noise seed	-1	음향 합성의 초기 노이즈값. -1은 무작위. 같은 Audio codes에서 이 값만 바꾸면 같은 곡의 다른 음향 렌더링을 비교할 수 있습니다.
Peak clip	10	출력 정규화에서 극소수의 큰 피크를 잘라 음량을 확보하는 값. dB나 퍼센트를 직접 적는 칸이 아닙니다.
MP3 bitrate	128	MP3 압축 비트레이트, kbps 단위. WAV에는 적용되지 않습니다. 압축 손실을 줄이려면 예를 들어 192/256/320을 고려할 수 있지만 원래 생성 품질을 복구하지는 못합니다.
Format	MP3	MP3, WAV16, WAV24, WAV32 중 선택.
Clear advanced and post-processing (×)	—	Steps, Batch, Noise seed, Peak clip, MP3 bitrate를 비웁니다. Format은 별도 상태이므로 직접 확인하세요.

Peak clip의 정확한 의미

출력 샘플 절댓값의 특정 백분위수를 기준으로 음량을 맞춘 후 초과 피크를 자릅니다. 구현은 0~999로 제한합니다.

• 0: 가장 큰 피크 기준 정규화. 이 정규화 과정의 피크 클리핑을 피하려는 경우.
• 10: 기본값. 상위 약 0.001% 샘플의 피크를 클리핑하는 기준.
• 999: 상위 약 0.0999% 기준. 음량은 커질 수 있지만 왜곡 위험이 늘어납니다.

처음에는 10을 유지하고 왜곡이 의심되면 0과 비교하세요. WAV32는 이 정규화 자체를 건너뜁니다.

Format 선택

형식	특징	용도
MP3	손실 압축, 작은 파일	빠른 감상·공유. bitrate 적용.
WAV16	16비트 PCM, 정규화 적용	범용 무손실 파일.
WAV24	24비트 PCM, 정규화 적용	후속 편집용으로 무난한 선택.
WAV32	32비트 부동소수점 원시 출력, 정규화 없음	DAW에서 직접 게인·마스터링할 때. 피크가 일반 재생 범위를 넘을 수 있으므로 주의.

비트 수가 높다고 작곡·가창 성능 자체가 좋아지지는 않습니다.

Seed와 Batch를 구별하는 방법

비교	LM 쪽	음향 합성 쪽
Seed	LM seed: 악보와 음악 진행 선택	Noise seed: 같은 진행의 음향 렌더링
Batch	LM batch: 다른 곡 여러 개	Batch: 같은 곡의 음향 변형 여러 개

일반적으로 총 결과 수는 LM batch × Batch입니다. 고정 Seed만으로 모든 환경·버전에서 완전히 같은 결과를 보장하지 않습니다. 재현에는 스타일, 가사, 악보, Audio codes, 두 Seed와 합성 설정을 함께 보관하는 것이 좋습니다.

8. 실행 버튼과 로그

항목	기능	주의
Example	공식 예제 중 하나를 무작위로 불러오기	현재 프롬프트가 바뀌므로 먼저 Save하세요. 자동 생성 버튼은 아닙니다.
Generate	생성 시작	악보 → 음악 토큰 → 음향 합성 → 파형 디코딩/파일 인코딩 순서. 기존 codes가 있으면 재사용 선택창이 뜹니다.
Cancel	현재 생성 작업 취소 요청	계산 중인 단계에 따라 반영에 시간이 걸릴 수 있습니다. 기존 결과를 삭제하는 기능은 아닙니다.
Server logs	서버 로그 표시/접기	진행 단계와 오류 확인용. 로그 자체가 다운로드 음원은 아닙니다.

[AR] Score는 악보 생성, [AR] Semantic은 음악 토큰 생성, [NAR] Step n/32는 소리 합성, [VAE]는 파형 복원, [MP3]는 압축 저장 단계입니다. Semantic이 끝났어도 소리 합성은 아직 남아 있을 수 있습니다. Unload는 단계 전환 시 GPU 메모리를 비우는 정상 동작일 수 있습니다.

Reuse this take? 대화상자

Audio codes가 있는 상태에서 Generate를 누르면 나타납니다.

• Same take: codes를 유지하고 같은 연주를 다시 합성합니다. Steps·Noise seed·출력 형식 비교에 사용합니다.
• New take: codes를 지우고 두 Seed를 무작위로 바꾸어 다시 연주합니다. Score까지 자동으로 지우지는 않습니다. 완전히 새로운 작곡을 원하면 Score도 따로 비우세요.

9. 생성 결과 카드와 Menu

결과 카드에는 곡 이름, 재생 버튼, 파형, 파일 형식, 현재 위치/전체 길이가 나타납니다. 아직 결과가 없으면 이 영역이 보이지 않을 수 있습니다.

버튼·메뉴	기능	사용법·주의
Play / Stop	재생 시작/정지	먼저 낮은 음량에서 들어보세요.
파형 클릭·드래그	재생 위치 이동	듣고 싶은 구간으로 이동합니다. 편집·잘라내기 기능은 아닙니다.
Favorite / Unfavorite (하트)	즐겨찾기 지정/해제	일괄 삭제 대상에서 제외할 곡은 하트를 켜세요. 백업을 대신하지 않습니다.
Menu	아래 작업 메뉴 펼치기	메뉴를 여는 것 자체는 곡을 바꾸지 않습니다.
Edit prompt	결과에 사용된 설정을 입력 폼에 불러오기	악보·codes·실제 Seed 등이 포함될 수 있습니다. 현재 작성 중인 입력을 덮으므로 먼저 저장하세요.
Rename song	카드의 곡 이름 바꾸기	이름 변경창에서 입력 후 확인. 음원 내용은 바뀌지 않습니다.
Download audio	실제 음원 파일 내려받기	MP3 또는 WAV로 저장. 프롬프트 Save와 별개입니다.
Transcribe score	오디오를 코드 포함 악보로 채보	별도 SheetSage2 모델 필요. 현재 설치/실행 설정에는 없어 사용 불가.
Transcribe melody	코드 없는 멜로디 악보로 채보	역시 추가 모델 필요. 완료 시 Mode를 Melody로 맞추는 것이 사용 의도입니다.
Delete this track	해당 결과 카드 삭제	확인 대화상자가 뜹니다. 휴지통 복구를 기대하지 말고 먼저 음원/설정을 백업하세요.
Delete non-favorites	목록 전체에서 즐겨찾기가 아닌 곡 삭제	메뉴를 연 카드 한 개만 삭제하는 기능이 아닙니다. 반드시 범위를 확인하세요.

채보 기능을 추후 설치하면 악보가 Score에 들어가지만 Style·Lyrics·Mode는 자동으로 전부 맞춰지지 않습니다. 채보 결과와 원하는 모드를 직접 확인해야 합니다.

결과는 브라우저의 로컬 데이터베이스에 보관됩니다. 다른 브라우저·프로필에서는 목록이 다를 수 있고 사이트 데이터 삭제로 잃을 수 있습니다. 중요한 곡은 음원과 재현 설정을 각각 파일로 저장하세요.

10. RTX 3060 12GB에서의 시작 설정

다음은 보수적인 시작 제안이며, 모든 길이/프롬프트에 대한 메모리 보장은 아닙니다.

설정	빠른 확인	최종 곡 시도
Mode	Full	Full
Score / Audio codes	빈칸	새 작곡이면 빈칸
Duration	60	180~240부터 시작
LM batch / Batch	모두 1	모두 1
CFG scale	1	1
Steps	16	32
나머지 샘플링	기본값	기본값에서 한 항목씩 비교
Format	MP3	감상 MP3, 편집 WAV24

GPU 메모리 부족 시 다른 GPU 앱을 종료하고, 두 Batch를 1로 확인한 뒤 CFG를 정확히 1로 맞추고 Duration을 줄이세요. Steps를 줄이는 것은 주로 계산 시간을 줄이며 메모리 부족을 반드시 해결하지는 않습니다.

--max-seq처럼 캐시 크기를 조절하는 옵션은 이 화면에 없습니다. 서버 실행 옵션 수정과 재시작이 필요하며, 작업 중에는 변경하지 마세요. 현재 실행기는 --max-batch 1을 사용합니다.

11. 자주 생기는 혼동

• 360을 넣었는데 짧게 끝남: Duration은 정확한 재생 시간 계약이 아닙니다. 가사 길이와 모델의 종료 판단도 영향을 줍니다.
• Style·LM seed를 바꿔도 비슷한 곡이 나옴: Audio codes 재사용 여부를 확인하세요. 새 작곡은 codes와 Score를 비웁니다.
• 후렴이 반복됨: 가사상 반복과 토큰 반복 억제는 다릅니다. Repetition penalty를 크게 올리기 전에 가사 구조와 Seed를 먼저 바꿔 비교하세요.
• 음량이 작음: 재생 슬라이더와 저장 음원의 정규화는 별개입니다. WAV32는 자동 정규화를 하지 않습니다.
• Save했는데 MP3가 없음: Save는 설정 저장입니다. 결과 카드의 Download audio를 사용하세요.
• 악보 추출 메뉴 오류: 현재 SheetSage2 모델과 서버의 --transcriber 설정이 없습니다. 메뉴 존재만으로 기능 준비가 완료된 것은 아닙니다.
• 수치 입력 오류: 정수 항목에 소수를 넣지 말고, 샘플링 범위를 확인하세요. 빈칸과 0은 다릅니다.

12. 확인 근거와 문서 범위

입력 항목·도움말·기본 표시값은 실제 웹 화면의 접힌 그룹을 펼쳐 확인했습니다. 서버 기본값은 로컬 서버 속성에서 확인했습니다. 대화상자와 결과 카드 동작, 입력 범위 및 내부 처리 의미는 해당 버전 소스와 대조했습니다. 생성·삭제·초기화·채보를 추가 실행하며 검증한 문서는 아닙니다.

• 서버 버전의 요청 규격과 처리 구조
• 화면 표시 버전의 입력 폼과 대화상자
• 화면 표시 버전의 결과 카드 메뉴
• 설정 초기화·저장 필드 정의
• Peak clip 및 파일 인코딩 구현