Jane-xiaoer/xiaoer-videolab

<div align="center">

🎬 Xiaoer VideoLab

한 번 클릭. 모든 동영상. 로컬 저장.

툴바 버튼 하나만 누르면 현재 페이지의 동영상이 ~/Downloads 폴더에 저장됩니다. 작고 가벼운 로컬 yt-dlp 데몬이 구동되며 — 1800개 이상의 사이트를 즉시 지원합니다 (YouTube · Bilibili · X/Twitter · TikTok · Vimeo · Twitch · Weibo …).

!Platform !Manifest V3 !Python stdlib only !No tracking

&nbsp;

</div>

---

🙏 기여자분들께 감사드립니다 / 致谢贡献者

이 프로젝트는 다음 분들 덕분에 더 좋아졌습니다 — 감사합니다! / 本项目因他们而更好,衷心感谢!

• @ttmouse — 팝업 히스토리 패널, 멈춘 다운로드 취소, 재생 / 폴더 열기, 원클릭 데몬 시작 (#4)

• @jzq1212 (林以恒) — Windows 지원: 크로스 플랫폼 데몬 + PowerShell 설치 스크립트 (#1)

• @alick-zhang — Windows 요청을 제기하여 위의 Windows 지원이 시작됨 (#3)

<br>弹出历史面板、取消卡住的下载、播放 / 打开文件夹、一键启动服务 <br>Windows 支持:跨平台 daemon + PowerShell 安装脚本 <br>提出 Windows 需求,促成了上面的 Windows 支持

이슈 및 PR 환영합니다 — 여러분의 이름도 여기에 추가됩니다. / 欢迎提 issue 和 PR,你的名字也会出现在这里。

---

Why (왜 만들었나)

브라우저 동영상 다운로더는 대부분 "모든 사이트의 모든 것을 읽어라"는 권한을 요구하고 사용자 정보를 외부로 전송하는 수상한 확장 프로그램 투성입니다. Xiaoer VideoLab은 정반대의 접근 방식을 취합니다:

• 확장 프로그램은 거의 아무것도 하지 않습니다. 버튼을 클릭할 때 현재 탭의 URL만 읽어서 127.0.0.1로 POST 요청을 보냅니다. 페이지 스크래핑, 콘텐츠 스크립트, 원격 서버가 없습니다.
• 다운로드는 로컬에서 이루어집니다. 작은 Python 데몬이 URL을 yt-dlp(검증된 오픈소스 다운로더)에 전달합니다. 모든 지능은 사용자가 감사할 수 있는 도구에 있습니다.
• 사용자가 요청한 동영상을 가져오기 위해 yt-dlp가 보내는 요청 외에는 어떤 것도 사용자의 기기를 떠나지 않습니다.

How it works (작동 방식)

 ┌─────────────────────┐   click    ┌──────────────────────────┐         ┌──────────┐
 │  Browser toolbar     │ ─────────► │  daemon @ 127.0.0.1:7788 │ ──────► │  yt-dlp  │ ──► ~/Downloads
 │  (Chrome MV3 ext.)   │  POST url  │  (Python stdlib, launchd)│  spawn  └──────────┘        │
 └─────────────────────┘            └──────────────────────────┘                              ▼
        ▲   badge: … ✓ ✕ !                       │                                   macOS notification
        └───────────────────────────────────────┘                                     "✅ <filename>"

• 데몬 — Python 표준 라이브러리 http.server, 127.0.0.1:7788에서 수신 대기, 로그인 시 launchd에 의해 시작됩니다.
• 확장 프로그램 — Chrome MV3, 단일 툴바 버튼, tab.url을 가져와 데몬에 POST합니다.
• 출력 — ~/Downloads/<platform><title><date>.mp4 (기본적으로 ≤1080p mp4; 설정 가능).
• 로그 — ~/Library/Logs/xiaoer-videolab.log

✅ 다운로드 가능한 항목

yt-dlp의 1872개 추출기로 구동 — 대부분의 동영상 사이트에서 작동합니다. 실제 사용 가능한 사이트 목록:

		사이트
	✅ 테스트 완료 및 확인됨	YouTube · Vimeo · Bilibili (B站) · Douyin (抖音) · Xiaohongshu (小红书)
	✅ 지원됨 (yt-dlp 추출기, 동일한 경로)	X/Twitter · Ixigua (西瓜) · Instagram · Reddit · Dailymotion · Facebook · TikTok\* · …그 외 약 1860개
	⚠️ 무료 콘텐츠만 가능	Youku (优酷) · iQiyi (爱奇艺) — VIP / DRM 보호 에피소드는 다운로드 불가
	🚫 권장하지 않음	Weibo (微博) · Zhihu (知乎) — 아래 참고
	❌ 지원되지 않음	Kuaishou (快手) & Tencent Video (腾讯视频) — 추출기 없음; WeChat Channels (视频号) — 앱 내장 및 암호화됨

🚫 Weibo / Zhihu — 권장하지 않음. 해당 웹 페이지는 결합된 SPA 피드(TikTok과 유사)입니다. 동영상은 큰 페이지의 작은 일부일 뿐이며, 일반적으로 단일 동영상을 독립적인 URL로 열 수 없습니다. 깔끔한 개별 동영상 주소가 없으면 버튼이 신뢰할 수 있는 대상을 찾을 수 없으므로 사용을 권장하지 않습니다.

>

\* TikTok / 해외 사이트는 접근 가능한 네트워크(중국 본토에서는 프록시; 일부 데이터센터 IP는 TikTok API에 의해 차단됨)가 필요합니다.

>

🎯 视频号 / 快手 / 小程序 / 直播流? 이러한 것들은 앱 내부에 있으며 패킷 스니핑이 필요합니다 — res-downloader를 사용하세요. 이 도구는 yt-dlp 생태계에 초점을 맞춥니다.

抖音 & 小红书는 특별한 페이지 내 그래버를 사용합니다(yt-dlp가 읽을 수 없음). 따라서 페이지에서 동영상이 열려/재생 중일 때 버튼을 클릭하세요.

참고: 平台 (플랫폼) 및 标题 (제목)은 파일 이름에 자동으로 감지됩니다; 日期 (날짜)는 다운로드한 날짜입니다.

TL;DR (이전에 해본 적이 있다면)

brew install yt-dlp ffmpeg
git clone https://github.com/Jane-xiaoer/xiaoer-videolab.git
cd xiaoer-videolab &&./scripts/install.sh
# 그런 다음 chrome://extensions/에서 extension/ 폴더를 압축 해제된 확장 프로그램으로 로드하세요.

---

설치 — 단계별 가이드

처음이신가요? 아래의 모든 단계를 따르세요. 약 5분이 소요되며 한 번만 하면 됩니다.

필요한 것

• macOS (launchd를 통한 백그라운드 서비스) 또는 Windows 10/11 (작업 스케줄러를 통해).
• Chromium 기반 브라우저 — Chrome, Arc, Edge, Brave 또는 Dia.
• 약 5분.

Windows 사용자? 아래 A & B 부분은 macOS용입니다. 🪟 Windows 사용자 로 이동한 후, C 부분으로 돌아오세요.

코딩 방법을 알 필요는 없습니다. 몇 가지 명령어를 복사하여 붙여넣기만 하면 됩니다.

Part A · 엔진 설치 (한 번만)

이 도구는 실제 작업을 수행하는 오픈소스 다운로더 yt-dlp 앞에 있는 친숙한 버튼입니다. 따라서 먼저 yt-dlp를 설치합니다.

A1. Terminal 앱을 엽니다. (⌘ Space를 누르고 Terminal을 입력한 후 Enter를 누르세요.)

<!-- 截图位: docs/images/01-terminal.png -->

A2. Homebrew를 설치합니다 (Mac용 패키지 관리자). 이미 설치되어 있다면 A3로 건너뛰세요. 다음을 Terminal에 붙여넣고 Enter를 누른 후 안내를 따르세요:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

A3. yt-dlp와 ffmpeg를 설치합니다:

brew install yt-dlp ffmpeg

ffmpeg는 중요합니다 — 없으면 일부 사이트에서 오디오 전용 또는 낮은 품질로 제공됩니다. 동영상과 오디오가 별도 스트림으로 제공되며 ffmpeg가 이를 다시 병합하기 때문입니다.

Part B · Xiaoer VideoLab 설치

B1. Terminal에서 다음 세 줄을 붙여넣으세요:

git clone https://github.com/Jane-xiaoer/xiaoer-videolab.git
cd xiaoer-videolab./scripts/install.sh

B2. 성공하면 마지막 줄이 다음과 같이 표시됩니다:

✓ Daemon running at http://127.0.0.1:7788
  Log: ~/Library/Logs/xiaoer-videolab.log

Next: load the browser extension
  1. Open chrome://extensions/...

<!-- 截图位: docs/images/02-install-success.png -->

이는 백그라운드 다운로더가 설치되었으며 로그인할 때마다 자동으로 시작됨을 의미합니다. Terminal을 다시 사용할 필요가 없습니다.

🪟 Windows 사용자? (Parts A & B 대신 이 작업을 수행)

브라우저 단계(Part C & D)는 모든 OS에서 동일합니다 — 엔진 + 서비스 설치만 다릅니다.

W1. 엔진을 설치합니다. PowerShell을 열고 다음을 실행합니다 (winget 사용, Win 10/11에 내장):

winget install Python.Python.3.11 yt-dlp.yt-dlp ffmpeg

W2. Xiaoer VideoLab을 설치합니다. 녹색 Code → Download ZIP 버튼으로 코드를 다운로드하거나(압축 해제), PowerShell에서:

git clone https://github.com/Jane-xiaoer/xiaoer-videolab.git
cd xiaoer-videolab
powershell -ExecutionPolicy Bypass -File scripts\install.ps1

설치 프로그램은 로그인 시작 작업을 등록하고 쿠키를 가져올 브라우저(edge/chrome)를 묻습니다. 나중에 제거하려면: powershell -ExecutionPolicy Bypass -File scripts\uninstall.ps1

이제 아래 Part C로 계속 진행하세요 — 툴바 버튼 로드는 모든 곳에서 동일합니다.

Part C · 툴바 버튼 추가

브라우저 버튼은 아직 Chrome 웹 스토어에 없으므로 수동으로 로드합니다. 이는 정상적이고 안전합니다.

아래 스크린샷은 이 부분의 모든 단계를 표시합니다(레이블은 중국어이지만 빨간색 화살표가 정확한 버튼을 가리킵니다): ① 주소 열기 · ② 개발자 모드 켜기 · ③ "압축 해제된 확장 프로그램 로드" 클릭 · ④ 확장 프로그램 스위치 켜기

!확장 프로그램 로드의 네 단계: 주소 열기, 개발자 모드 활성화, 압축 해제된 확장 프로그램 로드, 켜기

C1. 새 브라우저 탭을 열고 다음으로 이동: chrome://extensions/ (Edge에서는 edge://extensions/, Arc/Brave에서는 동일한 chrome://extensions/.)

C2. 개발자 모드를 켭니다 — 오른쪽 상단의 스위치입니다.

<!-- 截图位: docs/images/03-developer-mode.png -->

C3. 압축 해제된 확장 프로그램 로드 버튼(왼쪽 상단)을 클릭합니다. 폴더 선택기가 열립니다.

<!-- 截图位: docs/images/04-load-unpacked.png -->

C4. 리포지토리를 클론한 위치로 이동하여 그 안의 extension 폴더를 선택합니다 (예: xiaoer-videolab/extension). 선택을 클릭합니다.

Xiaoer VideoLab이라는 카드가 확장 프로그램 목록에 나타납니다.

<!-- 截图位: docs/images/05-extension-card.png -->

C5. 툴바에서 퍼즐 조각 아이콘을 클릭하고 Xiaoer VideoLab을 찾은 다음 핀을 클릭하여 아이콘이 툴바에 고정되도록 합니다.

<!-- 截图位: docs/images/06-pin-toolbar.png -->

Part D · 첫 번째 동영상 다운로드

D1. 동영상 페이지를 엽니다 (YouTube, Bilibili, X, TikTok …).

D2. 툴바에서 Xiaoer VideoLab 아이콘을 클릭합니다.

<!-- 截图位: docs/images/07-click-button.png -->

D3. "Downloading…" 알림이 표시된 다음 완료되면 "✅ &lt;filename&gt;" 알림이 표시됩니다. 아이콘에 작은 배지도 표시됩니다:

	배지	의미
	…	요청 전송됨, 다운로드 중
	✓	데몬이 작업을 수락함 (백그라운드에서 다운로드 계속)
	✕	데몬에 연결할 수 없음
	!	데몬이 오류를 반환함 (알림/로그 확인)

<!-- 截图位: docs/images/08-notification.png -->

D4. ~/Downloads 폴더에서 동영상을 찾으세요. 🎉

<!-- 截图位: docs/images/09-downloads-folder.png -->

이제부터는 동영상 열기 → 버튼 클릭만 하면 됩니다.

설정

모든 항목은 선택 사항입니다 — 설정한 후 ./scripts/install.sh를 다시 실행하여 서비스에 적용하세요:

	변수	기본값	설명
	VIDEOLAB_PORT	7788	데몬 포트 — ⚠️ 변경하는 경우 extension/background.js (DAEMON) 및 extension/manifest.json (host_permissions)도 동일한 포트로 수정해야 합니다. 그렇지 않으면 버튼이 데몬에 연결할 수 없습니다
	VIDEOLAB_DOWNLOADS	~/Downloads	파일이 저장되는 위치
	VIDEOLABYTDLP	자동 감지	yt-dlp 바이너리 경로 (자동 감지는 yt-dlp-nightly 빌드가 설치된 경우 우선 사용 — FAQ의 HTTP Error 412 참조)
	VIDEOLAB_PREFIX	(없음)	파일 이름 접두사, 예: 小耳-
	VIDEOLABMAXHEIGHT	1080	최대 동영상 높이 (4K의 경우 2160 설정)
	VIDEOLABCOOKIESBROWSER	(끄기)	로그인이 필요한 / 비공개 동영상을 위해 브라우저(chrome/brave/firefox/edge/safari)에서 쿠키 가져오기
	VIDEOLABAPPNAME	Xiaoer VideoLab	알림에 표시되는 이름

# 예: 4K, Chrome에서 로그인 쿠키 가져오기, 파일 이름에 브랜드 접두사 추가
VIDEOLAB_MAX_HEIGHT=2160 VIDEOLAB_COOKIES_BROWSER=chrome VIDEOLAB_PREFIX="小耳-"./scripts/install.sh

명령어

# 데몬이 살아있는지 확인
curl http://127.0.0.1:7788/health

# 로그 확인
tail -f ~/Library/Logs/xiaoer-videolab.log

# 데몬 재시작
launchctl unload ~/Library/LaunchAgents/com.xiaoer.videolab.plist
launchctl load   ~/Library/LaunchAgents/com.xiaoer.videolab.plist

# 확장 프로그램 없이 다운로드
curl -X POST http://127.0.0.1:7788/download \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

# 모든 것 업데이트 (최신 코드 + 최신 yt-dlp 엔진)

[...truncated...]