Communitygithub.com

배경 음악

텍스트 브리프만으로 로열티 프리 배경 음악을 완전 오프라인에서 생성합니다. Apple Silicon(MLX)에 최적화되어 있으며, 음성 내레이션과 믹싱할 수 있습니다.

배경 음악란 무엇인가요?

이 스킬은 ACE-Step 1.5(MLX 기반 음악 모델)를 활용하여 텍스트 브리프(장르, 분위기, BPM, 길이)로부터 독창적인 배경 음악을 생성하는 완전 로컬 도구입니다. Cursor, Claude Code 등 모든 AI 코딩 에이전트에서 사용할 수 있으며, Apple Silicon Mac에서 MLX/Metal 가속으로 빠르게 동작합니다. 스킬은 먼저 사용자로부터 구체적인 브리프를 받아 적절한 프롬프트로 변환하고, 2개의 후보 트랙을 생성하여 사용자가 선택하게 합니다. 선택된 트랙은 `mix_voiceover.sh`를 통해 음성 내레이션과 자동으로 믹싱(사이드체인 덕킹)되어 완성된 오디오 트랙을 제공합니다. 모든 데이터(코드, 모델 가중치, 생성된 오디오)는 사용자의 홈 디렉토리 `~/.bg-music/`에 저장되며, 인터넷 연결 없이 완전히 로컬에서 작동합니다. 상업적 사용도 MIT 라이선스로 안전하지만, 저작권 문제를 방지하기 위해 특정 아티스트나 트랙을 모방하는 프롬프트는 피해야 합니다.

지원 대상✓Claude Code~Codex CLI✓Cursor
npx skills add puntorigen/skills

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

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

문서

배경 음악은(는) 무엇을 하나요?

텍스트 브리프를 기반으로 릴스 및 데모 비디오를 위한 독창적이고 로열티 프리인 배경 음악을 생성합니다. 완전 오프라인으로 동작합니다. 래퍼(래퍼)는 ACE-Step 1.5(음악 모델)를 구동합니다. 당신(모델)은 브리프를 좋은 프롬프트로 다듬고, 여러 후보를 생성한 후 사용자가 선택하도록 하며, 선택된 트랙을 내레이션 아래에 선택적으로 믹싱합니다.

이 스킬은 voice-clone-narration 스킬과 함께 사용합니다. 음성은 거기서 생성하고, 배경 음악은 여기서 생성한 다음 mix_voiceover.sh로 음악이 내레이션 아래에서 자동으로 낮아지도록(덕킹) 하여 완성된 릴스 오디오 트랙을 만듭니다.

flowchart LR
  Brief["브리프: 장르, 분위기, BPM, 길이"] --> Gen["generate_music.py<br/>ACE-Step 1.5 (MLX), 기악"]
  Gen --> Mp3["후보 mp3 파일"]
  Nar["narration.mp3 (선택 사항)"] -.-> Mix["mix_voiceover.sh<br/>ffmpeg 사이드체인 덕킹"]
  Mp3 -.-> Mix
  Mix -.-> Reel["reel-audio.mp3"]

모든 것은 리포지토리 외부의 ~/.bg-music/ 디렉토리(ACE-Step 체크아웃, 모델 가중치, 생성된 오디오)에 저장됩니다.

사전 요구 사항

  • uv(패키지 관리자) 및 git - 모델은 단순 pip 설치가 아닌 uv sync 앱입니다. 설치는 격리된 환경에 설치합니다.
  • PATH에 ffmpeg 필요(MP3 인코딩 + 믹싱). 없으면 사용자에게 brew install ffmpeg를 요청하세요.
  • 약 10GB 여유 디스크 코드 + 모델 가중치(한 번 Hugging Face에서 익명으로 다운로드, 토큰 불필요). 더 큰 모델 변형을 사용하면 더 많은 공간이 필요합니다.
  • 빠른 네이티브 경로(MLX)를 위해 Apple Silicon Mac. CUDA/CPU에서는 PyTorch로 대체됩니다(CPU에서는 느림). 기본 2B-turbo + 0.6B-LM 계층에는 16GB 통합 메모리로 충분합니다.
  • 첫 번째 실행 시에만 인터넷 필요(코드 + 가중치 다운로드). 생성은 오프라인입니다.

