Communitygithub.com

haoyiyin/text-to-bgm

텍스트 설명으로 배경 음악을 생성하는 AI 에이전트 스킬. Apple Silicon Mac에서 100% 로컬로 작동합니다.

text-to-bgm란 무엇인가요?

이 스킬은 Apple Silicon Mac(M1/M2/M3/M4)에서 텍스트 설명만으로 배경 음악(BGM)을 생성할 수 있게 해줍니다. Meta의 MusicGen을 Apple MLX 프레임워크로 포팅한 `mlx-audiocraft`를 기반으로 하며, 완전히 오프라인에서 작동하여 클라우드나 API 키가 필요 없고 프라이버시가 완벽히 보장됩니다. MLX GPU 가속을 통해 빠른 생성을 지원하며, small/medium/large/stereo-large 모델을 선택할 수 있어 성능과 품질을 조절할 수 있습니다. 개발자는 명령줄 인터페이스나 파이썬 API를 사용하여 장르, 분위기, 악기, 지속 시간 등을 지정한 BGM을 생성할 수 있으며, 생성된 WAV 파일은 비디오, 게임, 팟캐스트, 공부/집중 세션 등에 바로 활용할 수 있습니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트와의 통합을 염두에 두고 설계되어, 에이전트가 사용자 요청을 분석하고 적절한 프롬프트와 파라미터로 음악을 생성할 수 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add haoyiyin/text-to-bgm

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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-small300M / 1.2GB좋음1.3x 실시간기본 선택
facebook/musicgen-medium1.5B / 3.4GB더 좋음~0.6x 실시간더 나은 품질
facebook/musicgen-large3.3B / 5.5GB최고 (모노)~0.4x 실시간고품질
facebook/musicgen-stereo-large3.3B / 6.5GB최고 (스테레오)~0.3x 실시간최종 출력

생성 파라미터

파라미터범위효과
--temperature0.5–1.5높을수록 더 창의적/다양함. 낮을수록 더 예측 가능함
--top-k100–500높을수록 더 다양한 음표 선택
--cfg-coef1.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 에이전트용)

  1. 설치 확인: musicgen-mlx --help 실행. 없으면 pip install mlx-audiocraft로 설치.
  2. 요구사항 수집: 사용자에게 장르, 분위기, 지속 시간을 물어봄. 모호하면 인기 BGM 스타일 제안.
  3. 모델 선택: 기본값은 facebook/musicgen-small (빠름, 300M). 더 나은 품질은 facebook/musicgen-medium, 최고 결과는 facebook/musicgen-stereo-large 사용.
  4. 프롬프트 작성: prompts.md의 프롬프트 가이드에 따라 10–30단어의 영어 설명을 작성.
  5. 지속 시간 설정: 루프용 15–30초, 짧은 BGM용 30–60초, 긴 곡용 60–120초.
  6. 생성: musicgen-mlx "<프롬프트>" -m <모델> -d <초> -o <경로>.wav 실행.
  7. 보고: 사용자에게 출력 파일 경로를 알림. 필요시 파라미터 조정하여 재생성 제안.

주의사항

  • ⚠️ 첫 실행 시 모델 다운로드 — 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장르 템플릿이 포함된 프롬프트 엔지니어링 가이드

관련 스킬