剪口播 v3
Volcengine 전사 + AI 말실수 인식 + 웹 검토 + 자른 후 재전사 + AI 자막 보정
빠른 사용법
사용자: 이 口播 영상 잘라줘
사용자: 이 영상 처리해줘
사용자: 이 녹화 영상을 기초 소재 패키지로 만들어줘
자막 생성 기능을 별도의 Skill로 분리하지 마세요. 剪口播는 口播 기초 소재 패키지를 위한 유일한 진입점입니다.
사용자가 口播 녹화 영상을 제공하면, 이 Skill은 기본적으로 이후 口播成片에서 바로 사용할 수 있는 기초 소재 패키지를 생성합니다:
source_cut.mp4 # 자른 口播 비디오
subtitles.srt # 자른 비디오 기반 재전사 후 AI 보정 자막
assets/ # 선택적: 스크린샷, 댓글 이미지, 결과 페이지 등
검토 페이지는 사용자가 "어디를 삭제할지" 확인하고 새 비디오를 자르는 역할만 합니다. 자막은 원본 비디오 자막을 그대로 사용하거나 Volcengine 전사 초안을 최종 자막으로 사용해서는 안 됩니다. Agent는 반드시 자른 비디오를 기반으로 재전사하고 AI 보정을 거친 후에야 subtitles.srt에 기록해야 합니다.
출력 디렉토리 구조
output/
└── YYYY-MM-DD_비디오명/
├── 剪口播/
│ ├── 1_转录/
│ │ ├── audio.mp3
│ │ ├── volcengine_result.json
│ │ └── subtitles_words.json
│ ├── 2_分析/
│ │ ├── readable.txt
│ │ ├── auto_selected.json
│ │ └── 口误分析.md
│ └── 3_审核/
│ ├── review.html
│ └── video.mp4 → 원본 비디오(심볼릭 링크)
└── 字幕/
├── 1_转录/
│ ├── audio.mp3
│ └── volcengine_result.json
├── subtitles_with_time.json
└── 3_输出/
├── video.raw.srt
└── video.srt
규칙: 이미 존재하는 폴더는 재사용하고, 없으면 새로 생성합니다.
프로세스
0. 출력 디렉토리 생성
↓
1. 오디오 추출 (ffmpeg)
↓
2. Volcengine 음성 파일 인식 2.0 호출 (Seed ASR v3)
↓
3. volcengine_result.json 생성
↓
4. 단어 수준 자막 생성 (subtitles_words.json)
↓
5. AI 말실수/무음 분석, 사전 선택 목록 생성 (auto_selected.json)
↓
6. 검토 웹페이지 생성 (review.html)
↓
7. 검토 서버 시작, 사용자 웹페이지 확인
↓
【사용자 확인 대기】→ 웹페이지에서 '클립 실행' 클릭
↓
8. 서버가 새 비디오만 자름
↓
9. Agent가 자른 비디오 생성을 감시
↓
10. 자른 비디오 기반 오디오 재추출, Volcengine 전사, video.raw.srt 생성
↓
11. Agent가 원고/본문 대조하며 AI 보정, video.srt 기록
↓
12. 기초 소재 패키지 정리: source_cut.mp4 + subtitles.srt + 선택적 assets/
자른 후 자막 하드 규칙:
- 반드시 자른 비디오를 기반으로 재전사해야 함. 원본 비디오 자막을 역추론해서 사용할 수 없음.
- Volcengine 전사는 초안일 뿐이며,
video.raw.srt로 출력. video.srt/subtitles.srt는 오직 Agent AI 보정을 거친 최종 자막만 허용.- 보정 시 사용자가 제공한 口播 원고, 본문, 고유 명사 및 문맥을 대조하여 전문 용어, 동음이의어 오인식, 문장 분할을 수정함. 비디오에 없는 내용을 추가해서는 안 됨.
실행 단계
단계 0: 출력 디렉토리 생성
# 변수 설정 (실제 비디오 경로에 맞게 조정)
VIDEO_PATH="/path/to/비디오.mp4"
VIDEO_NAME=$(basename "$VIDEO_PATH" .mp4)
DATE=$(date +%Y-%m-%d)
BASE_DIR="output/${DATE}_${VIDEO_NAME}/剪口播"
# 하위 디렉토리 생성
mkdir -p "$BASE_DIR/1_转录" "$BASE_DIR/2_分析" "$BASE_DIR/3_审核"
cd "$BASE_DIR"
단계 1-3: 전사
cd 1_转录
# 1. 오디오 추출 (파일명에 콜론이 있으면 file: 접두어 필요)
ffmpeg -i "file:$VIDEO_PATH" -vn -acodec libmp3lame -y audio.mp3
# 2. Volcengine 음성 파일 인식 2.0 호출 (기본 resource_id=volc.seedasr.auc)
SKILL_DIR="/Volumes/成峰/代码/剪辑Agent/.claude/skills/剪口播"
"$SKILL_DIR/scripts/volcengine_transcribe.sh" audio.mp3
# 출력: volcengine_result.json
전사 스크립트는 기본적으로 Volcengine v3 Seed ASR 2.0을 사용합니다:
POST /api/v3/auc/bigmodel/submit
POST /api/v3/auc/bigmodel/query
X-Api-Resource-Id: volc.seedasr.auc
임시로 다른 리소스로 되돌리거나 비교하려면 환경 변수로 재정의할 수 있습니다:
VOLCENGINE_ASR_RESOURCE_ID=volc.bigasr.auc "$SKILL_DIR/scripts/volcengine_transcribe.sh" audio.mp3
단계 4: 단어 수준 타임라인 생성
node "$SKILL_DIR/scripts/generate_subtitles.js" volcengine_result.json
# 출력: subtitles_words.json
cd ..
타임스탬프 규칙:
generate_subtitles.js는result.utterances(v3)와 구버전utterances를 모두 호환해야 함.- v3 결과의 유효하지 않은 타임스탬프 토큰(주로 공백,
start_time/end_time = -1)은 반드시 필터링해야 함. 그렇지 않으면 가짜 무음이 생성됨. - 2026-06-25의 180초 샘플 평가: Seed ASR 2.0은 보정 자막 타임 윈도우 기준 단어 수준 경계 오프셋 중앙값 약 80ms, P90 약 240ms, 최대 약 620ms. 기본 剪口播 타임라인으로 사용 가능하지만, 긴 문장은 여전히 단어 수준 타임스탬프에 따라 자막 줄로 다시 잘라야 함.
단계 5: 말실수 분석 (스크립트 + AI)
5.1 읽기 쉬운 형식 생성
cd 2_分析
node -e "
const data = require('../1_转录/subtitles_words.json');
let output = [];
data.forEach((w, i) => {
if (w.isGap) {
const dur = (w.end - w.start).toFixed(2);
if (dur >= 0.2) output.push(i + '|[静' + dur + 's]|' + w.start.toFixed(2) + '-' + w.end.toFixed(2));
} else {
output.push(i + '|' + w.text + '|' + w.start.toFixed(2) + '-' + w.end.toFixed(2));
}
});
require('fs').writeFileSync('readable.txt', output.join('\\n'));
"
5.2 사용자 습관 읽기
먼저 用户习惯/ 디렉토리의 모든 규칙 파일을 읽습니다.
5.3 문장 목록 생성 (핵심 단계)
먼저 문장을 분리한 후 분석합니다. 무음을 기준으로 문장 목록으로 분할:
node -e "
const data = require('../1_转录/subtitles_words.json');
let sentences = [];
let curr = { text: '', startIdx: -1, endIdx: -1 };
data.forEach((w, i) => {
const isLongGap = w.isGap && (w.end - w.start) >= 0.5;
if (isLongGap) {
if (curr.text.length > 0) sentences.push({...curr});
curr = { text: '', startIdx: -1, endIdx: -1 };
} else if (!w.isGap) {
if (curr.startIdx === -1) curr.startIdx = i;
curr.text += w.text;
curr.endIdx = i;
}
});
if (curr.text.length > 0) sentences.push(curr);
sentences.forEach((s, i) => {
console.log(i + '|' + s.startIdx + '-' + s.endIdx + '|' + s.text);
});
" > sentences.txt
5.4 스크립트 자동 무음 표시 (먼저 실행 필수)
node -e "
const words = require('../1_转录/subtitles_words.json');
const selected = [];
words.forEach((w, i) => {
if (w.isGap && (w.end - w.start) >= 0.2) selected.push(i);
});
require('fs').writeFileSync('auto_selected.json', JSON.stringify(selected, null, 2));
console.log('≥0.2초 무음 개수:', selected.length);
"
→ auto_selected.json 출력 (무음 idx만 포함)
5.4b 앞뒤 자르기 (전사 사각지대, 필수)
🚨 Volcengine은 음성만 전사합니다. 끝 부분의 전사되지 않은 잡음/마무리 동작은 자막에 없으므로 모든 감지기가 볼 수 없습니다. 비디오 길이를 비교하여 보완해야 합니다.
用户习惯/3-静音段处理.md참조.
VDUR=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "file:$VIDEO_PATH")
node -e "
const fs=require('fs');
const w=require('../1_转录/subtitles_words.json');
const auto=require('./auto_selected.json');
const VDUR=$VDUR, last=w[w.length-1];
if(VDUR - last.end > 0.3){ // 끝부분 미포함 → 꼬리 요소 추가 및 사전 선택
w.push({text:'',start:last.end,end:VDUR,isGap:true,reason:'끝부분 미전사(잡음/마무리)'});
auto.push(w.length-1);
fs.writeFileSync('../1_转录/subtitles_words.json',JSON.stringify(w));
fs.writeFileSync('./auto_selected.json',JSON.stringify([...new Set(auto)].sort((a,b)=>a-b),null,1));
console.log('꼬리 요소 추가 idx',w.length-1,'['+last.end+'→'+VDUR+']');
} else console.log('꼬리 부분 이미 포함됨');
if(w[0].start>0.3) console.log('⚠️ 시작 부분',w[0].start,'초 미포함, 머리 요소 추가 고려');
"
5.5 AI 말실수 분석 (auto_selected.json에 추가)
🚨 핵심 원칙: 앞쪽은 삭제하고 뒤쪽은 보존합니다. 모든 반복/말실수는 앞쪽을 삭제하고 뒤쪽을 보존합니다.
감지 유형별로 분담하여 여러 Agent를 병렬 실행:
각 Agent는 하나의 감지 유형만 담당하므로, 프롬프트가 더 짧고 정확하며 규칙 간 간섭을 피할 수 있습니다.
| Agent | 입력 | 감지 내용 | 삭제 범위 |
|---|---|---|---|
| A-문장 간 반복 | sentences.txt | 인접/한 문장 건너뛰고 시작 부분 5자 이상 동일 | 앞 문장 전체 삭제 |
| B-문장 내 반복 | sentences.txt | 동일 문장 내 A+중간+A 패턴 | 앞쪽 조각만 삭제, 전체 문장 삭제 안함 |
| C-불완전 문장 | sentences.txt | 말하다 중단 + 무음 + 다시 말하기 | 불완전 문장 전체 삭제 |
스크립트로 직접 처리 가능 (AI 불필요):
- 더듬는 단어 (那个那个, 就是就是) → 정규식 매칭
- 감탄사 (嗯, 啊, 呃) → 사용자 확인 대기로 표시
검증(verify) — 위험도에 따라 투입, 전체에 적용하지 않음 (用户习惯/10-删除风险分层.md 참조):
- 저위험 면제: 무음, 글자 단위 부분 반복 (보존 내용의 글자 단위 시작 부분 삭제, 예: 「我把同一句」삭제하고「我把同一句话」보존), ≤3자 단순 막힘/감탄사 → 바로 auto_selected에 추가, 웹페이지에서 사용자 최종 확인.
- 고위험 필수 검증: 전체 문장 삭제, "시작과 끝이 다른" 패턴 (예: 「超出了预算」vs 「超出了路线规划能力」), 긴 구간 반복 → 대항 리뷰어(adversarial reviewer) 투입하여 고유 내용이 삭제되지 않았는지 확인.
- 교훈: 전체 후보에 2배 검증을 적용했을 때, 약 4/91만 적중했고 모두 고위험 유형에 속함 (
log/참조). verify는 비용이 많이 들므로, 잘못 삭제될 위험이 있는 곳에만 집중하는 것이 좋습니다.
Agent 프롬프트 템플릿:
각 Agent 프롬프트에 포함할 내용:
1. 해당 Agent가 담당하는 하나의 감지 규칙만 포함 (사용자 습관에서 읽어옴)
2. 전체 sentences.txt 내용
3. 명확한 요구사항: 삭제할 idx 범위 목록 반환
4. 🚨 "앞쪽 삭제, 뒤쪽 보존" 강조: 앞쪽 버전을 삭제하고, 더 완전한 뒤쪽 버전을 보존
Agent 반환 형식:
| 문장 번호 | idx 범위 | 유형 | 내용 요약 | 처리 |
|------|---------|------|----------|------|
삭제 idx 목록: [삭제할 모든 idx]
결과 병합:
모든 Agent가 반환한 idx 목록 수집 → auto_selected.json에 병합 → 중복 제거 및 정렬
범위 전체 삭제 규칙: 말실수를 표시할 때, startIdx부터 endIdx 사이의 모든 요소(중간 gap 포함)를 auto_selected에 추가합니다. gap을 건너뛰고 텍스트 idx를 하나씩 선택하지 마십시오.
🚨 중요 경고: 줄 번호 ≠ idx
readable.txt 형식: idx|내용|시간
↑ 이 값을 사용
줄 번호 1500 → "1568|[静1.02s]|..." ← idx는 1568이지, 1500이 아닙니다!
말실수 분석.md 형식:
## 문장 간 반복 (Agent A)
| 문장 번호 | idx 범위 | 내용 요약 | 처리 |
|------|---------|----------|------|
| 5 | 212-233 | 문장 6과 중복, 문장 6이 더 완전 | 앞 문장 삭제 |
## 문장 내 반복 (Agent B)
| 문장 번호 | idx 범위 | 내용 요약 | 처리 |
|------|---------|----------|------|
| 16 | 492-510 | "很多人一提到CLI命令" 앞부분 중복 | 조각 삭제 |
## 불완전 문장 (Agent C)
| 문장 번호 | idx 범위 | 내용 요약 | 처리 |
|------|---------|----------|------|
| 7 | 266-275 | "为了解释为了回答这个" 미완성 | 전체 문장 삭제 |
5.6 口播 원고 정렬로 누락 보완 (口播 원고가 있을 때)
사용자가 口播 원고/원문을 제공한 경우(口播를 원고를 보고 읽은 경우), 이를 사용하여 문장 수준 정렬로 누락을 보완합니다. — 用户习惯/11-口播稿对齐.md 참조.
口播 원고 = 의미 ground truth (표현은 변경될 수 있음, 예: "两个模型"↔"两个大模型", 글자 단위 diff는 하지 마십시오). 각 전사 문장을 口播 원고 문장에 정렬하여 순수 텍스트 감지로는 놓치는 문장 수준 말실수를 찾아냅니다: 전체 문장 다시 말하기, 불완전 문장, 대응되는 원고 없음 — 특히 기술 용어 막힘 (Mindverse / δ-mem / LoRA 발음 틀려 다시 시작, "Delta Mam", 고립된 단일 글자 "从"). 이러한 전체 문장 삭제는 고위험에 해당 → 검증 절차를 거쳐 보존된 버전이 口播 원고의 원래 의미를 포함하는지 확인합니다.
단계 6-7: 검토
cd ../3_审核
# 6. 검토 웹페이지 생성 (비디오 파일 전달, 자동으로 심볼릭 링크 생성)
node "$SKILL_DIR/scripts/generate_review.js" ../1_转录/subtitles_words.json ../2_分析/auto_selected.json "$VIDEO_PATH"
# 출력: review.html, video.mp4 (심볼릭 링크)
# 7. 검토 서버 시작
node "$SKILL_DIR/scripts/review_server.js" 8899 "$VIDEO_PATH"
# http://localhost:8899 열기
⚠️ 반드시 review_server.js를 사용해야 합니다.
python3 -m http.server로 대체할 수 없습니다. 이유: 비디오 재생은 HTTP Range 요청(206)에 의존합니다. Python 간이 서버는 이를 지원하지 않아 비디오가 재생되지 않거나 소리가 나지 않을 수 있습니다. 일반 사용자는 이 터미널 창을 열어두기만 하면 됩니다. Claude Code / Codex는 Agent가 현재 환경에서 사용 가능한 백그라운드 작업 능력을 이용하여 호스팅합니다. 사용자에게 tmux 설치를 요구하지 마십시오.
사용자가 웹페이지에서 수행하는 작업:
- 비디오 화면 재생하여 확인
- 삭제 항목 선택/해제
- 왼쪽 버튼을 누른 상태로 텍스트 위를 밀어서 일괄 삭제/복구 표시 가능. 여러 줄에 걸쳐 밀기 가능. 드래그를 너무 많이 했을 때 손을 떼지 않고 뒤로 당기면 선택 영역이 실시간으로 좁혀짐
- '클립 실행' 버튼 클릭
단계 8: 자른 비디오 감시
사용자가 검토 페이지 버튼을 클릭하면, review_server.js는 새 비디오만 자르고 검토 디렉토리에 cut_done.json을 기록합니다. Agent는 이 파일을 감시하여 자른 비디오가 실제로 생성되었고 크기가 안정적인지 확인해야 합니다.
# 다른 Agent 작업/터미널에서 사용자 확인 후 클립 결과 대기
node "$SKILL_DIR/scripts/watch_cut_done.js" "output/YYYY-MM-DD_비디오명/剪口播/3_审核"
감시 결과는 자른 비디오 경로를 반환합니다:
{
"output": "output/YYYY-MM-DD_비디오명/剪口播/3_审核/비디오명_cut.mp4",
"newDuration": "123.45",
"outputSize": 12345678
}
반환된 output을 CUT_VIDEO로 기록합니다. 이후 자막은 반드시 이 비디오를 기반으로 재전사해야 합니다.
curl /api/cut 또는 스크립트로 클릭을 시뮬레이션하지 마십시오. 사용자가 명시적으로 승인하지 않는 한 허용되지 않습니다.
단계 9: 자른 비디오 기반 재전사
"$SKILL_DIR/scripts/generate_srt_for_video.sh" "자른_비디오.mp4" "output/YYYY-MM-DD_비디오명/字幕"
자막은 반드시 자른 비디오를 기반으로 재전사해야 합니다. 원본 비디오 자막을 역추론할 수 없습니다.
이 단계에서는 Volcengine 전사 초안만 생성합니다:
output/YYYY-MM-DD_비디오명/字幕/1_转录/volcengine_result.json
output/YYYY-MM-DD_비디오명/字幕/subtitles_with_time.json
output/YYYY-MM-DD_비디오명/字幕/3_输出/video.raw.srt
단계 10: AI 자막 보정
Agent는 반드시 video.raw.srt 또는 subtitles_with_time.json을 읽고, 사용자가 제공한 口播 원고/본문/고유 명사/문맥과 대조하여 AI 보정을 수행해야 합니다.
보정 규칙:
- 원래 타임라인은 유지하고, 우선 자막 텍스트만 수정합니다.
- 기술 용어, 도구 이름, 사람 이름, 영어 단어, 동음이의어 오인식을 수정합니다.
- 명백히 부자연스러운 문장 분할을 조정합니다.
- 비디오에 없는 내용을 추가하지 않습니다.
- 보정 완료 후
字幕/3_输出/video.srt에 기록합니다.
단계 11: 기초 소재 패키지 정리
AI 보정이 완료된 후, 자른 비디오와 최종 자막을 프로젝트 루트 디렉토리로 정리합니다:
OUTPUT_ROOT="output/YYYY-MM-DD_비디오명"
ln -sf "$CUT_VIDEO" "$OUTPUT_ROOT/source_cut.mp4"
ln -sf "$OUTPUT_ROOT/字幕/3_输出/video.srt" "$OUTPUT_ROOT/subtitles.srt"
최종 산출물은 최소한 다음을 포함합니다:
output/YYYY-MM-DD_비디오명/字幕/3_输出/video.srt
output/YYYY-MM-DD_비디오명/source_cut.mp4
output/YYYY-MM-DD_비디오명/subtitles.srt
사용자가 다음 단계로 口播成片을 실행하려는 경우, 산출물을 다음과 같은 개념으로 정리합니다:
source_cut.mp4 = 자른 口播 비디오
subtitles.srt = AI 보정된 자른 자막 SRT
assets/ = 선택적 소재
source_cut.mp4와 subtitles.srt는 심볼릭 링크일 수 있습니다. 사용자에게 보고할 때는 이들이 자른 비디오와 자른 자막을 가리키고 있음을 명확히 알려야 합니다.
검토 하드 규칙
검토 페이지 단계에서 반드시 멈추고 링크를 사용자에게 전달해야 합니다.
사용자가 확인하기 전에, Agent는 다음 세 가지만 수행할 수 있습니다:
review.html생성review_server.js시작- 사용자에게 검토 페이지 URL 알리기
사용자가 명시적으로 "네가 실행 버튼을 클릭해줘" 또는 "바로 잘라"라고 말하지 않는 한, Agent는 다음을 허용하지 않습니다:
/api/cut직접 호출- curl / 스크립트로 클릭 시뮬레이션
- 검토 페이지 건너뛰고 바로 자른 비디오 생성
사용자가 검토 페이지에서 '클립 실행'을 클릭하면, 서버는 자른 비디오만 생성합니다. Agent는 자른 비디오 생성이 완료되었음을 감지한 후에야 자른 후 재전사 및 AI 자막 보정 단계로 들어갈 수 있습니다.
데이터 형식
subtitles_words.json
[
{"text": "大", "start": 0.12, "end": 0.2, "isGap": false},
{"text": "", "start": 6.78, "end": 7.48, "isGap": true}
]
auto_selected.json
[72, 85, 120] // Claude 분석 생성 사전 선택 인덱스
클립 인코딩 (하드 규칙)
⚠️ 원본 비디오의 인코딩 매개변수를 일치시켜 재인코딩하고, 프레임 단위로 정확하게 자릅니다.
cut_video.sh의 작동 방식:
- 원본 비디오의 인코딩 매개변수(codec/profile/pix_fmt/bitrate)를 자동 감지
filter_complextrim+concat을 사용하여 프레임 단위로 정확하게 자름- 동일한 매개변수로 재인코딩:
-profile:v high -b:v {원본 비트레이트} -pix_fmt yuv420p
중요: 재인코딩 화질은 원본 매개변수와 일치하는지에 달려 있으며, CRF 값이 아닙니다.
- ✅
-b:v {원본 비트레이트} -profile:v high -pix_fmt yuv420p→ 육안으로 차이 없음 - ❌
-crf N만 지정하고 profile/pix_fmt를 지정하지 않음 → 차이가 있을 수 있음
설정
Volcengine API Key
사용자에게 Volcengine 음성 인식 API Key가 없는 경우, 먼저 사용자에게 Volcengine 콘솔을 열어 "음성 파일 인식 2.0"을 활성화하고 API Key를 생성하도록 안내합니다:
https://console.volcengine.com/speech/new/setting/activate?projectName=default
현재 기본 모델 리소스:
음성 파일 인식 2.0 / Seed ASR
resource_id = volc.seedasr.auc
Key를 받은 후, Skills 루트 디렉토리의 .env에 기록합니다:
cd /Volumes/成峰/代码/剪辑Agent/.claude/skills
cp .env.example .env
# .env를 편집하여 VOLCENGINE_API_KEY=xxx 입력
npm으로 설치한 경우, Skills 루트 디렉토리는 일반적으로 다음과 같습니다:
~/.claude/skills/chengfeng-videocut-skills
~/.codex/skills/chengfeng-videocut-skills