---
name: youtube-highres-expert
description: Expert in YouTube high-resolution (1080p, 4K) playback bypass strategies. Use this skill when the user asks for high-quality YouTube streaming in PotPlayer or other media players, needs to fix "JS-less" playback, or wants to update YouTube client versions based on yt-dlp source code.
---

# 📺 YouTube High-Resolution Expert

이 스킬은 유튜브의 최신 보안 정책(PoToken, Signature)을 우회하여 4K 이상의 고화질 스트리밍 주소를 직접 확보하는 전문 엔지니어 모드입니다. 주로 **JS-LESS**(웹 브라우저의 자바스크립트 엔진 없이) 클라이언트를 활용하여 시그니처 암호 해독 없이 직접 URL을 추출하는 전략을 구사합니다.

## 🚀 주요 전략: JS-LESS Bypass

1. **클라이언트 위조:** 일반 웹 브라우저 대신 `ANDROID`, `ANDROID_VR`, `IOS` 등 특정 모바일/VR 기기의 클라이언트로 위장합니다.
2. **직접 주소 확보:** 이 클라이언트들은 보안상의 이유로(또는 노후 기기 지원을 위해) `signatureCipher` 대신 평문 `url`을 반환하는 경우가 많습니다.
3. **STS(signatureTimestamp) 동기화:** 유튜브 서버가 요구하는 최신 `sts` 값을 요청 본문에 포함하여 차단을 방어합니다.

---

## 🛠️ 검증된 클라이언트 구성 (Verified Database)

| 클라이언트 이름 | 최신 버전 | 고화질 및 특징 | 추천 순위 |
| :--- | :--- | :--- | :--- |
| **ANDROID** | `21.02.35` | 4K/2160p60 지원, 가장 많은 포맷 제공 | 🥇 1위 |
| **ANDROID_VR** | `1.65.10` | 4K 지원, 현재 PotPlayer 기본값 | 🥈 2위 |
| **IOS** | `21.02.3` | 4K 지원, HLS 스트리밍에 유리 | 🥉 3위 |

**현재 권장 STS (signatureTimestamp):** `20536` (2026-03-30 기준)

---

## 🔄 클라이언트 버전 실시간 업데이트 가이드

유튜브 정책 변화로 기존 버전이 막힐 경우, `yt-dlp` 공식 GitHub 소스에서 새로운 클라이언트 정보를 실시간으로 추출할 수 있습니다.

- **Reference URL:** `https://raw.githubusercontent.com/yt-dlp/yt-dlp/refs/heads/master/yt_dlp/extractor/youtube/_base.py`

```powershell
# GitHub 마스터 브랜치에서 최신 정보를 직접 읽어옵니다.
python ./scripts/extract_clients.py
```

---

## 🤖 AI 자가 유지보수 사이클 (Self-Maintenance Loop)

유튜브의 정책 변화로 인해 기존에 기록된 클라이언트 버전이 더 이상 고화질을 반환하지 않거나 재생이 실패할 경우, 다음의 자동화된 복구 프로세스를 수행하십시오.

### Step 1: 최신 클라이언트 버전 추출

내장된 `extract_clients.py`를 실행하여 `yt-dlp` GitHub 소스로부터 최신 클라이언트 정보를 수집합니다.

```powershell
python ./scripts/extract_clients.py
```

### Step 2: 추출된 버전의 유효성 검증

수집된 최신 버전이 **JS-LESS** 환경에서 1080p 이상의 고화질을 지원하는지 진단 도구로 확인합니다.

```powershell
# 예시: ANDROID 21.02.40 버전 검증
python ./scripts/diagnose_clients.py ANDROID 21.02.40
```

### Step 3: 스킬 데이터베이스(SKILL.md) 갱신

검증 결과가 **[SUCCESS]**인 경우, 본 파일(`SKILL.md`)의 **## 🛠️ 검증된 클라이언트 구성 (Verified Database)** 섹션에 있는 표와 STS 값을 최신 정보로 직접 수정하여 기록하십시오.

### Step 4: 최종 배포 및 적용

업데이트된 정보를 바탕으로 PotPlayer나 기타 재생기의 환경 설정을 최신 클라이언트와 STS 값으로 변경하여 최종 해결 여부를 확인합니다.

---

## 📝 PotPlayer 적용 가이드 (AngelScript)

확장 프로그램(`.as`) 파일의 `GetVideoJson` 함수 내 `context` 섹션을 다음과 같이 업데이트하여 적용합니다:

```angelscript
// 예시: ANDROID 클라이언트 적용 (PotPlayer)
string context = "{\"client\":{\"clientName\":\"ANDROID\",\"clientVersion\":\"21.02.35\",\"hl\":\"ko-KR\",\"gl\":\"KR\",\"androidSdkVersion\":30}}";
// sts 값 업데이트 (sts=20536)
string payload = "{\"context\":" + context + ",\"videoId\":\"" + videoId + "\",\"playbackContext\":{\"contentPlaybackContext\":{\"signatureTimestamp\":20536}}}";
```

## ⚠️ 주의 사항

- **JS-LESS 클라이언트**가 더 이상 작동하지 않을 경우(유튜브가 강제로 PoToken을 요구할 경우), `WEB` 클라이언트와 함께 `signatureCipher` 복호화 로직(JS Interpreter)을 사용해야 할 수 있습니다. 현재는 위의 클라이언트들이 가장 안정적입니다.