디스코드 음악 봇 만들기

음악 봇은 오래된 기능처럼 보이지만 여전히 수요가 있습니다.

특히 소규모 커뮤니티나 개인 서버에서는 음성 채널 기능을 테스트할 때 가장 자주 만드는 봇 중 하나입니다.

다만 다른 기능형 봇보다 의존성이 많고, FFmpeg 같은 외부 도구에서 자주 막힙니다.

이번 글에서는 discord.py와 FFmpeg를 이용해 URL 기반 오디오를 재생하는 가장 기본적인 음악 봇을 만듭니다.

1. 먼저 알아둘 점

음악 봇은 텍스트 봇보다 준비물이 많습니다.

특히 아래 두 가지가 중요합니다.

• 음성 채널 접속 권한
• FFmpeg 설치

FFmpeg가 없으면 재생 단계에서 바로 멈춥니다.

따라서 설치 단계에서 FFmpeg가 실제로 잡히는지 먼저 확인해야 합니다.

2. 음성 재생에 필요한 도구부터 맞춘다

pip install -U discord.py yt-dlp python-dotenv
brew install ffmpeg

macOS 기준으로는 `brew install ffmpeg`가 가장 빠릅니다.
다른 OS라면 설치 방식이 다를 수 있습니다.

3. 토큰과 명령어 접두어 정리

DISCORD_TOKEN=여기에_봇_토큰
GUILD_ID=테스트_서버_ID

이 글에서는 슬래시 명령어로 음성 채널 접속과 재생을 처리합니다.

4. 음성 채널 접속과 재생 코드

import os

import discord
from discord import app_commands
from dotenv import load_dotenv
import yt_dlp

load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")
GUILD_ID = int(os.getenv("GUILD_ID"))

intents = discord.Intents.default()
intents.voice_states = True
client = discord.Client(intents=intents)
tree = app_commands.CommandTree(client)
guild = discord.Object(id=GUILD_ID)


def extract_audio_url(query: str) -> str:
    with yt_dlp.YoutubeDL({"format": "bestaudio", "quiet": True}) as ydl:
        info = ydl.extract_info(query, download=False)
        return info["url"]


@client.event
async def on_ready():
    await tree.sync(guild=guild)
    print(f"로그인 성공: {client.user}")


@tree.command(name="재생", description="입력한 URL의 오디오를 재생합니다.", guild=guild)
@app_commands.describe(url="재생할 오디오 URL")
async def play_music(interaction: discord.Interaction, url: str):
    if not isinstance(interaction.user, discord.Member) or interaction.user.voice is None:
        await interaction.response.send_message("먼저 음성 채널에 들어가 주세요.", ephemeral=True)
        return

    await interaction.response.defer()
    voice_channel = interaction.user.voice.channel
    voice_client = interaction.guild.voice_client if interaction.guild else None

    if voice_client is None:
        voice_client = await voice_channel.connect()
    elif voice_client.channel != voice_channel:
        await voice_client.move_to(voice_channel)

    audio_url = extract_audio_url(url)
    source = discord.FFmpegPCMAudio(audio_url)
    voice_client.play(source)
    await interaction.followup.send(f"재생 시작: {url}")


@tree.command(name="중지", description="현재 재생을 중지하고 퇴장합니다.", guild=guild)
async def stop_music(interaction: discord.Interaction):
    voice_client = interaction.guild.voice_client if interaction.guild else None
    if voice_client is None:
        await interaction.response.send_message("현재 음성 채널에 연결되어 있지 않습니다.", ephemeral=True)
        return

    await voice_client.disconnect()
    await interaction.response.send_message("재생을 중지하고 음성 채널에서 나갔습니다.")


if not TOKEN:
    raise ValueError("DISCORD_TOKEN 값이 없습니다.")

client.run(TOKEN)

음악 봇 기본형은 결국 `yt-dlp`로 오디오 URL을 뽑고, FFmpeg로 재생하는 구조입니다.
텍스트 봇보다 외부 환경 의존성이 크다는 점만 기억해 두면 됩니다.

5. 입장·재생·정지 순서로 확인

python main.py

봇을 음성 채널에 부른 뒤 `/재생`으로 테스트 URL을 넣어 봅니다.
정상이라면 바로 소리가 나와야 합니다.

6. FFmpeg와 음성 연결에서 자주 끊긴다

• 소리가 안 나는 경우 대부분 FFmpeg 설치 문제이거나 봇 음성 권한 문제입니다.
• Opus not loaded 관련 메시지가 나오는 경우 오디오 환경 구성이 추가로 필요할 수 있습니다.
• 특정 URL에서만 실패하는 경우 yt-dlp 버전이 오래됐을 가능성이 큽니다.

7. 운영 서버에서는 음악 전용 채널을 둔다

일반 채팅 채널에서 음악 명령어를 섞으면 금방 어수선해집니다.

전용 봇 명령어 채널이나 음성 채널 묶음을 따로 둬야 합니다.

채널 구조는 디스코드 카테고리 채널 정리하는 법과 같이 보면 좋습니다.

8. 배포 전에는 로컬에서 먼저 안정화한다

음악 봇은 텍스트 봇보다 실패 지점이 많습니다.

따라서 로컬에서 FFmpeg, 권한, 재생 흐름이 모두 정상인지 먼저 확인한 뒤 배포해야 합니다.

9. 상시 운영 환경이 필요하다

음성 기능도 결국 계속 켜져 있어야 멤버가 필요할 때 바로 쓸 수 있습니다.

실운영용이라면 24시간 디스코드 봇 무료 호스팅, 디스호스트처럼 계속 켜진 환경이 필요합니다.

10. 음악 재생 뒤에는 FFmpeg 오류 대응까지 묶어 본다

음악 봇을 붙였다면 그 직후 가장 많이 만나는 FFmpeg 환경 오류를 바로 점검해야 합니다.

그 전에 음성 채널 구조를 다시 보고 싶다면 디스코드 서버 꾸미기, 채널 역할 배치 가이드와 디스코드 역할 설정 완벽 가이드, 관리자 운영진 멤버 봇 역할을 처음부터 정리하는 법을 같이 보면 됩니다.