Communitygithub.com

CacinieP/video2knowledge

비디오를 타임스탬프가 있는 자막과 구조화된 지식 아티팩트로 변환합니다. 두 가지 수집 경로(멀티모달 VLM 및 ASR)와 기본적으로 완전한 로컬 처리를 지원합니다.

video2knowledge란 무엇인가요?

이 스킬은 비디오 파일을 타임스탬프 자막, 지식 문서, HTML 페이지, Anki 플래시카드, 그리고 그림이 포함된 학습 노트(图文笔记)로 변환합니다. 두 가지 수집 경로를 제공합니다: (1) Ollama를 통해 로컬에서 실행되는 최대 4B 파라미터의 멀티모달 VLM이 비디오 프레임을 샘플링하여 타임스탬프가 있는 캡션을 생성합니다; (2) ASR이 오디오를 전사하여 타임스탬프 자막을 생성합니다 — 로컬에서는 faster-whisper를, 중국어 mandarin의 경우 FunASR Paraformer를 사용하며(동음이의어 정확도 44% → 94% 향상), 이후 톤 인식 병음 기반 오류 수정 과정을 거칩니다. 그런 다음 구조화된 지식 문서(사용자 정의 템플릿 지원), 독립형 HTML 페이지, 중복 제거된 지식 카드 CSV, Anki apkg 덱, 그리고 그림 학습 노트(图文笔记)를 생성합니다. 기본적으로 모든 처리는 완전히 로컬에서 이루어지며, 비디오, 오디오, 출력이 호스트를 떠나지 않습니다. 클라우드 ASR/LLM 엔드포인트는 옵트인 방식으로 명시적으로 제3자에게 업로드됨을 표시합니다. 이 스킬은 강의나 녹화 내용을 요약하거나, 학습 카드를 만들거나, 회의록을 작성하거나, 튜토리얼 비디오를 지식 베이스로 전환할 때 유용합니다. 지원 플랫폼은 Claude Code, Cursor, Codex 등 다양한 AI 에이전트에서 사용할 수 있는 명령줄 기반 스킬입니다.

지원 대상~Claude Code✓Codex CLI~Cursor
npx skills add CacinieP/video2knowledge

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

video2knowledge은(는) 무엇을 하나요?

비디오를 다음으로 변환: 타임스탬프 자막 → 지식 문서 → HTML / Anki 카드 / 图文笔记. 두 가지 로컬 수집 경로, 기본적으로 완전 로컬 추론 (클라우드 API 없음). 처리는 완전히 로컬에서 유지 — 비디오, 자막, 출력물은 절대 업로드되지 않습니다. 로컬 runs/ 폴더에 저장되며 (gitignored). 저장소는 코드/설정 변경 사항만 추적합니다.

유일한 예외는 옵트인이며 절대 자동이 아닙니다: --backend openai-api / mimo-asr (ASR) 및 --api-base (지식 문서, 모든 OpenAI 호환 엔드포인트)는 해당 오디오 또는 자막 텍스트를 지정한 제3자에게 전송합니다. 전달하지 않으면 모든 것이 호스트에 유지됩니다. 이를 권장할 때 명시적으로 언급하십시오.

전제 조건 및 첫 번째 설정

호스트에 필요: ollama, ffmpeg, python3 (또는 uv). 한 번 실행:

bash scripts/setup_models.sh

이 명령은 (멱등적으로) 기계의 하드웨어 프로필을 자동 감지하여 (RAM / GPU / Apple Silicon / NVIDIA) scripts/hardware_profile.py를 통해 권장 VLM을 가져오고, .venv/에 가상 환경을 만든 후 faster-whisper + genanki를 설치합니다. 어떤 것을 선택했는지 확인:

python3 scripts/hardware_profile.py

프로필 범위는 tiny (4 GB 시스템 → whisper-tiny + qwen3.5:0.8b)부터 high-gpu (NVIDIA ≥8 GB → whisper-large-v3 + qwen3.5:9b on CUDA)까지입니다. 전체 표와 튜닝은 references/hardware-profiles.md에 있습니다. 환경 변수(VLM_MODEL=, ASR_DEFAULT_MODEL=, ...) 또는 CLI 플래그로 선택을 재정의할 수 있습니다.

Python 단계를 실행하기 전에 가상 환경을 활성화하세요:

source .venv/bin/activate

