# yt-dlp 설치 가이드

> ✅ **기본 동작: 자동 설치.** 서버가 처음 플레이리스트를 불러올 때 `%appdata%/.mc_custom/`
> (Linux 는 `~/.config/.mc_custom/`, macOS 는 `~/Library/Application Support/.mc_custom/`)
> 에 현재 OS/아키텍처에 맞는 `yt-dlp` 바이너리를 GitHub Releases 에서 받아 권한까지 부여합니다.
> 이미 받아둔 게 있으면 그대로 재사용합니다. 따라서 **일반적으로는 아래 수동 설치가 필요 없습니다.**
>
> 자동 설치가 실패하는 환경(외부 인터넷 차단, 권한 부족 등)에서만 아래 절차로 수동 설치하세요.

---

## 1. 가장 간단한 방법 — 단일 바이너리 내려받기 (권장)

Python/pip 없이도 동작하며, 권한도 깔끔합니다. 서버에 SSH로 접속한 뒤:

```bash
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp
yt-dlp --version
```

마지막 줄에서 버전(예: `2025.12.13`)이 출력되면 끝입니다.

업데이트는 같은 한 줄을 다시 실행하거나 `yt-dlp -U` 로 수행합니다.

> 만약 `/usr/local/bin` 에 쓰기 권한이 없는 환경이면 `~/.local/bin/yt-dlp` 로 받고
> `~/.local/bin` 이 `$PATH` 에 포함돼 있는지 확인하세요.

---

## 2. pipx 사용 (이미 pipx 가 깔려 있다면)

```bash
sudo apt-get update
sudo apt-get install -y pipx
pipx ensurepath
pipx install yt-dlp
```

업데이트: `pipx upgrade yt-dlp`

> Ubuntu 24.04 이상은 시스템 파이썬에 `pip install` 이 막혀 있어 (`PEP 668`)
> `pipx` 가 사실상 표준입니다. `pip install yt-dlp` 는 권장하지 않습니다.

---

## 3. apt 패키지 (구버전일 가능성 있음)

```bash
sudo apt-get update
sudo apt-get install -y yt-dlp
```

`apt` 의 yt-dlp 는 유튜브 정책 변경을 따라가지 못해 자주 깨집니다. **1번 방법을 추천합니다.**

---

## 부가: ffmpeg

설치기 EXE 에서 음악을 ogg 로 변환할 때 `ffmpeg` 도 필요합니다. 음악퀴즈 관리 사이트 자체는 필요 없지만,
설치기를 서버에서 디버깅한다면 함께 깔아두면 편합니다.

```bash
sudo apt-get install -y ffmpeg
```

---

## 동작 확인

설치 후 관리 사이트 서비스를 재시작할 필요는 **없습니다**. 매 요청마다 `spawn('yt-dlp', ['--version'])` 으로 직접 호출하므로,
`PATH` 상에 `yt-dlp` 가 있기만 하면 바로 인식됩니다.

확인:

```bash
sudo -u <서버를_실행하는_사용자> yt-dlp --version
```

예) systemd 로 `minecraft-launcher.service` 가 실행 중이고 사용자가 `claude` 라면:

```bash
sudo -u claude yt-dlp --version
```

여기서 버전이 출력되면 관리 사이트의 "플레이리스트 불러오기" 도 정상 동작합니다.

---

## 트러블슈팅

- **`yt-dlp: command not found`** — `$PATH` 에 설치 디렉터리가 없습니다. `which yt-dlp` 로 위치 확인.
- **`ERROR: ... HTTP Error 403`** — yt-dlp 가 너무 오래된 버전입니다. `yt-dlp -U` 로 업데이트.
- **`Sign in to confirm you're not a bot`** — 일시적인 IP 제한. 몇 분 후 재시도하거나, 같은 서버에서 다른 영상 재생을 시도해본 적이 있다면 IP 가 풀릴 때까지 기다려야 합니다.
- **systemd 서비스에서만 안 됨** — `PATH` 환경변수가 다를 수 있음. 서비스 유닛에 `Environment=PATH=/usr/local/bin:/usr/bin:/bin` 추가.