터미널(Terminal) 앱 열기
⌘ Command + Space"터미널"Enter.
검은색 창이 하나 열립니다. 이게 앞으로 명령어를 입력할 곳이에요.
TIP: 터미널을 Dock에 고정해두면 다음부터 편해요 (창 위에서 우클릭 → "Dock에 고정").
Homebrew 설치 (이미 있으면 건너뛰기)
Enter.
비밀번호 물어보면 맥 로그인 비밀번호 입력 (타이핑해도 화면에 안 보이는 게 정상). 5~10분 걸립니다.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
이미 설치됐는지 확인: brew --version 쳤을 때 "Homebrew X.X.X" 나오면 OK, 건너뛰세요.
Git & uv 설치
Git은 코드 다운로드용, uv는 Python 전용 패키지 관리자예요. 두 줄 한 번에 복사해 붙여넣기.
brew install git
curl -LsSf https://astral.sh/uv/install.sh | sh
설치 끝나면 터미널을 한 번 닫았다 다시 열어야 uv 명령어가 먹혀요.
ACE-Step 다운로드
ace-step 폴더가 생기고 거기로 코드가 받아져요.
mkdir -p ~/Documents/ace-step && cd ~/Documents/ace-step
git clone https://github.com/ace-step/ACE-Step-1.5.git
cd ACE-Step-1.5
필요한 부품 설치 (uv sync)
3~8분 기다려요. 진행 바가 계속 흘러가면 정상.
uv sync
에러 나면: "command not found: uv" 가 나오면 STEP 03 끝에 말한대로 터미널 껐다 다시 열기.
AI 모델 다운로드 (3~5분)
실제로 음악을 만드는 "두뇌" 파일(약 3~6GB)을 받아요. 인터넷이 빠르면 3분, 느리면 10분 정도.
uv run acestep-download
확인: "Download complete!" 메시지가 뜨면 성공.
AI 음악 서버 켜기
내 컴퓨터 안에 작은 서버를 띄워요. 서버가 돌고 있어야 음악을 뽑을 수 있어요.
창을 닫지 말고 그대로 두세요.
bash start_api_server_macos.sh
성공 신호: "Application startup complete" 또는 "Uvicorn running on http://127.0.0.1:8001" 이 보이면 OK.
여기서 멈추지 마세요! 이 터미널 창은 계속 열어둬야 해요. 닫으면 서버가 꺼져요.
새 터미널 창 열기
새 창이 필요해요.
⌘ Command + N 누르면 두 번째 창이 열립니다.
첫 곡 만들기 🎵
"귀여운 키즈 게임 BGM"이 만들어져요.
프롬프트만 바꾸면 원하는 분위기의 곡을 뽑을 수 있어요 (아래 "프롬프트 레시피" 참고).
약 30초 기다리면 결과 나옵니다.
curl -s -X POST http://127.0.0.1:8001/release_task \
-H "Content-Type: application/json" \
-d '{
"prompt": "happy kids game background music, warm synth, soft bouncy plucks, playful major key, crisp drums, cute and upbeat, clean mix",
"lyrics": "[instrumental]",
"bpm": 120,
"key_scale": "C major",
"guidance_scale": 10.0,
"inference_steps": 8,
"audio_duration": 45,
"use_random_seed": true,
"batch_size": 1,
"model": "acestep-v15-turbo"
}'
돌아오는 응답 예시: {"task_id":"abcd-1234..."} 형태. 이 task_id를 다음 단계에서 씁니다.
완성된 곡 찾기
"status": 1~/Documents/ace-step/ACE-Step-1.5/.cache/acestep/tmp/api_audio/ 폴더 안에 UUID 이름으로 저장되어 있어요.
⌘ + Shift + G → 이 경로 붙여넣기 → Finder로 열어서 더블클릭하면 재생됩니다.
TASK_ID="위에서_받은_task_id_붙여넣기"
curl -s -X POST http://127.0.0.1:8001/query_result \
-H "Content-Type: application/json" \
-d "{\"task_id_list\":[\"$TASK_ID\"]}"
더 편한 방법:http://127.0.0.1:8001/docs 열면 FastAPI 자동 문서가 떠서 버튼으로 클릭해서 쓸 수 있어요.
PowerShell 열기 (관리자 권한)
"PowerShell"우클릭 → "관리자 권한으로 실행" 선택.
UAC 창 뜨면 "예" 클릭. 파란 창이 열려요. 여기가 앞으로 명령어를 입력할 곳이에요.
주의: 꼭 "관리자 권한"으로 열어야 해요. 아니면 중간에 권한 에러로 막혀요.
Git for Windows 설치
확인:git --version 쳐서 버전 번호 나오면 OK.
uv 설치 (PowerShell에 복사)
uv는 Python 전용 패키지 관리자예요. PowerShell 창에 아래 줄을 복사해 붙여넣기.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
설치 후 PowerShell을 완전히 닫았다 다시 열어주세요. 안 그러면 uv 명령어가 인식이 안 돼요.
ACE-Step 다운로드
ace-step 폴더를 만들고 거기로 내려받아요.
mkdir "$HOME\Documents\ace-step" -Force
cd "$HOME\Documents\ace-step"
git clone https://github.com/ace-step/ACE-Step-1.5.git
cd ACE-Step-1.5
필요한 부품 설치
5~15분 소요. 초록 진행 바가 움직이면 정상.
uv sync
AI 모델 다운로드 (3~10분)
실제로 음악 만드는 두뇌 파일(약 3~6GB)을 받아요. 인터넷 속도에 따라 시간 차이 있어요.
uv run acestep-download
완료 신호: "Download complete!" 메시지.
AI 음악 서버 켜기 (창 열어두기)
이 창 절대 닫지 말기!
.\start_api_server.bat
성공 신호: "Uvicorn running on http://127.0.0.1:8001" 보이면 OK.
GPU가 필요해요. NVIDIA 그래픽카드 6GB 이상 (RTX 3060 / 4060 이상 권장). 없으면 CPU로도 돌지만 곡 하나 5~10분 걸려요.
두 번째 PowerShell 창 열기 + 곡 요청
새 PowerShell 창을 하나 더 여세요.
아래 명령어 붙여넣으면 귀여운 키즈 게임 BGM 1곡이 생성돼요. 30초~1분 대기.
$body = @{
prompt = "happy kids game background music, warm synth, soft bouncy plucks, playful major key, crisp drums, cute and upbeat, clean mix"
lyrics = "[instrumental]"
bpm = 120
key_scale = "C major"
guidance_scale = 10.0
inference_steps = 8
audio_duration = 45
use_random_seed = $true
batch_size = 1
model = "acestep-v15-turbo"
} | ConvertTo-Json
Invoke-RestMethod -Uri "http://127.0.0.1:8001/release_task" -Method Post -Body $body -ContentType "application/json"
돌아오는 응답에 task_id 라는 값이 있어요. 다음 단계에서 씁니다.
완성된 곡 찾기
위에서 받은_task_id%USERPROFILE%\Documents\ace-step\ACE-Step-1.5\.cache\acestep\tmp\api_audio\Enter 누르면 파일이 보여요.
$taskId = "위에서_받은_task_id_여기에"
$body = @{ task_id_list = @($taskId) } | ConvertTo-Json
Invoke-RestMethod -Uri "http://127.0.0.1:8001/query_result" -Method Post -Body $body -ContentType "application/json"
웹 UI 쓰고 싶으면:http://127.0.0.1:8001/docsbash start_gradio_ui.bat 실행하면 예쁜 UI가 http://127.0.0.1:7860 에 뜹니다.