수집 경로 선택 (1단계)

결정 트리:

  • 음성 트랙이 명확한 경우 (강의, 강연, 인터뷰, 나레이션) → 경로 2 (ASR). 더 빠르고, 텍스트 정확도가 높으며, 세분화된 타임스탬프를 제공합니다. 중국어 mandarin의 경우 FunASR Paraformer 백엔드를 선호하세요 — python3 scripts/hardware_profile.py --recommend로 확인하세요. → references/path2-asr.md
  • 무음 / 슬라이드 전용 / 화면 녹화 또는 화면 텍스트 및 다이어그램이 필요한 경우 → 경로 1 (멀티모달). → references/path1-multimodal.md
  • 음성 트랙이 있는 슬라이드/PPT 비디오 (일반적인 온라인 강의 사례): 핵심 콘텐츠가 화면에 (표, 수식, 예제) 있고 발표자가 나레이션하는 경우 → 경로 3 (이중 경로 융합). ASR로 나레이션을 전사하고 VLM OCR로 슬라이드를 처리한 후 타임스탬프로 융합합니다. → references/path3-fusion.md

경로 1과 2는 동일한 세그먼트 스키마({start,end,text})를 생성하므로 2단계는 경로에 관계없이 작동합니다. 경로 3은 2단계의 --merged에서 사용하는 융합된 merged.json을 생성합니다.

경로 1 — 멀티모달 캡션

python3 scripts/mm_caption.py \
  --video VIDEO --out-dir OUT \
  --model openbmb/minicpm-v4.6:latest --interval 2.0

출력: OUT/captions.srt, OUT/captions.json, OUT/frames/.

슬라이드/PPT 비디오의 경우 중복 제거 샘플링(범용, 임계값 튜닝 불필요)과 표/수식 OCR 프롬프트를 사용하세요:

python3 scripts/mm_caption.py \
  --video VIDEO --out-dir OUT \
  --mode dedup --prompt-ocr

경로 2 — ASR 전사

어떤 엔진을 사용할까요? 먼저 기계에 물어보세요:

python3 scripts/hardware_profile.py --recommend

61.5시간 분량의 중국어 mandarin 강좌를 대상으로 측정, 동일한 30분 강의에서 동일한 39개 핫워드 목록 사용:

동음이의어 용어 정확도속도
faster-whisper small + hotwords44%실시간의 2.5배
Paraformer-zh (FunASR, CPU)94%실시간의 12–16배

핫워드로는 이 문제를 해결할 수 없습니다: 背谱/被谱는 병음 과 성조가 동일하므로 오디오 자체가 모호합니다. 권장 사항은 VRAM이 아닌 RAM에 기반합니다 — Paraformer의 장점은 mandarin 정확도이며 CPU에서 실행됩니다. GPU가 있다면 VLM을 위해 비워두세요: whisper와 VLM을 함께 실행하면 8토큰 요청이 3.8초에서 60초 이상으로 늘어납니다.

기본값 (로컬, faster-whisper):

python3 scripts/asr_caption.py \
  --video VIDEO --out-dir OUT \
  --model small --language zh \
  --hotwords "术语一, 术语二"   # 선택적 전문 용어 편향, initial_prompt 통해

Paraformer (mandarin에 권장; 자체 가상 환경 필요 — funasr의 tokenizers 핀은 기본 환경과 함께 설치할 수 없음):

bash scripts/setup_models.sh --with-funasr     # .venv-funasr를 빌드하고 경로 출력

python3 .venv-funasr/bin/python scripts/asr_funasr.py \
  --video VIDEO --out-dir OUT --language zh --hotwords "背谱,视谱,音阶"

로컬에서 전사할 수 없는 호스트를 위한 클라우드 엔진도 있으며, 옵트인 방식입니다 — 오디오를 제3자에게 업로드합니다. bash scripts/setup_models.sh --with-openai-client는 필요한 openai SDK를 추가합니다; --backend openai-api는 모든 OpenAI 호환 엔드포인트를 허용하고 --backend mimo-asr는 타임스탬프를 반환하지 않는 채팅 형식 게이트웨이용입니다. references/path2-asr.md를 참조하세요.

출력: OUT/subtitles.{srt,vtt,json}.

