AutoCliper.AI — 에이전트 스킬
긴 YouTube 동영상 하나를 5~15개의 중국어 포장 및 하드코딩 자막이 포함된 숏클립으로 변환합니다.
이 문서는 AutoCliper 파이프라인을 실행하는 모든 AI 에이전트의 단일 진실 공급원(Single Source of Truth) 입니다. 번호가 매겨진 각 단계를 순서대로 따르십시오. 단계를 건너뛰지 마십시오. 파일 이름을 추측하지 마십시오 — 각 쓰기 작업 후 파일 시스템을 확인하십시오.
0. 사전 점검
다른 작업을 수행하기 전에 환경을 확인하십시오. 정확한 차단 원인을 보고하고, 점검에 실패하면 중지하십시오.
| 점검 | 명령어 | 통과 조건 |
|---|---|---|
| yt-dlp 설치 | which yt-dlp | 경로 반환 |
| ffmpeg 설치 | which ffmpeg | 경로 반환; 없으면 python3 -c "import imageio_ffmpeg; print(imageio_ffmpeg.get_ffmpeg_exe())" 시도 |
| Python 3.9+ | python3 --version | >= 3.9 |
| 스킬 저장소 확인 | 스킬 루트 기준으로 corekit/ 디렉토리 존재 여부 확인 | corekit/__init__.py 존재 |
모든 후속 명령어를 위해 환경 변수를 설정하십시오:
export PYTHONPATH="<AutoCliper.AI-저장소-경로>"
아래 모든 python3 -m corekit.* 명령어는 이 PYTHONPATH가 설정되어 있다고 가정합니다.
1. 작업 공간 생성
이 동영상을 위한 출력 디렉토리 구조를 생성하십시오. <slug>는 동영상 제목 또는 ID에서 파생하십시오 — 소문자, 하이픈, 공백 없음, 특수 문자 없음.
mkdir -p "studio/<slug>/intake"
mkdir -p "studio/<slug>/intel"
mkdir -p "studio/<slug>/exports"
예상 결과:
studio/<slug>/
├── intake/ ← 원본 동영상 + 자막 저장
├── intel/ ← 분석 결과물 저장
└── exports/ ← 클립별 폴더 저장
2. 소스 자산 가져오기
YouTube에서 동영상 및 자막 다운로드:
python3 -m corekit.fetch_source "<YouTube_URL>" "studio/<slug>/intake"
내부 동작: 다운로더는 먼저 영어 자막(en, en-US, en-orig)을 시도하고, 실패 시 중국어 자막(zh-Hans, zh-CN, zh)을 시도합니다. 인증된 접근을 위해 --cookies-from-browser chrome을 사용합니다.
명령어 완료 후, intake 폴더를 나열하고 다음을 식별하십시오:
.mp4동영상 파일 (파일명에 동영상 제목과 ID가 포함될 수 있음).srt자막 파일 (언어 태그.en.srt또는.zh-Hans.srt등이 포함될 수 있음)- 사이드카 파일 (
.ytdl,.jpg등) — 기록해 두되 필요하지는 않음
다운로드 실패 시:
- 쿠키 오류 → 사용자에게 Chrome YouTube 로그인을 새로고침한 후 재시도하도록 안내
- 자막을 찾을 수 없음 → "이 동영상에 사용 가능한 자막이 없습니다"라고 보고하고 중지
- 동영상 다운로드 오류 → 다른 형식으로 한 번 재시도; 계속 실패하면 오류 보고
정확한 파일 이름을 다음 단계를 위해 기록하십시오. 이름을 추측하거나 하드코딩하지 마십시오.
3. 자막을 JSON으로 파싱
SRT 자막 파일을 더 쉬운 분석을 위해 구조화된 JSON으로 변환:
python3 -m corekit.subtitle_to_json \
"studio/<slug>/intake/<정확한-srt-파일명>" \
"studio/<slug>/intel/transcript.json"
출력 파일이 존재하고 큐 객체 배열을 포함하는지 확인하십시오. 각 큐는 다음과 같습니다:
{
"index": 1,
"start": "00:00:01,234",
"end": "00:00:03,456",
"start_seconds": 1.234,
"end_seconds": 3.456,
"text": "the spoken content"
}
트랜스크립트가 비어 있거나 10개 미만의 큐가 있는 경우, "트랜스크립트가 너무 짧거나 손상되었습니다"라고 보고하고 중지하십시오.
4. 트랜스크립트 분석 및 후보 제안
이것은 가장 중요한 지적 단계입니다. 분석을 시작하기 전에 다음 파일을 읽으십시오:
- playbooks/clip-contract.md —
selected_clips.json의 정확한 JSON 스키마 정의 - playbooks/content-analysis-playbook.md — 다중 패스 분석 방법, 점수 기준, 리뷰 형식 정의
4a. 다중 패스 분석
단일 패스로 클립을 선택하려고 시도하지 마십시오. 다음 순서를 따르십시오:
패스 1 — 훑어보기 및 플래그 지정: transcript.json을 읽으면서 기억에 남고, 정보 밀도가 높고, 독창적이거나, 반직관적이거나, 감정적으로 날카로운 내용이 포함된 부분을 찾으십시오. 너무 적게 표시하는 것보다 너무 많이 표시하는 것이 좋습니다.
패스 2 — 경계 다듬기: 각 플래그 지정된 부분에 대해 주변 큐(앞뒤 5~10개 큐)를 다시 읽으십시오. 깔끔한 시작과 끝을 선택하십시오:
- 시작은 클립의 처음 3초 이내에 시청자를 사로잡는 대사여야 합니다
- 끝은 화자가 생각을 마친 후여야 합니다 — 문장 중간에서 끝나면 안 됩니다
- 유망한 순간을 위해 몇 초의 맥락이 필요하다면 시작을 더 앞으로 확장하십시오
- 생각이 흐려지면 끝을 해결될 때까지 확장하십시오
패스 3 — 완전성 확인: 각 후보에 대해 다음을 확인하십시오:
- 20~180초 길이 (그만한 가치가 있다면 3분까지 가능)
- 정확히 하나의 명확한 아이디어를 포함
- 시작 대사는 훅(hook)이지, 채우기(filler)가 아님
- 마지막 대사는 생각을 해결함
- 나머지 동영상을 보지 않아도 이해 가능
- 인사, 스폰서 멘트, Q&A 서두, 긴 잡담이 아님
패스 4 — 점수 및 순위: 각 후보를 네 가지 차원(1~5점)으로 평가하십시오:
hook— 처음 3초의 시작이 얼마나 매력적인가?clarity— 하나의 명확한 아이디어로 모호함이 적은가?standalone— 이전 맥락 없이 독립적으로 이해 가능한가?payoff— 결말이 유용하거나, 기억에 남거나, 공유할 가치가 있는가?
가중 총점으로 순위를 매기십시오: hook × 0.35 + clarity × 0.25 + standalone × 0.2 + payoff × 0.2
4b. 후보 수 가이드라인
| 원본 길이 | 목표 후보 수 |
|---|---|
| < 20분 | 5 – 8 |
| 20 – 60분 | 8 – 12 |
| > 60분 | 10 – 15 |
기본 실패 모드는 "너무 많은 것"이 아니라 "너무 적은 것"이어야 합니다. 확실하지 않으면 더 포함하십시오. 사용자가 정리할 것입니다.
4c. 자동 생성(잡음이 있는) 자막 처리
YouTube 자동 자막에는 종종 다음이 포함됩니다:
- 반복된 조각 (동일한 구문이 연속된 큐에 나타남)
- 누락된 구두점 및 대문자
- 잘못 들린 단어 (특히 이름, 기술 용어)
소스 자막이 자동 생성된 경우:
- 의도된 의미를 신중하게 추론하십시오 — 주장을 만들어내지 마십시오
- 클립 경계를 판단할 때 중복 조각은 무시하십시오
- 주변 맥락을 사용하여 문장이 실제로 끝나는 위치를 결정하십시오
- 후보 요약에 소스 품질이 낮다는 점을 명시하십시오
4d. 출력 파일 쓰기
두 개의 파일을 작성하십시오:
-
studio/<slug>/intel/selected_clips.json— 기계 판독 가능한 클립 결정.playbooks/clip-contract.md의 스키마를 정확히 따라야 합니다. -
studio/<slug>/intel/candidate-board.md— 사람이 읽을 수 있는 리뷰 테이블.
5. 사용자 리뷰를 위한 후보 제시
리뷰 친화적 형식으로 후보 목록을 표시하십시오. 각 후보에 대해 다음을 표시:
| 필드 | 형식 | 예시 |
|---|---|---|
| ID | clip-XX | clip-01 |
| 시간 범위 | HH:MM:SS → HH:MM:SS | 00:12:03 → 00:13:22 |
| 길이 | 사람이 읽기 쉬운 형식 | 1분 19초 |
| 제목 | 하나의 자극적인 중국어 제목, 12자 이하 | AI终将取代一切? |
| 요약 | 정확히 두 문장의 중국어 | 문장1: 무슨 내용인가. 문장2: 왜 볼 가치가 있는가. |
번호가 매겨진 표로 표시하여 사용자가 ID로 응답할 수 있도록 하십시오.
사용자가 "진행" 또는 "자동 선택"이라고 말하는 경우: 직접 최고 순위 후보를 선택하십시오. 1시간 동영상의 경우 최소 8개를 내보내십시오.
사용자가 특정 ID를 선택하는 경우: 해당 클립만 내보내십시오.
6. 각 선택된 클립 내보내기
사용자가 선택한(또는 자동 선택한) 각 클립에 대해 6a부터 6f까지의 단계를 순서대로 실행하십시오. 다음 클립으로 이동하기 전에 한 클립에 대한 모든 하위 단계를 완료하십시오.
6a. 동영상 부분 자르기
python3 -m corekit.cut_video \
"studio/<slug>/intake/<정확한-mp4-파일명>" \
<시작_초> <끝_초> \
"studio/<slug>/exports/<클립-폴더>/clip.mp4"
<클립-폴더> 명명 규칙은 XX-<제목-슬러그>입니다 (예: 01-ai-will-replace).
출력 파일이 존재하고 크기가 0이 아닌지 확인하십시오.
6b. 소스 자막 윈도우 처리
python3 -m corekit.window_subtitles \
"studio/<slug>/intake/<정확한-srt-파일명>" \
<시작_초> <끝_초> \
"studio/<slug>/exports/<클립-폴더>/clip.src.srt"
이것은 클립 윈도우와 겹치는 큐만 추출하고 모든 타임스탬프를 클립 시작이 00:00:00,000이 되도록 이동합니다.
출력 SRT에 최소 하나의 큐가 있는지 확인하십시오.
6c. 중국어 자막 번역
clip.src.srt를 읽고 간체 중국어로 번역하십시오. 결과를 같은 폴더에 clip.zh.srt로 작성하십시오.
번역 규칙 (엄격히 따르십시오):
- 자연스러운 구어체 중국어 — 문서/격식체 중국어가 아닙니다. 시청자는 짧은 동영상을 보고 있지 문서를 읽고 있는 것이 아닙니다.
- 타임스탬프를 정확히 유지 — 가독성을 위해 두 개의 큐를 병합해야 하는 경우가 아니라면 절대 임의로 타이밍을 변경하지 마십시오.
- 명명된 개체를 정확하게 유지 — 사람, 회사, 제품 이름, 숫자 및 인용구는 충실히 보존해야 합니다.
- 간결한 줄 — 짧은 동영상 속도에 맞는 짧은 중국어 구문을 선호하십시오. 긴 스크롤 자막은 유지율을 떨어뜨립니다.
- 필요한 경우 큐 간 재분배 — 영어 문장이 3개의 큐에 분할된 경우 해당 3개 큐에 중국어 텍스트를 재분배할 수 있습니다. 큐 순서를 유지하십시오.
- 큐를 축소하지 마십시오 — 40개의 큐를 가진 조밀한 영어 SRT는 약 35~45개의 중국어 큐를 생성해야 하며, 10개가 아니어야 합니다. 기본 실패 모드는 너무 적은 것보다 약간 너무 많은 것입니다.
- 진정한 중복만 제거 — 자동 자막은 종종 연속된 큐에서 동일한 조각을 반복합니다. 중복은 제거할 수 있지만 첫 번째 항목은 유지하십시오.
- 소스가 이미 중국어인 경우 — 번역하지 마십시오. 명백한 자동 자막 노이즈(반복 조각, 깨진 문자)만 정리하십시오.
6d. 제목 및 설명 생성
각 클립에 대해 다음을 생성하십시오:
제목 (처음 1초 오버레이용):
- 날카롭고, 클릭 가능하며, 독창적이어야 함
- 한국어 12자 이하 목표로 화면에 48포인트 글꼴 크기로 깔끔하게 표시되도록 함
- 도발적이거나 반대 의견일 수 있지만 화자의 의미에 충실해야 함
- 호기심, 긴장감 또는 계속 보고 싶은 욕구를 불러일으켜야 함
설명 (플랫폼 배포용):
- 한글 140자 이하 (중국어 텍스트 번역 시 참고)
- 다음을 언급해야 함: 누가 말하는지, 어떤 쇼/인터뷰에서 가져왔는지, 어떤 주제가 논의되는지, 핵심 주장 또는 핵심 내용은 무엇인지
둘 다 studio/<slug>/exports/<클립-폴더>/metadata.txt에 작성하십시오:
标题:AI终将取代一切?
描述:Sam Altman 在 Lex Fridman 播客中谈到 AGI 的时间表——他认为大多数人严重低估了 AI 的发展速度,未来三年将改变一切。
6e. 동영상에 중국어 자막 + 제목 새기기
python3 -m corekit.render_hardsubs \
"studio/<slug>/exports/<클립-폴더>/clip.mp4" \
"studio/<slug>/exports/<클립-폴더>/clip.zh.srt" \
"studio/<slug>/exports/<클립-폴더>/clip.hardsub.mp4" \
--title "<6d에서-가져온-제목>"
중요: 중국어 clip.zh.srt 파일을 전달하십시오. clip.src.srt가 아닙니다. 이것은 가장 흔한 에이전트 실수입니다 — 번역 대신 소스 언어 자막을 전달하는 것입니다.
새기기 단계는 다음을 수행합니다:
- libass 자동 감지; 사용 불가능하면 drawtext 렌더링으로 대체 (당신의 조치 불필요)
- 현재 시스템에 가장 적합한 H.264 인코더 자동 선택
- 처음 1초 동안 동영상 중앙에 48포인트 글꼴 크기와 3px 검정 외곽선으로 제목 렌더링
- 나머지 클립 동안 프레임 하단에 자막 큐 렌더링
**출력 clip.hardsub.mp4**가 존재하고 clip.mp4보다 파일 크기가 더 큰지 확인하십시오 (필터 체인이 시각적 데이터를 추가합니다).
6f. 패키징 카피에 추가
각 클립이 내보내진 후 해당 제목과 설명을 결합된 패키징 파일에 추가하십시오:
studio/<slug>/intel/packaging-copy.md
형식:
## clip-01: AI终将取代一切?
**标题**: AI终将取代一切?
**描述**: Sam Altman 在 Lex Fridman 播客中谈到 AGI 的时间表...
**文件**: studio/<slug>/exports/01-ai-will-replace/clip.hardsub.mp4
**时长**: 1分 19秒
---
7. 최종 출력
모든 클립이 내보내진 후 사용자에게 다음을 반환하십시오:
- 소스 자산 폴더:
studio/<slug>/intake/ - 후보 목록: 5단계의 전체 표 (타임스탬프, 길이, 제목, 요약)
- 패키징 파일:
studio/<slug>/intel/packaging-copy.md - 내보낸 클립: 각
clip.hardsub.mp4경로 나열
작업 공간 레이아웃 참조
studio/<video-slug>/
├── intake/ # YouTube 원본 자산
│ ├── <title> [<id>].mp4 # 소스 동영상 (yt-dlp의 파일명)
│ └── <title> [<id>].<lang>.srt # 소스 자막
├── intel/ # 분석 결과물
│ ├── transcript.json # 구조화된 자막 큐 (3단계)
│ ├── selected_clips.json # 클립 결정 (4단계)
│ ├── candidate-board.md # 리뷰 테이블 (4단계)
│ └── packaging-copy.md # 모든 제목 + 설명 (6f단계)
└── exports/ # 내보낸 클립당 하나의 폴더
└── 01-<slug>/
├── clip.mp4 # 원본 컷 (자막 없음)
├── clip.src.srt # 윈도우 처리된 소스 언어 자막
├── clip.zh.srt # 번역된 중국어 자막
├── clip.hardsub.mp4 # 최종 결과물 (새겨진 자막 + 제목)
└── metadata.txt # 이 클립의 제목 + 설명
모듈 참조
| 모듈 | 호출 | 인수 |
|---|---|---|
corekit.fetch_source | python3 -m corekit.fetch_source <url> <출력_디렉토리> | YouTube URL, 출력 디렉토리 |
corekit.subtitle_to_json | python3 -m corekit.subtitle_to_json <입력.srt> <출력.json> | SRT 파일 경로, JSON 출력 경로 |
corekit.cut_video | python3 -m corekit.cut_video <입력.mp4> <시작_초> <끝_초> <출력.mp4> | 소스 동영상, 시작 초(실수형), 끝 초(실수형), 출력 경로 |
corekit.window_subtitles | python3 -m corekit.window_subtitles <입력.srt> <시작_초> <끝_초> <출력.srt> | 소스 SRT, 시작 초(실수형), 끝 초(실수형), 출력 경로 |
corekit.render_hardsubs | python3 -m corekit.render_hardsubs <입력.mp4> <입력.srt> <출력.mp4> --title "..." | 클립 동영상, 중국어 SRT, 출력 경로, 선택적 제목 텍스트 |
render_hardsubs의 선택적 플래그:
--title "...": 오버레이할 제목 텍스트--font-size N: 제목 글꼴 크기 (기본값 48)--outline-width N: 외곽선 너비 픽셀 (기본값 3)
문제 해결
| 증상 | 가능한 원인 | 해결 방법 |
|---|---|---|
fetch_source가 403 오류 반환 | 만료된 YouTube 쿠키 | 사용자에게 브라우저에서 YouTube에 다시 로그인하고 쿠키 파일을 새로고침하도록 요청 |
| 자막 파일이 있지만 parse 후 거의 비어 있음 | 잘못된 언어 자막이 다운로드됨 | intake 폴더를 확인하고 다른 언어 변형을 시도 (.zh.srt 대 .en.srt 등) |
cut_video 출력 크기가 0임 | 시작/끝 시간이 잘못되었거나 동영상이 손상됨 | ffprobe로 동영상 길이를 확인하고 시작/끝 시간이 범위 내에 있는지 확인 |
render_hardsubs가 "Encoder not found" 오류 반환 | ffmpeg가 H.264를 지원하지 않음 | --codec libx264 플래그를 추가하거나 다른 코덱(예: libx265)을 사용 |
render_hardsubs가 소스 언어 자막을 새김 | 잘못된 SRT 파일이 전달됨 (clip.src.srt 대 clip.zh.srt) | 올바른 중국어 SRT 파일(clip.zh.srt)이 전달되었는지 확인하고 다시 실행 |
playbooks
이러한 playbooks는 클립 선택 및 분석을 위한 스키마 및 방법을 정의합니다.