비디오 스킬
ffmpeg, Deepgram Nova 3 및 S3/터널 공유를 사용하여 비디오를 처리하고 공유합니다.
기본값: 더 가벼운 비디오, 동일한 해상도
항상 소스의 원본 해상도로 더 작은 파일로 재인코딩합니다. 압축된 동일 해상도 복사본은 거의 항상 사용자가 원하는 것입니다. 업로드가 빠르고, 공유가 가벼우며, 시청 경험이 동일합니다. 모든 흐름(무음, 대화형 및 Gemini dev-video 재생 인코딩)에서 이것을 기본값으로 설정하십시오. 사용자가 명시적으로 다른 것을 요청하는 경우에만 변경하십시오. 구체적으로:
- 기본 최적화 =
--resolution keep— libx264 + CRF로 재인코딩하고 크기 조정 필터 없음으로 해상도를 변경하지 않고 파일만 작게 만듭니다. 이것은 권장되는 Q1 선택이며 무음 모드의 기본값입니다. - 소스가 1080p보다 실질적으로 큰 경우(≥1440p / 4K) 또는 사용자가 요청하는 경우에만 다운스케일(예: 1080p)하십시오. 절대로 업스케일하지 마십시오.
- 사용자가 명시적으로 요청하는 경우에만 재인코딩을 건너뛰고(수정되지 않은 원본/스트림 복사 사용) — 예: "원본 유지", "재인코딩 안 함".
- 안전 확인: 인코딩 후 출력 크기를 소스와 비교하십시오. 실질적으로 더 작지 않은 경우(드문 경우 — 이미 낮은 비트레이트 소스), CRF(26–28)를 높이거나 원본으로 대체하십시오. 화면 녹화는 특히 잘 압축됩니다.
preset slow와 함께 CRF 24–26은 화면 텍스트를 선명하게 유지하면서 일반적으로 70~80%를 줄입니다. - 다운로드 버튼: 페이지는 기본적으로 단일 "비디오 다운로드" 버튼(재생 비디오를 가리킴)을 표시합니다. 실제로 수정되지 않은 원본을 해당 정확한 이름으로 출력 폴더에 업로드하는 경우에만 "원본 다운로드" 버튼을 추가하십시오(즉,
render_page.py --original-filename <name>전달). 그렇지 않으면 버튼이 누락된 파일에 연결되어 404 오류가 발생합니다. 기본 압축 유지 흐름은 별도의 원본을 유지하지 않으므로--original-filename을 전달하지 마십시오.
전제 조건
ffmpeg및ffprobe가 설치되어 있어야 합니다.- Python 3를 사용할 수 있어야 합니다.
awsCLI를 사용할 수 있어야 합니다(S3 업로드용).- Deepgram API 키 — 오디오 텍스트 변환/자막용(기본 엔진).
- OpenRouter API 키 — Gemini 분석 엔진(
dev-video/transcript-cheap모드)용. 선택 사항입니다. 해당 모드가 선택된 경우에만 필요합니다.
디렉터리
- 스크립트:
<skill_dir>/scripts/— 모든 Python 스크립트 및 player.html 템플릿 - 자격 증명:
~/.config/video-skill/— 플러그인 업데이트 간에도 유지됨deepgram_token— 한 줄의 Deepgram API 키openrouter_token— 한 줄의 OpenRouter API 키(Gemini 분석 엔진)s3_credentials— key=value 형식(endpoint, bucket, access_key, secret_key)
- 기본 설정:
~/.config/video-skill/preferences.json— 세션 간에 저장된 사용자 선택
자격 증명 설정
필요할 때 자격 증명이 없으면 AskUserQuestion을 통해 사용자에게 문의하십시오:
Deepgram: DEEPGRAM_API_KEY env 변수, 그 다음 ~/.config/video-skill/deepgram_token 파일을 확인하십시오. 둘 다 없으면 사용자에게 문의하고 파일에 저장하십시오.
OpenRouter: OPENROUTER_TOKEN env 변수, 그 다음 ~/.config/video-skill/openrouter_token 파일을 확인하십시오. dev-video / transcript-cheap 분석 모드에만 필요합니다. Gemini 모드가 선택되었고 토큰이 없으면 사용자에게 문의하고 파일에 저장하십시오.
S3: env 변수(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, S3_ENDPOINT, S3_BUCKET), 그 다음 ~/.config/video-skill/s3_credentials를 확인하십시오. 없으면 사용자에게 endpoint, bucket, access_key, secret_key를 문의하고 저장하십시오.
중요: 자격 증명을 CLI 인수로 전달하지 마십시오. 스크립트는 --credential-dir ~/.config/video-skill을 통해 내부적으로 파일에서 읽습니다.
기본 설정
{
"language": "en",
"last_folder": "/Users/example/screencasts",
"share_folder": "/Users/example/screencasts",
"sharing_method": "s3",
"optimization": "compress-keep",
"crf": 23,
"preset": "medium",
"audio": "aac-128k",
"subtitles": "track",
"subtitle_style": "modern",
"subtitle_font": "Helvetica Neue",
"target_language": "ru",
"download_button": true,
"passcode": true,
"mode": "subtitles"
}
optimization: 재생 비디오가 인코딩되는 방식입니다. 기본 compress-keep = 소스 해상도에서 더 가볍게 재인코딩(--resolution keep). 다른 값: web-1080p(1080p로 다운스케일 — ≥1440p/4K 소스용), custom, keep-original(재인코딩 안 함 — 명시적 사용자 요청 시에만). 위의 "기본값: 더 가벼운 비디오, 동일한 해상도" 를 참조하십시오.
mode: 트랜스크립트/분석 엔진을 결정하는 단일 필드입니다. 네 가지 값 중 하나입니다(이전 analysis_mode + developer_analysis 쌍이 이것으로 통합됨):
mode | 엔진 | 자막 | 개발자 분석 | 사용 시기 |
|---|---|---|---|---|
subtitles (기본값) | Deepgram | 정확 | 아니오 | 일반 공유, 자막만 원할 때 |
dev-audio | Deepgram | 정확 | 예(트랜스크립트 텍스트에서) | 도구/버그 피드백, 깔끔한 자막도 원할 때 |
dev-video | Gemini 비디오 | 조잡 | 예 + 스크린샷 | 가장 풍부한 도구/UX 피드백(화면 읽기) |
transcript-cheap | Gemini 오디오 | 조잡 | 아니오 | 저렴한 대략적인 트랜스크립트, 타이밍이 중요하지 않을 때 |
내부적으로: subtitles/dev-audio는 process_and_share.py를 실행하고(후자는 --developer-analysis 포함), dev-video/transcript-cheap는 Gemini 엔진(gemini_analyze.py)을 실행합니다. "개발자 분석" = 페이지 내 분석 블록 더하기 분석 Markdown 아티팩트(해당 섹션 참조). 엔진 지침(연구 2026-06): 정확한 자막에는 Deepgram을 유지하고, 분석에는 Gemini-비디오, 저렴한 대략적인 트랜스크립트에는 Gemini-오디오를 사용하십시오. 정확한 캡션도 중요한 dev-video의 경우, 트랙을 위해 Deepgram 패스를 추가로 실행하십시오.
저장: 모든 대화형 선택 후 preferences.json을 업데이트하십시오. 모든 실행 후 last_folder를 항상 저장하십시오.
로드: 시작 시 읽습니다. 저장된 값을 "(권장)" 기본값으로 사용하십시오. 무음 모드에서는 직접 사용하십시오.
스크립트 참조
모든 스크립트는 <skill_dir>/scripts/에 있습니다. 자격 증명을 위해 --credential-dir을 허용하고 상태 추적을 위해 [PROGRESS] 라인을 출력합니다.
| 스크립트 | 목적 | 주요 인수 |
|---|---|---|
process_and_share.py | 주요 워크플로우: 최적화 + 트랜스크립트 + 렌더링 + 업로드 | <video> --output-dir --share-folder --share s3|tunnel |
share_existing.py | 사전 처리된 폴더 공유 | <folder> --share-folder --share s3|tunnel |
upload_s3.py | 폴더를 S3에 업로드 | <folder> --key <key> --credential-dir |
render_page.py | 템플릿에서 index.html 생성 | --output-dir --template --metadata |
manage_registry.py | 레지스트리 CRUD (추가/제거/목록/조회/마이그레이션) | <subcommand> --share-folder |
partial_update.py | 공유된 폴더 재렌더링 + 재업로드(레지스트리에서 키 확인, passcode 전달) | <output_folder> [--key] |
font_name.py | TTF의 내부 패밀리 이름 출력(ASS Fontname용) | <font.ttf> |
transcribe.py | Deepgram 트랜스크립션 → SRT + VTT | <video> --credential-dir [--language] |
gemini_analyze.py | Gemini 엔진: 오디오 트랜스크립트 또는 비디오 분석 + 스크린샷 | <video> --mode audio|video --output-dir --credential-dir [--key] |
burn_subtitles.py | 비디오에 자막 굽기 | <video> <srt> [--font --fontsize ...] |
share_server.py | 터널 공유를 위한 로컬 HTTP 서버 | <share_root> [--port] |
워크플로우
0단계: 인수 구문 분석 및 모드 감지
명령어:
/video→ 대화형 모드 (1-5단계)/video process <path>→ 특정 파일에 대한 대화형 모드/video share→ 무음 모드: 최신 파일 처리 + 공유/video share <path>→ 무음 모드: 특정 파일 처리 + 공유/video share <path> "context"→ 메타데이터에 대한 추가 컨텍스트가 있는 무음 모드/video start→ 공유 서버 + 터널 시작/video stop→ 공유 중지/video status→ 공유된 비디오 목록/video copy <key_or_name>→ 링크 + passcode를 클립보드에 복사/video remove <key_or_name>→ 레지스트리에서 제거
공유 명령어 (직접 처리, 처리 없음)
공유 레지스트리: <share_folder>/.share_registry.json — manage_registry.py에 의해 관리됨.
start 명령어:
- 기본 설정 읽기 →
share_folder. 설정되지 않은 경우 문의. pgrep -f share_server.py확인. 실행 중이면 상태 표시.- 서버 시작:
python3 "<scripts>/share_server.py" "<share_folder>" --port 8080 & - 터널 시작:
ssh -p 443 -R0:localhost:<port> -o StrictHostKeyChecking=no a.pinggy.io 2>&1 & - 터널 URL 구문 분석. 다음 표시: "서버가 <base_url>에서 실행 중입니다."
- 전체 URL(
<base_url>/v/<key>)로 기존 비디오 나열.
stop 명령어:
pkill -f share_server.py; pkill -f "ssh.*pinggy"; pkill -f "ngrok http"
status 명령어:
python3 "<scripts>/manage_registry.py" list --share-folder "<share_folder>"실행pgrep -f share_server.py로 터널 상태 확인.- 표 표시: key, title, S3 URL, tunnel URL, passcode, created.
copy 명령어:
python3 "<scripts>/manage_registry.py" get --share-folder "<share_folder>" --key "<query>"실행- 형식:
<title>\n<url>\nPasscode: <code>→pbcopy
remove 명령어:
python3 "<scripts>/manage_registry.py" remove --share-folder "<share_folder>" --key "<query>" 실행
무음 모드 (/video share)
한 번의 확인, 한 번의 스크립트 실행, 최소한의 상호 작용.
흐름:
-
비디오 식별(인수 경로 또는
last_folder/ CWD에서 최신) -
출력 폴더 생성
<share_folder>/<video_name>/ -
passcode 생성(무작위 6자리 또는 저장된 기본 설정)
-
확인 표시:
빠른 공유: demo.mov → 동일 해상도 · 압축됨 (CRF 23) · AAC 128k → 트랜스크립트 + 자막 (track) → S3를 통해 공유 (영구 링크) → Passcode: 482910 진행하시겠습니까?옵션: 진행 (권장) / 대화형 모드로 전환
mode가dev-video또는transcript-cheap인 경우,process_and_share.py를 실행하지 말고 대신 "Gemini 분석 엔진" 섹션(저장된 기본 설정을 사용하여 무음으로)을 따른 다음 여전히 업로드 + 공유를 등록하십시오. -
주요 워크플로우 스크립트 실행.
mode가dev-audio인 경우--developer-analysis전달:python3 "<scripts>/process_and_share.py" "<video_path>" \ --output-dir "<output_folder>" \ --share-folder "<share_folder>" \ --credential-dir ~/.config/video-skill \ --resolution keep --crf 23 --preset medium --audio aac-128k \ --subtitles track \ --share s3 \ --passcode "<passcode>" \ [--developer-analysis] \ [--context "<user_context>"]기본
--resolution keep(압축, 동일 해상도). 소스가 ≥1440p/4K인 경우에만--resolution 1080p를 사용하고, 사용자가 명시적으로 수정되지 않은 파일을 원하는 경우keep-original처리를 사용하십시오. -
METADATA_READY:에 대한 stdout 모니터링 — 스크립트가 이 마커를 출력하면: a. 그 앞에 있던TRANSCRIPT_PREVIEW:및METADATA_INFO:를 읽습니다. b. 트랜스크립트 미리보기에서 제목, 설명 및 4-8개의 챕터를 생성합니다. c.mode가dev-audio인 경우(개발자 분석 켜짐): 전체 트랜스크립트(출력 디렉토리의 SRT/VTT에서 읽음, 잘린 미리보기 아님)에서 분석 블록 및 분석 Markdown을 구축합니다. 정확한 형태 및 계약에 대해서는 "metadata.json 참조" 및 "분석 Markdown" 섹션을 참조하십시오. 페이지 언어(RU / DE / EN)와 일치시킵니다. d. metadata.json 참조에 따라 출력 디렉토리에metadata.json을 작성합니다. e. 스크립트가 metadata.json을 감지하고 자동으로 계속됩니다. -
스크립트 완료. 결과 표시, 링크가 생성됩니다.