설정

스킬 디렉토리를 확인하고 한 번 설정을 실행합니다(ACE-Step 1.5를 클론하고 환경을 동기화합니다. 첫 번째 실행은 종속성을 다운로드하므로 몇 분 정도 걸릴 수 있음):

SKILL_DIR="<이 SKILL.md 파일이 있는 폴더>"   # 예: .cursor/skills/bg-music
bash "$SKILL_DIR/scripts/setup_env.sh"

그런 다음 생성에 사용할 핸들을 설정합니다(setup_env.sh에서도 출력됩니다):

BG_HOME="${BG_MUSIC_HOME:-$HOME/.bg-music}"
PY="$BG_HOME/ACE-Step-1.5/.venv/bin/python"

워크플로우

이 체크리스트를 복사하여 진행 상황을 추적하세요:

- [ ] 1. 브리프 확인: 장르, 분위기, 템포(BPM), 길이, 주요 악기
- [ ] 2. 설정: setup_env.sh 실행 (처음 한 번만)
- [ ] 3. 구체적인 프롬프트 작성; 후보 2개 생성
- [ ] 4. 후보 듣기/링크; 사용자 선택 허용 (필요시 재생성)
- [ ] 5. (선택 사항) 승자 트랙을 내레이션 mp3 아래에 덕킹으로 믹싱
- [ ] 6. mp3 전달

1단계: 브리프 확정하기

음악 품질은 구체적인 프롬프트에 달려 있습니다. 사용자로부터 다음 정보를 얻거나 추론하여 선택 사항을 명시하세요:

  • 장르/스타일: 로파이 힙합, 시네마틱 오케스트라, 기업 엠비언트, 신스웨이브, 어쿠스틱 포크, 신나는 팝...
  • 분위기: 차분함, 고양됨, 긴장감, 몽환적, 활기참, 우울함.
  • 템포: 느림 / 중간 / 빠름, 또는 명시적 BPM(예: 90).
  • 길이: 초(10-600; 릴스는 보통 30-120).
  • 주요 악기(선택 사항): 로즈 피아노, 따뜻한 패드, 부드러운 드럼, 나일론 기타.

3단계: 생성하기

"$PY" "$SKILL_DIR/scripts/generate_music.py" \
  --prompt "따뜻한 로파이 힙합, 감미로운 로즈 피아노, 부드러운 비닐 노이즈, 느긋한 드럼, 루프 가능, 기악" \
  --bpm 80 --duration 60 --count 2 \
  --out "$BG_HOME/out/lofi.mp3"
  • 트랙은 기본적으로 기악입니다(보컬 없음).
  • --count 2는 선택할 수 있는 두 가지 변형을 생성합니다(lofi-1.mp3, lofi-2.mp3).
  • MP3 파일을 쓰고 경로와 길이를 출력합니다. 첫 번째 실행은 모델 가중치를 다운로드합니다. 이후 실행은 훨씬 빠릅니다.

좋은 프롬프트는 구체적이고 쉼표로 구분됩니다. 장르 + 분위기 + 2-3가지 악기 + 템포 단어 + "기악"/"루프 가능"을 포함하세요. 예시:

  • "시네마틱 감동 오케스트라, 부드러운 현악기, 피아노, 점차 따뜻하게 고조되는 은은한 타악기, 기악"
  • "깔끔한 기업 엠비언트, 부드러운 신스 패드, 가벼운 플럭, 낙관적, 미니멀, 기악"
  • "드라이빙 신스웨이브, 아날로그 베이스, 레트로 아르페지오, 펀치감 있는 드럼, 야간 주행 에너지, 기악"

5단계: 내레이션 아래에 믹싱하기(선택 사항)

사용자에게 음성 오버(예: voice-clone-narration 스킬에서)도 있는 경우, 음악을 자동으로 덕킹합니다:

bash "$SKILL_DIR/scripts/mix_voiceover.sh" \
  --voice ~/.voice-clone-narration/out/test-en.mp3 \
  --music "$BG_HOME/out/lofi-1.mp3" \
  --out ~/Desktop/reel-audio.mp3

