Discord 노래봇

Python과 discord.py를 활용한 디스코드 음악 봇입니다. YouTube에서 음악을 검색/재생하며, 대기열 관리, 즉시 스킵, 유사곡 자동재생(프리페치 포함) 등의 기능을 제공합니다.

기술 스택

항목	기술
언어	Python 3.12
Discord API	discord.py 2.7+ (voice 확장 포함)
음원 추출	yt-dlp
오디오 인코딩	FFmpeg 8.1
패키지 관리	uv
환경 변수	python-dotenv

프로젝트 구조

discordBot/
├── .env                  # 봇 토큰 (Git 추적 제외)
├── .gitignore
├── requirements.txt
├── bot.py                # 봇 진입점
└── cogs/
    └── music.py          # 음악 Cog

명령어 목록

기본 재생

명령어	설명
/join	사용자가 있는 음성 채널에 봇을 입장시킵니다.
/leave	봇을 음성 채널에서 퇴장시킵니다.
/play <URL 또는 검색어>	URL은 바로 재생, 검색어는 5개 결과를 버튼으로 제시하여 선택 후 재생합니다.
/pause	현재 재생 중인 노래를 일시정지합니다.
/resume	일시정지된 노래를 다시 재생합니다.
/stop	재생을 중지하고 대기열을 초기화합니다.

스킵

명령어	설명
/skip	현재 노래를 즉시 건너뛰고 다음 곡을 재생합니다.

대기열 관리

명령어	설명
/queue	현재 대기열 목록을 Embed로 표시합니다.
/remove <번호>	대기열에서 해당 번호의 곡을 제거합니다.

반복 / 셔플

명령어	설명
/loop <모드>	반복 모드를 전환합니다. (끄기 / 한 곡 반복 / 전체 반복)
/shuffle	대기열의 곡 순서를 무작위로 섞습니다.

검색

명령어	설명
/search <검색어>	YouTube에서 최대 5개의 검색 결과를 보여주고, 버튼 클릭 또는 채팅 입력으로 선택할 수 있습니다.

기타

명령어	설명
/nowplaying	현재 재생 중인 곡 정보를 Embed로 표시합니다.
/autoplay	자동재생 토글. 장르 프리셋 설정, variety로 가수 다양성 토글 가능.

유사곡 자동재생

대기열이 비어있으면, 현재 곡 제목에서 키워드를 추출하여 YouTube에서 유사한 곡을 자동으로 검색하고 재생합니다.

중복 방지

• 곡명 유사도 필터: 제목 유사도 75% 이상인 곡(커버, 리믹스 등)을 자동 차단합니다.
• 가수 다양성: /autoplay variety로 토글. 켜면 최근 5곡과 같은 가수의 곡이 연속 추천되지 않습니다.
• 이력 관리: 최근 50곡의 재생 이력을 기반으로 URL 중복을 방지합니다.

프리페치

현재 곡이 끝나기 15초 전에 다음 자동추천 곡을 미리 검색해둡니다. 곡 전환 시 검색 대기 시간 없이 즉시 다음 곡이 재생됩니다.

장르 프리셋

/autoplay <장르> 명령으로 자동재생 검색에 장르 태그를 추가할 수 있습니다.

사용 가능 프리셋: 애니, 팝, 록, 재즈, 클래식, 힙합, R&B, EDM, 발라드, JPOP, KPOP, 게임, 로파이

자동 퇴장

• 음성 채널에 봇만 남으면 30초 후 자동 퇴장합니다.
• 재생이 끝나고 대기열이 비어있으면 3분 후 자동 퇴장합니다.

실행 방법

사전 준비

• Python 3.12+
• FFmpeg
• uv

설치 및 실행

# 의존성 설치
uv venv .venv
uv pip install -r requirements.txt

# .env 파일에 봇 토큰 설정
echo BOT_TOKEN=your_token_here > .env

# 가상환경 활성화 후 실행
.venv\Scripts\activate
python bot.py

참고사항

• Slash Command 기반이므로, 봇 초대 시 applications.commands 권한이 필요합니다.
• 첫 실행 시 Slash Command 동기화에 시간이 걸릴 수 있습니다 (최대 1시간).