# 영상에서 자료 뽑기 — yt-dlp + 음성→글
> **이 장에서 배우는 것**
> 영상 한 편을 **읽을 수 있는 글**로 바꾸는 순서. 그리고 그 순서에서
> **다운로드를 건너뛰는 지점**이 어디인지.
## 먼저 — 영상을 정말 받아야 하는가
[앞 장](/guide/ht-crawlee-stealth)과 같은 질문입니다. 영상 파일은 **이 가이드에서
다루는 것 중 가장 무겁고 가장 자주 깨지는 입력**입니다. 위에서부터 확인하세요.
| 필요한 것 | 받을 것 | 크기 감각 |
|---|---|---|
| 무슨 말을 했는지 | **자막** | KB |
| 제목·설명·길이·조회수 | **메타데이터(JSON)** | KB |
| 자막이 없는 영상의 내용 | **오디오만** | MB |
| 화면에 나온 것(자료 화면, 제품, 자막이 아닌 글자) | 영상 | 수백 MB |
**대부분의 업무는 첫 두 줄에서 끝납니다.** "이 채널이 요즘 무슨 얘기를 하나",
"경쟁사 신제품 영상 열 편 요약해줘" 같은 일에 영상 파일은 필요 없습니다.
```mermaid
graph TD
A["영상에서 뭔가 알아내야 한다"] --> B{"자막이 있나"}
B -->|있다| C["자막만 받기 — 여기서 끝"]
B -->|없다| D["오디오만 받기"]
D --> E["음성 → 글"]
C --> F["요약·분류·표 만들기"]
E --> F
A --> G{"화면을 봐야 하나"}
G -->|그렇다| H["그때 비로소 영상"]
```
## 그 다음 — 해도 되는 일인지
기술보다 **먼저**입니다. 도구는 이 중 어느 것도 해결해 주지 않습니다.
- **이용약관.** 대부분의 영상 플랫폼은 약관에서 다운로드를 제한합니다.
기술적으로 되는 것과 해도 되는 것은 다릅니다.
- **저작권.** 영상은 저작물입니다. **자막·대본을 요약해 내부 판단에 쓰는 것**과
**받은 영상을 재배포하거나 다시 편집해 올리는 것**은 완전히 다른 문제입니다.
뒤쪽은 이 장의 범위가 아닙니다.
- **로그인·비공개 뒤.** 계정 약관에 걸립니다. 내 계정으로 **내가 올린 것**을
받는 것과 장벽을 우회하는 것은 다릅니다.
- **개인정보.** 공개된 영상이라도 사람이 찍혀 있으면 처리 근거가 필요합니다.
- **상대 서버 부담.** 채널 전체를 한 번에 긁지 마세요. 간격을 두세요.
**가장 편한 경우는 내 채널, 내 영상입니다.** 내가 올린 영상의 자막을 모아
정리하거나 지난 방송 원고를 다시 쓰는 용도라면 위 대부분이 애초에 문제가 되지
않습니다. 그 밖의 대상이라면 **요약해서 내부에서 읽는 선까지**로 두는 편이
안전합니다.
## 도구 — yt-dlp 하나
이 영역은 선택지가 사실상 하나입니다.
| | 무엇 | 상태 |
|---|---|---|
| **yt-dlp** | 유튜브·인스타·틱톡 포함 수천 개 사이트 | 사실상 표준. 주 단위로 갱신 |
| youtube-dl | yt-dlp의 원본 | 정체. 새 사이트 변경을 못 따라갑니다 |
| Node 라이브러리들 | 유튜브 전용이 대부분 | 플랫폼이 바뀔 때마다 깨집니다 |
**ffmpeg가 함께 필요합니다.** yt-dlp가 화질·음질을 따로 받아 합치거나 오디오를
변환할 때 내부에서 부릅니다. 없으면 "합칠 수 없다"며 반쪽짜리 파일을 남깁니다.
```bash
# macOS
brew install yt-dlp ffmpeg
# 확인
yt-dlp --version
```
## 명령 네 개
### 1. 메타데이터만 — 가장 싸다
```bash
yt-dlp --skip-download --dump-json "<주소>" > out/meta.json
```
제목·길이·업로드일·설명·조회수가 JSON 한 덩어리로 나옵니다. **무엇을 볼지
고르는 단계**에 쓰세요. 채널 목록은 이렇게 봅니다.
```bash
yt-dlp --flat-playlist --dump-json "<채널 주소>" > out/list.jsonl
```
### 2. 자막만 — 대부분 여기서 끝
```bash
yt-dlp --skip-download \
--write-subs --write-auto-subs \
--sub-langs "ko,en" --convert-subs srt \
-o "out/%(id)s.%(ext)s" "<주소>"
```
`--write-subs`는 **올린 사람이 넣은 자막**, `--write-auto-subs`는 **플랫폼이
자동 생성한 자막**입니다. 둘 다 켜 두고 있는 쪽을 씁니다.
> **자동 자막은 원문 그대로가 아닙니다.** 고유명사·숫자·제품명이 자주 틀립니다.
> 요약과 흐름 파악에는 충분하지만, **인용하거나 숫자를 옮길 때는 원본을 확인**
> 하세요.
### 3. 오디오만 — 자막이 없을 때
```bash
yt-dlp -f bestaudio -x --audio-format m4a \
-o "out/%(id)s.%(ext)s" "<주소>"
```
`-x`는 오디오만 추출입니다. **영상 대비 용량이 한 자릿수 퍼센트**로 떨어집니다.
다음 단계인 음성→글에는 오디오만 있으면 됩니다.
### 4. 영상 — 화면을 봐야 할 때만
```bash
yt-dlp -S "res:720" -o "out/%(id)s.%(ext)s" "<주소>"
```
`-S "res:720"`은 **720p를 넘지 않는 선에서 가장 좋은 것**을 고릅니다. 원본
화질을 그대로 받을 이유가 거의 없습니다 — 자료로 볼 것이라면 720p로 충분하고
용량이 몇 배 차이 납니다.
### 두 번 받지 않기
```bash
yt-dlp --download-archive out/done.txt ...
```
받은 것의 id를 파일에 적어 두고 **다음 실행에서 건너뜁니다.** 매일 도는
파이프라인에서는 이게 없으면 같은 영상을 계속 다시 받습니다.
## 글로 바꾸기
오디오를 받았으면 [음성과 이미지 다루기](/guide/ht-voice-image)의 경로를 그대로
씁니다.
```bash
curl -X POST http://localhost:27777/api/ai/v1/audio/transcriptions \
-H "Authorization: Bearer $HT_KEY" \
-F file=@out/abc123.m4a \
-F model="<모델 이름>"
```
여기까지 오면 영상은 **글**이 됐고, 그 다음은 이 가이드 앞부분과 똑같습니다.
[REST로 업무](/guide/ht-rest-api)를 만들어 요약·분류·표 만들기를 맡기면 됩니다.
```mermaid
graph TD
A["1 목록
terminal"] --> B["2 자막 또는 오디오
terminal"]
B --> C["3 음성 → 글
모델 API"]
C --> D["4 요약·정리
task"]
D --> E["out/요약.md"]
```
3번은 **자막이 있으면 통째로 건너뜁니다.** 이 파이프라인에서 가장 비싼 칸이라,
2번에서 자막을 먼저 확인하는 것만으로 대부분의 비용이 사라집니다.
## HyperTeams에서 돌리기
수집은 판단이 없는 작업이라 `task`가 아니라 **`terminal`**입니다.
[사례 — 콘텐츠 공장](/guide/ht-case-factory)의 수집 칸과 같은 자리입니다.
```
매일 07:00 · kind: terminal
node collect-videos.mjs
```
- 파일은 [작업 폴더](/guide/ht-working-directory) 안에 둡니다. `out/`은 이진
파일이 쌓이는 곳이라 버전 관리에서 빼세요.
- **오래 걸립니다.** 열 편이면 분 단위, 음성→글까지 붙으면 그 이상입니다.
화면 앞에서 기다릴 일이 아니라 [예약](/guide/ht-pipelines)으로 돌릴 일입니다.
- 해석과 가공은 다음 단계 `task`에 맡깁니다. 수집과 판단을 한 칸에 섞으면
실패했을 때 어느 쪽이 문제인지 알 수 없습니다.
### Connect에서 한 편만 볼 때
팀 워크스페이스에서 **영상 하나를 그 자리에서 요약**하는 정도라면 위 배선이
필요 없습니다. [도구 설정](/guide/cn-tool-settings)의 웹 도구가 유튜브 내용
가져오기를 포함합니다. 채널 단위로 매일 돌릴 때만 이 장으로 오세요.
## 유지비 — 여기도 한 번 만들고 끝나지 않습니다
| 무엇이 | 어떻게 |
|---|---|
| 플랫폼 | 예고 없이 바뀝니다. **인스타·틱톡이 유튜브보다 훨씬 자주** |
| yt-dlp | 그걸 뒤따라 고칩니다. 며칠 지난 버전이 이미 안 되기도 합니다 |
| 자막 유무 | 어제 있던 자동 자막이 오늘 없을 수 있습니다 |
그래서 **버전을 고정하지 마세요.** 다른 의존성과 반대입니다.
```bash
yt-dlp -U # 실패하면 가장 먼저 해 볼 것
```
그리고 **성공을 가정한 파이프라인을 만들면 안 됩니다.** 조용히 빈 결과를
내려보내는 것이 가장 나쁩니다 — 뒷단계가 그 빈 값으로 그럴듯한 요약을
지어냅니다.
```
[완료 조건]
- 수집 건수가 0이면 결과 파일을 쓰지 말고 실패로 알릴 것
- 자막도 오디오도 못 받은 항목은 건너뛰되 목록에 남길 것
```
## 자주 하는 실수
### 자막을 확인하지 않고 영상부터 받습니다
가장 흔합니다. 자막 한 번 확인하면 끝날 일에 수백 MB와 음성→글 시간을 씁니다.
**순서가 자막 → 오디오 → 영상**인 이유입니다.
### 자동 자막을 원문처럼 인용합니다
앞에서 적었지만 다시 씁니다. 자동 자막의 **숫자와 고유명사는 믿지 마세요.**
### 채널 전체를 한 번에 긁습니다
차단되고, 오래 걸리고, 대부분 필요 없는 영상입니다. **메타데이터로 먼저
고르고** 고른 것만 받으세요.
### 받은 영상을 다시 올립니다
이 장은 **자료로 읽기 위한** 수집을 다룹니다. 재배포·재편집은 저작권 문제이고,
도구가 해결해 주지 않습니다.
---
## 확인
**1. 영상 열 편을 요약해야 합니다. 무엇부터 받습니까?**
답
**메타데이터와 자막**입니다. 자막이 있으면 거기서 끝나고, 영상 파일도 음성→글
단계도 필요 없습니다. 영상은 화면을 봐야 할 때만 받습니다.
**2. 왜 yt-dlp는 버전을 고정하지 않습니까?**
답
**상대 플랫폼이 계속 바뀌고 yt-dlp가 그것을 뒤따라 고치기** 때문입니다. 고정해
두면 어느 날 조용히 실패합니다. 다른 의존성과 반대로, 실패하면 `yt-dlp -U`가
가장 먼저 해 볼 일입니다.
**3. 수집이 0건일 때 무엇을 해야 합니까?**
답
**결과 파일을 쓰지 말고 실패로 알립니다.** 빈 결과를 내려보내면 다음 단계가 그
빈 값으로 그럴듯한 요약을 지어내고, 아무도 안 보는 시간에 그게 그대로 굳습니다.
---
다음은 국내 실무에서 가장 자주 막히는 확장자입니다 →
[공문서 다루기 — hwp·hwpx](/guide/ht-korean-docs)