로컬 음악 생성
YuE2 로컬 음악 생성 가이드: 가사에서 보컬곡과 편곡 만들기
YuE2로 가사에서 보컬과 반주가 있는 곡을 만들고, 악보를 수정하는 과정을 따라갑니다. 공식 시작 조건은 Linux와 BF161을 지원하는 NVIDIA GPU2, 24GB VRAM3입니다. 한국어 가창은 짧은 가사로 먼저 확인하세요.
YuE v1과 현재 YuE2를 먼저 구분하기
저장소 주소는 그대로지만 main 브랜치의 README가 YuE2로 교체되어 있습니다. README는 기존 YuE의 코드·문서·라이선스가 YuE-v1 브랜치에 보존되어 있다고 안내합니다.
따라서 오래된 설치 글에서 본 의존성, GPU 메모리 요구량, 체크포인트4 이름을 현재 설치에 그대로 섞으면 안 됩니다. 이 페이지의 명령과 인터페이스는 YuE2 기준이며, 구버전 YuE를 재현하려는 경우에는 YuE-v1 브랜치의 설명과 해당 모델 카드, 가중치 이용 조건을 별도로 확인하세요.
YuE2는 가사와 스타일로 악보를 계획한 뒤 곡 전체를 생성합니다. 기본 출력은 보컬과 반주가 합쳐진 48kHz 스테레오 음원입니다. 첫 실행 때 모델 파일을 내려받으므로 저장 공간과 네트워크 시간을 확보하세요. 생성된 악보를 직접 수정하는 방법도 다룹니다.
GPU와 운영체제 조건 확인하기
공식 quick start는 Linux, Python 3.12, BF16을 지원하는 NVIDIA GPU와 24GB VRAM을 기준으로 합니다. README는 양자화5 없이 48kHz 스테레오를 생성한다고 설명합니다.
따라서 설치 전에 GPU 모델과 VRAM을 확인하고, 시스템 RAM6·저장 공간에도 여유를 두세요. 24GB보다 작은 카드에서 시도하는 것은 문서가 보장하는 구성은 아닙니다. 메모리 부족으로 실패해도 그것이 모델 품질이나 속도에 대한 벤치마크 결과는 아닙니다.
공식 README와 Hugging Face quick start는 NVIDIA CUDA7 실행 경로를 다룹니다. Apple Silicon의 Metal, AMD ROCm, Windows 네이티브 실행은 공식 설치 조건에 없습니다. 해당 장치에서 실행하려면 최신 upstream 문서를 확인하고 별도 구성으로 시험하세요.
Python 환경을 분리해 설치하고 첫 곡 만들기
Python 3.12를 준비하고 새 가상환경8에서 공식 저장소를 설치합니다. 설치 경로는 PyTorch9·CUDA 등 기존 Python 패키지와 충돌할 수 있으니, 다른 음악 도구 환경을 재사용하지 않는 편이 관리하기 쉽습니다.
명령은 저장소 README의 quick start를 따릅니다. 설치가 끝나면 기본 예제 요청을 사용해 첫 결과를 생성하세요.
모델 가중치는 설치 패키지에 포함되지 않고 첫 실행 때 다운로드됩니다.
기본 CLI10는 예제 요청 파일을 지정하지 않으면 저장소의 기본 request를 사용합니다. 출력 경로를 새로 정해 결과가 덮어써지지 않도록 하고, 첫 실행에서 다운로드가 끝난 뒤 audio.flac을 들어 보세요.
출력 폴더에는 청취 파일뿐 아니라 score.abc11, 설정과 중간 산출물이 함께 저장됩니다. 한 곡 생성이 끝나지 않거나 truncated 표시가 있으면 그 상태도 기록해야 결과를 정상 완성으로 오해하지 않습니다.
git clone https://github.com/multimodal-art-projection/YuE.git
cd YuE
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .python examples/generate.py --output outputs/first-song가사곡, 보컬, 순수 연주곡의 범위
YuE2의 주된 생성 예제는 가사와 스타일을 넣어 보컬과 반주가 있는 완성곡을 만드는 경로입니다. 스타일에는 장르, 악기, 보컬 성격, 언어, 템포를 간결하게 적고, 가사는 [Verse], [Chorus]처럼 곡 구조를 표시합니다. '소울풀한 중저음 보컬, 느린 네오소울, Rhodes와 베이스, 82 BPM12'처럼 서로 맞는 단서를 주면 의도를 검토하기 쉽습니다.
단, 모델이 요청한 성별·발음·템포를 정확히 따르거나 가사를 한 글자도 빠짐없이 부른다고 보장되지는 않습니다.
보컬 없이 반주만 필요한 경우에는 이 차이를 먼저 알아두세요. README와 기본 예제는 가사 입력으로 보컬곡을 만드는 데 초점을 둡니다. 'instrumental' 스타일 문구만으로 보컬이 항상 사라지는지, 별도의 무가사 입력이 공식 지원되는지는 README에서 명시적으로 확인되지 않습니다.
따라서 순수 인스트루멘털이 필수라면 작은 시험 곡으로 보컬 누출을 듣고 확인하세요. 확실한 무보컬이 요구되는 제작이라면 보컬·반주 분리나 다른 전용 생성 경로를 준비하는 편이 낫습니다.
한국어 가사는 작동 확인과 품질 검증을 나눠 보기
YuE2 README 상단은 ‘All languages’를 표방하고, 공개 예제에는 영어와 중국어 곡이 있습니다. 반면 모델 카드의 언어 태그는 중국어와 영어이며 한국어 전용 체크포인트나 품질 평가 자료는 확인되지 않습니다.
다국어 안내와 카드 태그만으로 한국어 가창의 품질을 확정할 수는 없습니다. 공식 YuE v1에는 일본어·한국어 체크포인트가 있으므로, 두 버전의 정보를 섞지 말고 YuE2에서는 짧은 가사로 직접 발음과 음절 길이를 들어 보세요.
시험은 긴 곡보다 한두 줄의 한국어 가사로 시작하세요. 모델이 글자를 빼거나 비슷한 소리로 바꾸는지, 받침과 연음이 들리는지, 박자에 맞추느라 모음을 늘이거나 음절을 합치는지 기록합니다.
같은 입력을 영어 또는 중국어 예제와 섞어 비교하면 무엇을 확인하려는지 흐려질 수 있습니다. 한국어가 핵심 요건이라면 여러 음역과 빠르기에서 반복 청취하고, 실제 사용 전에는 사람의 교정과 동의를 받으세요.
full·melody·off와 생성 단계 이해하기
기본 full 모드는 먼저 편집 가능한 멜로디와 코드 계획을 만들고, 이후 그 계획으로 곡을 생성합니다. melody 모드는 멜로디만 계획하며, 공식 문서는 커버에서 반주를 새 스타일에 맞게 바꾸는 용도로 권합니다. off는 기보 계획 없이 가사와 스타일에서 직접 생성합니다. abc 입력으로 사용자가 만든 악보를 전달할 수도 있지만, 입력은 저장소가 지원하는 ABC 형태여야 합니다. 익숙하지 않은 ABC 표기법은 변환이 필요할 수 있습니다.
세부 API13는 plan() → generate_semantic() → synthesize() → decode14() 순서로 나뉩니다. 계획 단계는 score.abc와 계획 파일을 만들고, semantic 단계가 음악을 나타내는 토큰15을 생성합니다. synthesize 단계는 음향 latent를 계산하고, VAE16 decoder가 최종 스테레오 파형을 복원합니다.
이 구분은 시간이 어디에 드는지 파악하고 결과의 기보를 고칠 때 유용합니다. 보컬과 반주를 따로 내보내는 stem 분리와는 다릅니다.
단계별 실행은 중간 파일이 커질 수 있으니 충분한 저장 공간을 확보하세요.
악보를 복사해 곡 수정하기
생성 폴더의 score.abc를 보관한 뒤 복사본을 편집하세요. 멜로디 음높이와 리듬, 코드 진행, 구간 길이를 바꾸고 싶다면 먼저 한 가지 변화만 적용해 들어 봅니다.
YuE2는 악보를 읽고 점검할 수 있게 하는 것이 특징이지만, 텍스트 지시만으로 기존 파형 일부를 보존한 채 덧칠하는 오디오 편집기는 아닙니다. 수정된 악보를 입력하면 전체 곡을 다시 렌더링합니다.
따라서 원본 음원·악보·수정본을 각기 다른 폴더에 남겨 두세요.
생성 파이프라인17을 Python에서 분리해 호출할 수 있습니다. 공식 generation 문서 예제는 plan을 저장하고 다시 불러온 다음 semantic 토큰부터 이어 작업합니다.
편집 시에는 저장된 plan 내부를 직접 고치지 말고 score.abc 복사본을 수정해 새 요청의 abc 인자로 전달하세요. save_artifacts()가 남기는 설정, 모델 식별자, 토큰, latent와 truncation 여부를 보존하면 나중에 어떤 조건으로 만든 결과인지 추적하기 쉽습니다.
import json
from pathlib import Path
from yue2 import YuE2Pipeline
request = json.loads(Path("examples/song.json").read_text(encoding="utf-8"))
with YuE2Pipeline.from_pretrained("m-a-p/YuE2-3B", device="cuda") as pipe:
song = pipe(**request)
song.save_artifacts("outputs/my-song")
print(song.truncated)생성 시간과 메모리는 측정 조건까지 함께 읽기
공식 quick start는 24GB VRAM NVIDIA GPU와 24GB 가용 시스템 RAM을 시작 조건으로 안내합니다. 카드에 적힌 피크 VRAM 약 11GiB가 곧 11GB 카드에서 실행 가능하다는 뜻은 아닙니다. 최대 문맥 시험에서는 14.08GiB까지 썼고, 다른 GPU·런타임에서는 결과가 달라집니다. 직접 비교할 때는 하드웨어 가이드를 참고하세요.
Hugging Face 모델 카드에는 RTX 4090 공식 측정치가 있습니다. PyTorch 2.10·Transformers 4.57.6, CUDA graphs18와 FlashAttention19, 비양자화 BF16 AR/NAR20·FP3221 VAE·기본 YuE2-Vae 조건에서 full은 214.85초 오디오를 71.04초에 생성하고 VRAM 최고치 11.18GiB, melody는 214.67초를 68.68초에(11.02GiB), off는 196.88초를 57.91초에(11.09GiB) 생성했습니다. 4090 값은 모델 준비 후 모드별로 32회 생성한 평균이며, 다운로드·초기 로딩과 저장 시간은 제외합니다.
이는 로컬 재현 측정이 아니라 모델 카드의 결과입니다.
가중치 라이선스와 결과물 권리를 각각 확인하기
YuE2 코드와 문서는 Apache 2.0, 모델 가중치는 CC BY-NC 4.0에 추가 허가가 붙은 형태로 공개되어 있습니다. 공식 조건은 개인 자격으로 활동하는 창작자·음악가가 모델을 사용해 만든 결과물을 게시·배포·판매·라이선스하거나 수익화할 수 있도록 별도 허가를 줍니다.
기업이 모델 가중치를 업무에 상업적으로 쓰려면 별도의 상업 라이선스를 문의해야 합니다. 코드 라이선스가 가중치까지 허용한다고 해석하면 안 됩니다.
내려받은 체크포인트와 별도 도구·데이터에는 각자의 조건이 적용될 수 있습니다.
모델 사용 허가는 타인의 작사·작곡, 음원, 특정 가수의 목소리나 정체성을 쓸 권리까지 주지 않습니다. 커버를 만들 때는 원곡과 보컬 샘플의 권리·동의를 따로 확인하세요. 배포 가능 여부는 적용 법률과 서비스 정책에 따라 다르므로 상업 발매 전 권리자와 전문가에게 확인해야 합니다.
용어 각주
BF16 — 모델의 수를 저장하고 계산하는 16비트 부동소수점 형식입니다. 사용 가능 여부는 하드웨어와 실행 프로그램에 달려 있습니다.
본문으로 돌아가기GPU — 많은 계산을 병렬로 처리하는 프로세서입니다. AI 모델 실행에서는 모델 계산을 맡습니다.
본문으로 돌아가기VRAM — 그래픽카드의 GPU가 사용하는 메모리입니다. 모델 가중치와 계산 중간값을 저장하며 시스템 RAM과 구분됩니다.
본문으로 돌아가기체크포인트 — 학습된 모델의 가중치 등을 저장한 파일입니다. 같은 모델 계열도 버전이나 용도에 따라 다른 체크포인트를 쓸 수 있습니다.
본문으로 돌아가기양자화 — 모델의 수치를 더 적은 비트로 표현하는 방법입니다. 메모리 사용량과 함께 정확도나 실행 속도도 달라질 수 있으며, 영향은 형식과 구현에 따릅니다.
본문으로 돌아가기시스템 RAM — 프로그램이 실행되는 동안 데이터를 임시로 보관하는 시스템 메모리입니다. 저장장치나 독립 GPU의 VRAM과는 다릅니다.
본문으로 돌아가기CUDA — NVIDIA GPU에서 범용 계산을 실행하기 위한 소프트웨어 플랫폼입니다. CUDA용으로 만든 프로그램은 다른 GPU에서 그대로 동작한다고 보장되지 않습니다.
본문으로 돌아가기Python 가상환경 — 프로젝트별로 Python 패키지를 분리해 설치하는 공간입니다. 패키지 버전 충돌을 줄이며 가상 머신과는 다릅니다.
본문으로 돌아가기PyTorch — AI 모델을 만들고 실행하는 소프트웨어 프레임워크입니다. 모델과 함께 호환되는 PyTorch 버전 및 하드웨어 지원도 확인해야 합니다.
본문으로 돌아가기CLI — Command-Line Interface의 약자입니다. 터미널에 명령어를 입력해 프로그램을 조작하는 방식입니다.
본문으로 돌아가기ABC 악보 표기 — 음높이와 박자 등을 문자로 적는 악보 표기법입니다. 음원 파일이 아니며 도구마다 지원 범위가 다를 수 있습니다.
본문으로 돌아가기BPM — Beats Per Minute의 약자로, 1분당 박자 수를 나타내는 템포 지표입니다.
본문으로 돌아가기API — 프로그램의 기능을 다른 코드에서 호출하기 위한 약속된 인터페이스입니다. API라는 말만으로 외부 서버 전송을 뜻하지는 않습니다.
본문으로 돌아가기디코드 — LLM에서는 입력 처리 뒤 출력 토큰을 생성하는 단계를 뜻합니다. VAE나 오디오 코덱에서는 압축 표현이나 인코딩 데이터를 원래 형식으로 복원하는 처리를 가리킬 수 있습니다.
본문으로 돌아가기토큰 — 모델이 입력이나 출력을 나누어 처리하는 단위입니다. 토큰 하나가 글자 하나나 일정한 시간 길이에 해당하지는 않습니다.
본문으로 돌아가기VAE — Variational Autoencoder의 약자입니다. 입력을 압축된 잠재 표현으로 바꾸거나, 그 표현에서 결과를 복원하는 데 쓰입니다.
본문으로 돌아가기파이프라인 — 입력부터 결과까지 이어지는 처리 단계의 묶음입니다. 각 단계에서 서로 다른 모델이나 도구를 사용할 수 있습니다.
본문으로 돌아가기CUDA Graphs — 반복되는 GPU 작업 순서를 기록해 재사용하는 CUDA 기능입니다. 작업 제출 부담을 줄일 수 있지만 모델 자체를 작게 만들지는 않습니다.
본문으로 돌아가기FlashAttention — 어텐션 계산에서 메모리 접근을 효율화하는 구현입니다. 사용 가능 여부와 효과는 하드웨어, 모델, 실행 환경에 따라 다릅니다.
본문으로 돌아가기AR / NAR — AR은 앞선 출력을 바탕으로 순서대로 생성하는 자기회귀 방식이고, NAR은 출력을 덜 순차적으로 생성하는 비자기회귀 방식입니다.
본문으로 돌아가기FP32 — 32비트 부동소수점 수치 형식입니다. BF16보다 값 하나에 더 많은 메모리를 쓰며 수치를 더 세밀하게 표현할 수 있습니다.
본문으로 돌아가기