그런 다음 동음이의어를 수정합니다. ASR은 소리를 듣고 단어를 인식하지 못하므로 도메인 용어가 잘못 표기되어 모든 다운스트림 아티팩트로 오류가 전파됩니다. 측정 결과: 46개 위치에서 20개 클래스의 실제 오류, 100% 정밀도.

python3 scripts/fix_homophones.py --subtitles OUT/subtitles.json

편집 거리가 아닌 성조 인식 병음으로 일치시키고 subtitles.srt / .vtt를 다시 작성합니다. 2단계 전에 실행하세요. --dry-run으로 미리보기, --block 实度로 조각 블랙리스트, --glossary @terms.txt로 자체 용어 추가.

경로 3 — 이중 경로 융합 (ASR × VLM)

경로 2를 실행한 다음 경로 1(OCR)을 실행하고, OCR 용어를 ASR 핫워드에 다시 공급하고, 융합한 후 병합된 파일로 빌드합니다:

# 1a. ASR
python3 scripts/asr_caption.py --video VIDEO --out-dir OUT --language zh
# 1b/1c. 중복 제거 프레임 + VLM OCR
python3 scripts/mm_caption.py --video VIDEO --out-dir OUT --mode dedup --prompt-ocr
# 1d. OCR 용어 -> 핫워드 + 적용 범위 확인 (커버리지가 낮으면
#     --hotwords @OUT/ocr_hotwords.txt 로 ASR 재실행)
python3 scripts/hotwords_from_ocr.py --captions OUT/captions.json \
  --subtitles OUT/subtitles.json --out OUT/ocr_hotwords.txt
# 2. 타임스탬프 + 의미 정렬 확인으로 융합
python3 scripts/merge_visual.py --subtitles OUT/subtitles.json --visual OUT/captions.json --out OUT/merged.json
# 3. 빌드 (--merged 사용한 2단계)
python3 scripts/build_knowledge.py --subtitles OUT/subtitles.json --merged OUT/merged.json --out-dir OUT --format all

융합 루프에는 세 가지 경로 간 구성 요소가 있습니다: (1) hotwords_from_ocr.py는 화면 용어(반복되는 CJK n-gram, 슬라이드 제목, 라틴 약어 — 휴리스틱, LLM 없음)를 추출하고 ASR이 듣지 못한 용어, 즉 잘못 들었을 가능성이 있는 전문 용어를 보고합니다; (2) merge_visual.py는 타임스탬프로 시각 자료를 연결한 다음, 타임스탬프로 연결된 슬라이드와의 단어 중복이 거의 없고 인접 슬라이드가 명확히 더 잘 일치하는 경우(발화자 지연/타임스탬프 드리프트) 나레이션 라인을 인접 슬라이드에 보수적으로 다시 바인딩하며, 불확실한 경우 weak으로 표시하여 추측하지 않습니다 — 단, 정착된 슬라이드(화면에 ≥60초)에서는 구두 설명이 일반적이므로 플래그가 발생하지 않습니다 (--no-semantic은 순수 타임스탬프 일치를 복원합니다); (3) build_knowledge.py --merged는 LLM에 오디오+시각 텍스트를 인터리브하여 제공합니다(청크 경계는 슬라이드 표를 절대 자르지 않으며, 프롬프트 에코 라인은 모든 목록 필드에서 지문 필터링되고, 필드 한도는 비디오 길이에 따라 조정되어 3시간에 3배)하며 스왑/약함 노트에 ⚠️ 마커를 추가하고, map-reduce된 목록 필드를 요약을 컨텍스트로 한 번에 전역적으로 재순위화합니다. 청크 수준 LLM 응답은 build_cache.json에 캐시되므로 중단된 3시간 빌드가 다시 시작되지 않고 재개됩니다. 배치에서는 batch_run.py가 OCR 용어를 course_hotwords.txt에 누적하여 이후 비디오의 전사를 개선하고, --asr-verify는 OCR 용어 적용 범위가 50% 미만으로 떨어진 비디오를 다시 전사합니다. 기본 텍스트 모델은 동일한 하드웨어 프로필을 따릅니다: low/low-mac/mid에서는 openbmb/minicpm5-2b (2.5B 밀집, 1.6 GB), high+에서는 경로 1 VLM 풀 자체(qwen3.5/qwen3.8은 통합 비전+텍스트이므로 두 번 다운로드되지 않음). --model 또는 V2K_TEXT_MODEL=로 모든 실행에 대해 하나를 고정하여 재정의합니다. 품질 측정: scripts/recall_check.py --run-dir <dir> --draft는 사람이 몇 분 안에 정리하는 골든 must-have 목록(용어/양쪽 채널 번호/타임라인 커버리지)을 생성합니다; 그런 다음 --golden은 생성된 아티팩트를 이에 대해 점수를 매깁니다(tests/golden/BASELINE.md의 기준) — "누락된 콘텐츠"가 매개변수 변경에 따라 추적할 수 있는 숫자가 됩니다.

