mairp/video-to-deck

video-to-deck은(는) 무엇을 하나요?

동영상으로 프레젠테이션을 만듭니다. 당신(모델)은 텍스트 전용입니다 — 오디오를 듣거나 프레임을 볼 수 없습니다. 따라서 이 스킬의 스크립트가 보고 듣는 작업을 수행하고 텍스트 증거 번들(evidence.md)을 제공합니다. 당신의 역할은 종합만입니다: 증거를 읽고 좋은 덱을 작성하세요. 증거가 뒷받침하지 않는 것을 지어내지 마세요.

출력은 Marp 마크다운(deck.md)입니다: 지금 읽을 수 있는 일반 .md이며, 나중에 render.sh 명령 하나로 실제 슬라이드 덱(PPTX/PDF/HTML)이 됩니다.

$SKILL 아래 = 이 스킬의 디렉토리(이 파일을 포함하는 폴더).

절차

1. 일회성 설정 (멱등적)

bash "$SKILL/scripts/setup.sh"

faster-whisper(전사), tesseract(OCR)를 설치하고 — npm이 있으면 — marp-cli와 mermaid-cli를 설치합니다. 다시 실행해도 안전합니다. ffmpeg는 미리 설치되어 있어야 합니다.

2. 동영상 찾기

bash "$SKILL/scripts/find_videos.sh" "<폴더>"      # 한 줄에 하나의 경로, 재귀적

단일 파일의 경우 이 단계를 건너뛰고 경로를 직접 사용하세요.

3. 각 동영상에 대한 증거 번들 구축 (한 번에 하나씩)

bash "$SKILL/scripts/process_video.sh" "<동영상>" "<출력_디렉토리>/<동영상-줄기이름>"

이 단계는 오디오 추출 → 전사, 키프레임 샘플링 → 화면 텍스트 OCR을 수행하고 <출력_디렉토리>/<동영상-줄기이름>/evidence.md(및 transcript.txt, segments.tsv, frames/, ocr.txt)를 작성합니다. CPU에서 긴 동영상은 느립니다. 품질을 위해 WHISPER_MODEL=small을 설정하거나, 속도를 위해 CUDA GPU를 사용하세요 (자동 감지됨; scripts/transcribe.py의 WHISPER_DEVICE 참조). 동영상을 병렬로 처리하지 말고 순차적으로 처리하세요.

선택적 비전 패스 (Qwen-VL). OCR은 텍스트만 읽습니다. 텍스트로 포착할 수 없는 것 — 차트와 그 추세, 다이어그램, UI 레이아웃, 발표자의 제스처 — 도 캡처하려면, 각 유지된 키프레임에 캡션을 추가하는 비전 모델을 활성화하세요. 기본적으로 비활성화되어 있습니다. 같은 명령의 환경에서 VISION_MODEL(및 필요한 경우 VISION_ENDPOINT)을 설정하여 켜십시오:

VISION_MODEL=qwen2.5-vl \
VISION_ENDPOINT=http://127.0.0.1:8081/v1/chat/completions \
  bash "$SKILL/scripts/process_video.sh" "<동영상>" "<출력_디렉토리>/<동영상-줄기이름>"

활성화되면 evidence.md에 OCR과 함께 "## 시각적 설명" 섹션이 추가됩니다 — 이를 차트/다이어그램 슬라이드에 사용하세요. OpenAI 호환 비전 엔드포인트라면 모두 작동합니다(llama.cpp/llama-swap 또는 Ollama와 같은 로컬 서버, 또는 호스팅 API; 토큰이 필요한 경우 VISION_API_KEY). 엔드포인트에 연결할 수 없으면 OCR만으로 계속 실행됩니다 — 아무것도 중단되지 않습니다.

4. 덱 작성

evidence.md 전체를 읽으세요. "$SKILL/templates/deck.marp.md"를 <출력_디렉토리>/<동영상-줄기이름>/deck.md로 복사하고 내용을 채우세요. 규칙:

• marp: true 프론트매터를 유지하세요 — 이것이 슬라이드 덱을 만드는 요소입니다.
• 전사를 사용하여 말한 내용을 캡처하고; OCR / 화면 텍스트를 사용하여 슬라이드에 표시된 정확한 레이블, 숫자, 제목 및 코드를 가져오고; "시각적 설명" 섹션이 있는 경우(비전 패스가 활성화된 경우) OCR이 전달할 수 없는 차트/다이어그램/UI에 사용하세요.
• 유용할 때 주장을 해당 시점에 태그하세요: [00:04:12].
• 슬라이드의 키프레임을 슬라이드에 넣으세요 — 이것은 선택적 장식이 아니라 기본값입니다. ocr.txt의 모든 ### [시간범위] frames/kf_####.jpg 블록은 해당 슬라이드의 대표 프레임을 지정합니다. 이것을 해당 덱 슬라이드에 가져오세요: ![](frames/kf_0007.jpg). 키프레임은 슬라이드의 증거이며, 다이어그램/차트/UI를 보여주므로 글머리 기호로만 설명할 수 없는 것을 보여주고 덱이 원본 프레젠테이션을 반영하도록 합니다. 슬라이드가 Mermaid로 다시 그린 순수 다이어그램 슬라이드이거나 프레임에 시각적 신호가 없는 경우(말하는 머리, 빈 전환)에만 생략하세요. 하나의 소스 슬라이드에서 두 개의 덱 슬라이드가 나오는 경우, 하나의 프레임을 반복하지 말고 해당 슬라이드의 실행에서 두 개의 다른 프레임을 사용하세요.
• 증거가 뒷받침하는 것만 포함하세요. 전사 및 OCR이 모두 비어 있으면, 덱을 지어내지 말고 동영상에 추출 가능한 콘텐츠가 없다고 말하세요.

밀도 — 덱은 증거를 요약해서 없애는 것이 아니라 통합해야 합니다. 가장 흔한 실수는 얇은 덱입니다: 동영상에 실제로 포함된 대부분의 내용을 버리는 4단어 글머리 기호 20개 슬라이드. 증거 번들을 구축하는 데는 비용이 많이 들고, 덱은 사람들이 읽는 것입니다.

• 소스 슬라이드당 덱 슬라이드 하나. OCR 섹션의 각 ### [시간범위] frames/… 블록은 동영상의 실제 슬라이드 하나입니다 — 그 목록이 체크리스트이자 대략적인 슬라이드 수입니다. 세 개의 소스 슬라이드를 하나의 글머리 기호로 병합하지 마세요. 40분 강연은 일반적으로 30-45개의 슬라이드입니다.
• 구체적인 내용을 슬라이드에 담으세요. 증거에 있는 모든 숫자, 지표, 임계값, 백분율, 제품 이름, CRD, 구성 키 및 레이블은 슬라이드 자체에 속합니다. 소스 슬라이드에 6개의 글머리 기호와 4개의 통계가 있었다면, 당신의 슬라이드에는 6개의 글머리 기호와 4개의 통계가 있어야 합니다 — "향상된 정확도"가 아닙니다.
• 글머리 기호는 한 줄(~15-20단어)이어야 하며, 네 단어가 아닙니다. 슬라이드당 5-8개가 일반적입니다. 간결함은 소스가 간결할 때만 옳습니다.
• 소스가 표 형식일 때마다 표를 사용하세요 — 라우팅 행렬, 벤치마크 그리드, 수준 정의, 우선순위 규칙. 샘플이 아닌 모든 행과 열을 재현하세요.
• 발표자 노트는 추가적이며, 슬라이드에 없는 말한 내용을 위한 것입니다: 주의사항, 실전 경험, "이유", Q&A 세부 사항. 슬라이드에 속하는 내용을 숨기는 장소가 아닙니다.
• 완료 전에 적용 범위를 확인하세요. ocr.txt의 ### [..] 블록을 순서대로 살펴보고 각각이 표현되었는지 확인하세요. 블록을 건너뛴 경우, 이전 슬라이드의 복제/애니메이션이거나 데모 프레임이어야 합니다 — 어느 것인지 말할 수 있어야 합니다.

