text-to-bgm은(는) 무엇을 하나요?
Apple Silicon Mac에서 로컬 AI를 사용하여 텍스트 설명으로 배경 음악(BGM)을 생성합니다. mlx-audiocraft 기반 — Apple MLX 프레임워크로 포팅된 Meta의 MusicGen.
- 100% 오프라인 — 클라우드, API 키 없음, 모델 다운로드 후 인터넷 불필요
- 비공개 — 모든 생성이 기기에서 처리됨
- 빠름 — M1/M2/M3/M4에서 MLX GPU 가속
사용 시점
사용자가 다음을 요청할 때 이 스킬을 사용하세요:
- 배경 음악 / BGM / 기악 음악 생성
- 앰비언트 음악, 로파이 비트, 시네마틱 사운드트랙 제작
- 비디오, 게임, 팟캐스트, 공부/집중 세션용 오디오 생성
- macOS Apple Silicon에서의 텍스트-투-뮤직 요청
다음의 경우 사용하지 마세요:
- 효과음 →
audiogen-mlx(mlx-audiocraft에 포함) 사용 - 보컬 / 노래 → MusicGen은 보컬에 취약함
- 완전한 프로덕션 곡 → 더 길고 구조화된 음악은 ACE-Step 고려
요구 사항
- macOS 및 Apple Silicon (M1, M2, M3, M4)
- Python 3.10+ (3.11 권장)
- RAM: 소형 모델 최소 8GB, 대형 모델 16GB+
- 디스크: 모델당 1.2GB(소형) ~ 6.5GB(스테레오 대형)
설치
# 한 줄 설치
pip install mlx-audiocraft
# 확인
musicgen-mlx --help
또는 포함된 설정 스크립트 사용:
bash setup.sh
사용법
기본
musicgen-mlx "lo-fi chill study beats with soft piano" -d 30 -o bgm.wav
전체 CLI 참조
musicgen-mlx [-h] [-m MODEL] [-o FILE] [-d SEC] [--no-open]
[--top-k K] [--temperature T] [--cfg-coef C]
prompt
인자:
prompt 생성할 음악에 대한 텍스트 설명
옵션:
-m, --model NAME HuggingFace 모델 (기본값: facebook/musicgen-small)
-o, --output FILE 출력 WAV 경로 (기본값: ./musicgen_output.wav)
-d, --duration SEC 지속 시간(초) (기본값: 8)
--no-open 생성 후 파일 열지 않음
--top-k K Top-k 샘플링 (기본값: 250)
--temperature T 샘플링 온도 (기본값: 1.0)
--cfg-coef C 분류기-프리 가이던스 계수 (기본값: 3.0)
모델
| 모델 | 크기 | 품질 | 속도 (M4 Max) | 사용 사례 |
|---|---|---|---|---|
facebook/musicgen-small | 300M / 1.2GB | 좋음 | 1.3x 실시간 | 기본 선택 |
facebook/musicgen-medium | 1.5B / 3.4GB | 더 좋음 | ~0.6x 실시간 | 더 나은 품질 |
facebook/musicgen-large | 3.3B / 5.5GB | 최고 (모노) | ~0.4x 실시간 | 고품질 |
facebook/musicgen-stereo-large | 3.3B / 6.5GB | 최고 (스테레오) | ~0.3x 실시간 | 최종 출력 |
생성 파라미터
| 파라미터 | 범위 | 효과 |
|---|---|---|
--temperature | 0.5–1.5 | 높을수록 더 창의적/다양함. 낮을수록 더 예측 가능함 |
--top-k | 100–500 | 높을수록 더 다양한 음표 선택 |
--cfg-coef | 1.0–7.0 | 높을수록 프롬프트를 더 엄격히 따름. 기본값 3.0은 균형적 |
래퍼 스크립트 사용
편의를 위해 generate_bgm.sh를 사용하세요:
bash generate_bgm.sh "cinematic orchestral epic trailer music" -d 45
옵션: -m <모델>, -d <초>, -t <온도>, -o <출력>
Python API
import mlx.core as mx
import numpy as np
import soundfile as sf
from audiocraft_mlx.models.musicgen import MusicGen
# 모델 로드
mg = MusicGen.get_pretrained("facebook/musicgen-small")
# 생성 파라미터 설정
mg.set_generation_params(duration=30, temperature=1.0, top_k=250, cfg_coef=3.0)
# 생성
audio = mg.generate(["lo-fi jazz hop with smooth saxophone and chill drums"])
# 저장
wav = np.array(audio[0]) # [채널, 샘플]
sf.write("output.wav", wav.T, mg.sample_rate)
프롬프트 엔지니어링
예제가 포함된 종합 가이드는 prompts.md를 참조하세요.
빠른 팁:
- 장르/스타일로 시작: "lo-fi hip hop", "cinematic orchestral", "ambient electronic"
- 악기 추가: "warm piano", "soft synth pads", "acoustic guitar"
- 분위기/무드 설명: "relaxing", "uplifting", "mysterious", "energetic"
- 프로덕션 특성 포함: "vinyl crackle", "reverb", "80 BPM", "sidechain compression"
- 용도로 마무리: "perfect for study", "background for podcast", "game menu music"
⚠️ MusicGen은 영어 프롬프트와 기악 음악에 가장 잘 작동합니다.
절차 (AI 에이전트용)
- 설치 확인:
musicgen-mlx --help실행. 없으면pip install mlx-audiocraft로 설치. - 요구사항 수집: 사용자에게 장르, 분위기, 지속 시간을 물어봄. 모호하면 인기 BGM 스타일 제안.
- 모델 선택: 기본값은
facebook/musicgen-small(빠름, 300M). 더 나은 품질은facebook/musicgen-medium, 최고 결과는facebook/musicgen-stereo-large사용. - 프롬프트 작성: prompts.md의 프롬프트 가이드에 따라 10–30단어의 영어 설명을 작성.
- 지속 시간 설정: 루프용 15–30초, 짧은 BGM용 30–60초, 긴 곡용 60–120초.
- 생성:
musicgen-mlx "<프롬프트>" -m <모델> -d <초> -o <경로>.wav실행. - 보고: 사용자에게 출력 파일 경로를 알림. 필요시 파라미터 조정하여 재생성 제안.
주의사항
- ⚠️ 첫 실행 시 모델 다운로드 — HuggingFace에서 1.2–6.5 GB 다운로드. 사용자에게 경고.
- ⚠️ Apple Silicon 전용 — Intel Mac에서는 작동하지 않음.
- ⚠️ 기본 8초 지속 시간 — BGM에는 항상
-d지정. - ⚠️ 기악 전용 — 보컬/가사에 취약.
- ⚠️ 비상업용 라이선스 — CC-BY-NC 4.0. 상업적 사용 불가.
- ⚠️ RAM 소모 많음 — 8GB 시스템은 소형/중형 모델만 사용.
- ⚠️ 대형 모델은 느림 — 스테레오-대형은 ~0.3x 실시간. 60초 생성에 약 3분 소요.
확인
# 1. CLI 확인
musicgen-mlx --help
# 2. 빠른 테스트
musicgen-mlx "piano melody" -d 5 -o /tmp/test_bgm.wav
# 3. 출력 확인
file /tmp/test_bgm.wav
# 예상: RIFF (little-endian) data, WAVE audio
# 4. 듣기
open /tmp/test_bgm.wav
파일
| 파일 | 용도 |
|---|---|
SKILL.md | 이 파일 — 스킬 정의 및 참조 |
setup.sh | 원클릭 설치 스크립트 |
generate_bgm.sh | 쉬운 에이전트 친화적 생성을 위한 래퍼 |
prompts.md | 장르 템플릿이 포함된 프롬프트 엔지니어링 가이드 |