지식 아티팩트로 정제 (2단계)

build_knowledge.py를 각 경로의 .json 출력에 대해 실행합니다:

python3 scripts/build_knowledge.py \
  --subtitles OUT/subtitles.json \
  --out-dir OUT --format all

OUT/에 다음을 생성합니다:

아티팩트파일섹션
2.1 지식 문서 (템플릿 기반)knowledge.mdassets/default-template.md 또는 --template <file> 사용
2.2 독립형 HTMLknowledge.html클릭 가능한 [mm:ss] 타임라인
2.2b Office/인쇄 내보내기knowledge.docx / knowledge.pdf--format docx / --format pdf (--format all에서 python-docx/fpdf2 설치 시 자동)
2.3 지식 카드cards.csvquestion,answer,tags,timestamp,source — 중복 제거됨: 긴 강의는 청크에 대해 map/reduce로 요약되고 모델이 각 청크에서 동일한 질문을 다시 묻기 때문에 모든 반복이 제거됨 (측정: 1608개 카드 중 145개, 최악의 경우 117행 → 11행)
2.4 그림 학습 노트 (图文笔记)notes.md + notes.html주요 프레임 × 나레이션, 아래 참조
2.4b 노트 Office/인쇄notes.docx / notes.pdfbuild_notes.py --docx --pdf (프레임 포함)
2.4c 정제된 노트 (纯享版)notes-distilled.md / .docx / .pdf동일한 노드와 프레임, 인용 나레이션 없음 — 42% 더 작고 무료 (이미 계산된 출력에서 렌더링)

그런 다음 카드를 Anki로 변환 (2.3 최종):

python3 scripts/gen_apkg.py --csv OUT/cards.csv --out OUT/cards.apkg --deck "视频知识卡"

그림 학습 노트 (2.4, 图文笔记)

중복 제거된 KEY FRAMES와 각 타임스탬프 주변의 나레이션을 인터리브하는 스크롤 가능한 노트 — "읽기로 다시 보기" 아티팩트입니다. frames.json(extract_frames.py에서, 보통 경로 1의 dedup 모드를 통해)과 각 경로의 자막이 필요합니다:

python3 scripts/build_notes.py \
  --subtitles OUT/subtitles.json \
  --frames OUT/frames/frames.json \
  --out-dir OUT --describe-frames

노드 밀도는 자동입니다. --max-frames 0(기본값)은 노트 크기를 45초당 약 1노드로 조정하며, 12–60 사이로 고정됩니다: 12분 클립은 16노드, 41분 강의는 55노드, 3시간 강의는 60노드를 얻습니다. 이전 1-per-4min 예산은 37분 강의에 9노드만 제공했고, 이후 1-per-90s도 8개에서 최소값을 유지했습니다 — 306개 비디오 / 61.5시간 라이브러리에서 측정한 평균 클립은 12.1분이므로 최소값이 비디오 길이에 관계없이 대부분의 라이브러리를 8노드로 제한했습니다. 움직여야 할 것은 최대값이 아니라 최소값이었습니다. 명시적인 --max-frames N을 전달하여 고정합니다. 선택은 클러스터 계층화됩니다: 모든 변경 버스트는 안정된 최종 프레임을 유지하므로 애니메이션 버스트가 더 이상 격리된 주요 슬라이드의 자체 노드를 굶주리게 하지 않습니다.

주요 프레임당: LLM 섹션 제목 → 프레임 이미지 → 선택적 VLM 画面 설명 (--describe-frames) → 나레이션 창에서 요약된 1-2문장 노트 → 원문 原声 발췌.

