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 + hotwords | 44% | 실시간의 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.md | assets/default-template.md 또는 --template <file> 사용 |
| 2.2 독립형 HTML | knowledge.html | 클릭 가능한 [mm:ss] 타임라인 |
| 2.2b Office/인쇄 내보내기 | knowledge.docx / knowledge.pdf | --format docx / --format pdf (--format all에서 python-docx/fpdf2 설치 시 자동) |
| 2.3 지식 카드 | cards.csv | question,answer,tags,timestamp,source — 중복 제거됨: 긴 강의는 청크에 대해 map/reduce로 요약되고 모델이 각 청크에서 동일한 질문을 다시 묻기 때문에 모든 반복이 제거됨 (측정: 1608개 카드 중 145개, 최악의 경우 117행 → 11행) |
| 2.4 그림 학습 노트 (图文笔记) | notes.md + notes.html | 주요 프레임 × 나레이션, 아래 참조 |
| 2.4b 노트 Office/인쇄 | notes.docx / notes.pdf | build_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 | 회상 검사 골든 기준 |