음성이 재생되는 동안 음악은 자동으로 낮아지고(사이드체인 압축), 음성 없는 구간에서 다시 올라옵니다. 내레이션 길이를 커버하도록 루프되며 페이드 인/아웃됩니다. --music-gain(배경 레벨, 기본 -8dB), --duck(덕킹 강도, 기본 8) 및 --fade로 조정할 수 있습니다.

6단계: 전달하기

선택된 mp3를 포함하거나 링크하세요. 생성된 파일은 ~/.bg-music/out/에 유지됩니다.

주요 옵션 (generate_music.py)

옵션기본값목적
--prompt(필수)음악 설명: 장르, 분위기, 악기, 느낌.
--duration60길이(초, 10-600).
--bpm자동BPM 템포(30-300); 생략하면 모델이 선택합니다.
--count2생성할 변형 수.
--outout/music-<ts>.mp3출력 경로 (--count > 1이면 접두어로 사용).
--seed무작위재현성을 위해 고정.
--keyscale자동음악 키, 예: "A minor".
--vocals꺼짐 (기악)보컬 허용 (배경 음악에는 거의 필요 없음).
--steps8확산 단계 (터보 기본값; 더 많으면 느리지만 약간 더 좋음).
--mp3-quality2ffmpeg libmp3lame -q:a (0=최고..9=최소).
--keep-wav꺼짐중간 wav 파일 유지.

주요 옵션 (mix_voiceover.sh)

옵션기본값목적
--voice(필수)내레이션 mp3/wav (전체 레벨 유지).
--music(필수)배경 음악 mp3/wav (덕킹 + 내레이션 길이만큼 루프).
--out(필수)출력 믹싱 mp3.
--music-gain-8기본 음악 레벨 dB (낮을수록 조용함).
--duck8덕킹 강도 (압축기 비율); 높을수록 음악이 더 낮아짐.
--fade2음악 페이드 인/아웃 시간(초).
--mp3-quality2ffmpeg libmp3lame -q:a.

안전

  • AI 생성 음악임을 공개해야 하는 플랫폼이나 상황에서는 반드시 공개하세요.
  • 상업적 사용: ACE-Step 1.5는 MIT 라이선스이며 라이선스/로열티 프리/합성 데이터로 훈련되었으므로 생성된 트랙은 일반적으로 안전하게 사용할 수 있습니다. 그러나 모델의 자체 면책 조항에 따라, 특정 아티스트나 트랙의 정체성을 복사하는 프롬프트는 피하고 상업적 출시 전에 독창성을 확인하세요.
  • 브리프, 프롬프트, 생성된 오디오를 외부 서비스에 절대 업로드하지 마세요. 모든 것은 ~/.bg-music/ 아래에 로컬로 유지됩니다.

안티 패턴

  • 모호한 한 단어 프롬프트("음악", "멋진 것") - 일반적인 결과를 얻습니다. 장르 + 분위기 + 악기 + 템포를 명시하세요.
  • 배경 음악만 필요한데 보컬을 요청하는 경우 - 트랙이 내레이션 아래에서 깔끔하게 들어가도록 기악(기본값)으로 유지하세요.
  • 하나의 테이크만 생성하고 바로 보내기 - --count 2로 생성하고 사용자가 선택하도록 하세요.
  • 음성 오버 아래에 음악을 수동으로 오버레이하기 - mix_voiceover.sh를 사용하여 음악이 음성 아래에서 자동으로 낮아지도록 하세요.
  • "<아티스트/트랙>과 똑같이 들리는 노래"를 요청하기 - 독창성 및 라이선스 위험.
  • ~/.bg-music/의 내용을 리포지토리에 커밋하기.

리소스

  • 모델 동물원(16GB에서 2B-turbo를 사용하는 이유), 전체 파라미터 치트시트, 분위기별 프롬프트 패턴, 라이선스 근거, 문제 해결: REFERENCE.md
  • 음악 아래에 믹싱할 내레이션 생성: voice-clone-narration 스킬.
  • 비디오에서 최종 오디오 확인: review-mp4 스킬.

관련 스킬