画面 프롬프트는 사람이 아닌 교육 정보를 요청합니다: 음표, 코드 기호, 박자표, 주석 및 화면 텍스트 — 그리고 연주자 설명을 명시적으로 거부합니다 ("女士弹琴", "手势讲解"은 복습 노트에 필요한 것이 아닙니다). 읽을 수 있는 교육 콘텐츠가 없는 프레임은 대신 주제를 명명합니다 ("钢琴演奏画面,无字幕"). 이 한 가지 프롬프트 변경은 공부에 도움이 되는 노트와 비디오를 설명하는 노트의 차이입니다.

하나의 패스로 두 가지 뷰. 모든 실행은 동일한 섹션에서 쌍을 작성합니다 — 추가 모델 호출 없음:

파일내용용도
notes.md프레임 + 노트 + 인용 原声강사의 정확한 표현 교차 확인
notes-distilled.md동일한 노드, 동일한 프레임, 인용 나레이션 없음복습 — 295개 노드에서 측정 시 blockquotes가 문자의 53%를 차지

--docx / --pdf 내보내기는 두 변형을 모두 생성합니다 (notes.docx + notes-distilled.docx, PDF도 동일). notes.html은 프레임을 base64로 단일 공유 가능 파일에 포함합니다 — 전체 뷰만 해당되며, 정제된 HTML 쌍은 없습니다. 모델에 연결할 수 없을 때는 프레임 + 원시 발췌로 저하됩니다.

VLM에 시각 기능이 있는 모델을 명시적으로 제공하세요. --describe-frames를 --vlm-model 없이 사용하면 텍스트 모델로 대체되며, 이 모델은 볼 수 없습니다; 실행 시 경고하고 프레임당 실패하는 대신 설명을 삭제합니다:

python3 scripts/build_notes.py ... --describe-frames \
  --model openbmb/minicpm5-2b --vlm-model openbmb/minicpm-v4.6:latest

스키마, 단일 형식 실행 및 저하된 모드에 대해서는 references/outputs.md를 참조하세요.

사용자 정의 템플릿 (2.1)

기본 템플릿: assets/default-template.md. --template <file>로 재정의:

python3 scripts/build_knowledge.py --subtitles s.json --out-dir o \
  --template ./my-lecture-template.md --format knowledge

템플릿은 {{placeholders}} ({{title}}, {{summary}}, {{bullets}} (音画合并要点速览), {{timeline}}, {{key_points}}, {{qa}}, {{glossary}}, {{source}}, {{duration}}, {{date}}, {{meta}})를 사용하는 일반 Markdown입니다. 포함된 플레이스홀더만 채워집니다; 나머지는 그대로 유지됩니다. 전체 사양 + 3개의 예제 템플릿 (강의 / 회의 / 튜토리얼)은 references/templates.md에 있습니다.

로컬 전용 처리 및 변경 추적

모든 비디오 처리는 기계에 유지됩니다. 비디오, 추출된 프레임, 자막, 지식 문서 및 카드는 gitignored인 로컬 runs/ 폴더에 기록됩니다 — 미디어에 관한 어떤 것도 업로드되거나 커밋되지 않습니다.

GitHub 저장소는 코드 및 설정 변경 사항만 추적합니다 (스크립트, 참조, 템플릿, README). 이는 스킬이 어떻게 발전했는지 명확한 기록을 제공하며, 사용자의 미디어를 노출하지 않습니다. 설명적인 feat:/fix:/docs: 커밋 메시지를 사용하세요.

특정 실행의 로컬 기록을 원하면 해당 실행 폴더에 manifest.json을 작성하세요 (사용된 경로, 모델, 인수, 출력 목록) — 그러나 로컬에 유지하세요:

cat > "$RUN/manifest.json" <<EOF
{"video":"~/Movies/lecture.mp4","path":"path2","asr_model":"small","text_model":"openbmb/minicpm5-2b","date":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","args":{"language":"zh","hotwords":["术语一","术语二"]}}
EOF

참조

문서내용
references/hardware-profiles.md전체 하드웨어 프로필 표 및 환경 변수
references/path1-multimodal.md경로 1 상세: 모드, 프롬프트, 매개변수
references/path2-asr.md경로 2 상세: 엔진, 백엔드, 핫워드, 동음이의어 수정
references/path3-fusion.md경로 3 상세: 융합 루프, 의미 정렬, 배치
references/templates.md템플릿 사양 및 예제
references/outputs.md출력 스키마, 단일 형식 실행, 저하된 모드
tests/golden/BASELINE.md회상 검사 골든 기준

관련 스킬