5. 다이어그램 패스 ("이것이 다이어그램이 될 수 있나?" 확인)

각 주제에 대해 물어보세요: 이것이 구조적(구성 요소 + 연결, 액터 상호 작용, 프로세스/흐름, 상태 + 전이, 엔티티 + 관계)인가요? 그렇다면 글머리 기호 대신 자체 슬라이드에 Mermaid(기본) 또는 PlantUML 다이어그램으로 그리세요. 콘텐츠→유형 결정 표와 복사-붙여넣기 스켈레톤은 "$SKILL/references/diagrams-cheatsheet.md"를 참조하세요. 내용이 단순한 서사인 곳에 다이어그램을 강요하지 마세요.

6. (선택 사항) 실제 슬라이드 덱 내보내기

bash "$SKILL/scripts/render.sh" "<출력_디렉토리>/<동영상-줄기이름>/deck.md" pptx   # 또는 pdf | html | all

이 명령은 다이어그램 블록을 이미지로 사전 렌더링한 다음 PPTX/PDF를 생성합니다. marp/mermaid가 설치되어 있지 않으면 덱은 단순히 .md로 남습니다(여전히 유효하고 볼 수 있음).

한 번에 전체 트리를 처리하려면 덱별로 render.sh를 호출하는 대신 일괄 드라이버(아래)에 --pdf를 추가하세요.

배치 / 중첩 폴더

전체 폴더 — 특히 중첩된 강좌 트리 — 의 경우 scripts/drive_decks.sh <루트>를 선호하세요: 이 명령은 bash에서 루프를 돌며 동영상마다 새로운 에이전트를 생성(모델의 컨텍스트를 넘치지 않도록 함)하고 출력에 소스 하위 폴더를 미러링하여 부모→자식 계층 구조가 유지되도록 합니다. scripts/rename_by_topic.sh <덱들>은 각 리프를 강좌 폴더 내의 주제로 슬러그화합니다. 작성이 완료되면 **--pdf**를 추가하여 모든 덱을 PDF로 내보냅니다 — Mermaid는 이미지로 사전 렌더링되고 리프 폴더가 축소되어 각 PDF가 상위 폴더(<출력>/CourseA/lesson/deck.md → <출력>/CourseA/lesson.pdf)에 배치되므로 PDF당 하위 폴더가 생기지 않습니다. 이전 실행에서 평면적으로 생성된 덱의 계층 구조를 재구축하려면 scripts/regroup_by_source.sh <덱들>을 사용하세요 — 각 evidence.md의 Source: 줄을 읽어 모든 덱을 강좌 상위 폴더 아래에 배치하고(중복은 _duplicates/에 격리), 그런 다음 이름 변경을 실행합니다. 전체 배치 가이드는 README.md를 참조하세요.

참조

• references/marp-cheatsheet.md — Marp 슬라이드 구문(구분자, 이미지, 노트, 열).
• references/diagrams-cheatsheet.md — 다이어그램을 그려야 할 때와 각 유형의 구문.

참고 사항

• OCR은 화면 캡처/슬라이드 동영상의 화면 텍스트를 잘 캡처합니다. 실사 영상의 경우 전사가 대부분의 신호를 전달합니다 — 이에 의존하고 시각적 요소에 대해 과장하지 마세요.
• 전사, OCR 및 렌더링은 항상 로컬에서 수행됩니다. 작성 단계가 머신을 떠나는지 여부는 전적으로 --agent-cmd가 가리키는 에이전트에 달려 있습니다.
• 설계는 모델에 구애받지 않습니다: bash를 실행하고 파일을 읽을 수 있는 모든 텍스트 에이전트가 이 스킬을 사용할 수 있습니다.