VideoDB 스킬
비디오, 라이브 스트림 및 데스크톱 세션을 위한 인지 + 메모리 + 작업
다음과 같은 경우 이 스킬을 사용하세요:
사용 시기
- 파일, URL, 데스크톱 세션 또는 라이브 스트림에서 비디오 또는 오디오 인지, 색인, 검색 또는 타임라인 편집이 필요한 경우
- 타임스탬프, 검색 가능한 증거, 자막, 클립, 오버레이 또는 실시간 모니터링 알림과 관련된 작업
- 수집, 이해, 검색 및 미디어 작업을 결합한 하나의 워크플로우를 원하는 경우
1) 데스크톱 인지
- 화면, 마이크 및 시스템 오디오를 캡처하는 데스크톱 세션 시작/중지
- 라이브 컨텍스트 스트리밍 및 일화적 세션 메모리 저장
- 말해진 내용과 화면에서 발생하는 상황에 대한 실시간 알림/트리거 실행
- 세션 요약, 검색 가능한 타임라인 및 재생 가능한 증거 링크 생성
2) 비디오 수집 + 스트리밍
- 파일 또는 URL을 수집하고 재생 가능한 웹 스트림 링크 반환
- 트랜스코딩/정규화: 코덱, 비트레이트, FPS, 해상도, 종횡비
3) 색인 + 검색 (타임스탬프 + 증거)
- 시각적, 음성 및 키워드 색인 구축
- 타임스탬프 및 재생 가능한 증거와 함께 정확한 순간 검색 및 반환
- 검색 결과에서 클립 자동 생성
4) 타임라인 편집 + 생성
- 자막: 생성, 번역, 번인
- 오버레이: 텍스트/이미지/브랜딩, 모션 캡션
- 오디오: 배경 음악, 음성 해설, 더빙
- 타임라인 작업을 통한 프로그래밍 방식 구성 및 내보내기
5) 라이브 스트림 (RTSP) + 모니터링
- RTSP/라이브 피드 연결
- 실시간 시각적 및 음성 이해 실행 및 모니터링 워크플로우를 위한 이벤트/알림 내보내기
일반적인 입력
- 로컬 파일 경로, 공개 URL 또는 RTSP URL
- 데스크톱 캡처 요청: 세션 시작 / 중지 / 요약
- 원하는 작업: 이해를 위한 컨텍스트 가져오기, 트랜스코딩 사양, 색인 사양, 검색 쿼리, 클립 범위, 타임라인 편집, 알림 규칙
일반적인 출력
- 스트림 URL
- 타임스탬프 및 증거 링크가 포함된 검색 결과
- 생성된 자산: 자막, 오디오, 이미지, 클립
- 라이브 스트림을 위한 이벤트/알림 페이로드
- 데스크톱 세션 요약 및 메모리 항목
표준 프롬프트 (예시)
- "데스크톱 캡처를 시작하고 비밀번호 필드가 나타나면 알림을 보내줘."
- "내 세션을 녹화하고 종료될 때 실행 가능한 요약을 생성해줘."
- "이 파일을 수집하고 재생 가능한 스트림 링크를 반환해줘."
- "이 폴더를 색인하고 사람이 있는 모든 장면을 찾아 타임스탬프를 반환해줘."
- "자막을 생성하고 번인한 후 가벼운 배경 음악을 추가해줘."
- "이 RTSP URL을 연결하고 영역에 사람이 들어오면 알림을 보내줘."
Python 코드 실행
VideoDB 코드를 실행하기 전에 프로젝트 디렉토리로 이동하고 환경 변수를 로드하세요:
from dotenv import load_dotenv
load_dotenv(".env")
import videodb
conn = videodb.connect()
이것은 다음에서 VIDEO_DB_API_KEY를 읽습니다:
- 환경 (이미 내보낸 경우)
- 현재 디렉토리의 프로젝트
.env파일
키가 없으면 videodb.connect()가 자동으로 AuthenticationError를 발생시킵니다.
짧은 인라인 명령어가 작동하는 경우 스크립트 파일을 작성하지 마세요.
인라인 Python (python -c "...")을 작성할 때는 항상 적절한 형식의 코드를 사용하세요. 세미콜론을 사용하여 문장을 구분하고 읽기 쉽게 유지하세요. 약 3문장보다 긴 경우 대신 heredoc을 사용하세요:
python << 'EOF'
from dotenv import load_dotenv
load_dotenv(".env")
import videodb
conn = videodb.connect()
coll = conn.get_collection()
print(f"비디오 수: {len(coll.get_videos())}")
EOF
설정
사용자가 "videodb 설정" 등을 요청한 경우:
1. SDK 설치
pip install "videodb[capture]" python-dotenv
Linux에서 videodb[capture]가 실패하면 capture extras 없이 설치하세요:
pip install videodb python-dotenv
2. API 키 구성
사용자는 다음 방법 중 하나를 사용하여 VIDEO_DB_API_KEY를 설정해야 합니다:
- 터미널에서 내보내기 (Claude 시작 전):
export VIDEO_DB_API_KEY=your-key - 프로젝트
.env파일: 프로젝트의.env파일에VIDEO_DB_API_KEY=your-key저장
https://console.videodb.io 에서 무료 API 키를 받으세요 (50회 무료 업로드, 신용 카드 불필요).
API 키를 직접 읽거나, 쓰거나, 처리하지 마세요. 항상 사용자가 설정하도록 하세요.
빠른 참조
미디어 업로드
# URL
video = coll.upload(url="https://example.com/video.mp4")
# YouTube
video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")
# 로컬 파일
video = coll.upload(file_path="/path/to/video.mp4")
자막 + 트랜스크립트
# force=True는 비디오가 이미 색인된 경우 오류를 건너뜁니다
video.index_spoken_words(force=True)
text = video.get_transcript_text()
stream_url = video.add_subtitle()
비디오 내 검색
from videodb.exceptions import InvalidRequestError
video.index_spoken_words(force=True)
# search()는 결과가 없을 때 InvalidRequestError를 발생시킵니다.
# 항상 try/except로 감싸고 "결과 없음"을 빈 값으로 처리하세요.
try:
results = video.search("product demo")
shots = results.get_shots()
stream_url = results.compile()
except InvalidRequestError as e:
if "No results found" in str(e):
shots = []
else:
raise
장면 검색
import re
from videodb import SearchType, IndexType, SceneExtractionType
from videodb.exceptions import InvalidRequestError
# index_scenes()에는 force 매개변수가 없습니다. 장면 색인이 이미 존재하면 오류를 발생시킵니다.
# 오류에서 기존 색인 ID를 추출하세요.
try:
scene_index_id = video.index_scenes(
extraction_type=SceneExtractionType.shot_based,
prompt="이 장면의 시각적 내용을 설명하세요.",
)
except Exception as e:
match = re.search(r"id\s+([a-f0-9]+)", str(e))
if match:
scene_index_id = match.group(1)
else:
raise
# score_threshold를 사용하여 관련성 낮은 노이즈를 필터링하세요 (권장: 0.3+)
try:
results = video.search(
query="화이트보드에 쓰는 사람",
search_type=SearchType.semantic,
index_type=IndexType.scene,
scene_index_id=scene_index_id,
score_threshold=0.3,
)
shots = results.get_shots()
stream_url = results.compile()
except InvalidRequestError as e:
if "No results found" in str(e):
shots = []
else:
raise
타임라인 편집
중요: 타임라인을 구축하기 전에 항상 타임스탬프의 유효성을 검증하세요:
start는 0 이상이어야 함 (음수 값은 자동으로 허용되지만 깨진 출력을 생성함)start는end보다 작아야 함end는video.length이하여야 함
from videodb.timeline import Timeline
from videodb.asset import VideoAsset, TextAsset, TextStyle
timeline = Timeline(conn)
timeline.add_inline(VideoAsset(asset_id=video.id, start=10, end=30))
timeline.add_overlay(0, TextAsset(text="끝", duration=3, style=TextStyle(fontsize=36)))
stream_url = timeline.generate_stream()
비디오 트랜스코딩 (해상도/품질 변경)
from videodb import TranscodeMode, VideoConfig, AudioConfig
# 서버 측에서 해상도, 품질 또는 종횡비 변경
job_id = conn.transcode(
source="https://example.com/video.mp4",
callback_url="https://example.com/webhook",
mode=TranscodeMode.economy,
video_config=VideoConfig(resolution=720, quality=23, aspect_ratio="16:9"),
audio_config=AudioConfig(mute=False),
)
종횡비 재설정 (소셜 플랫폼용)
경고: reframe()은 느린 서버 측 작업입니다. 긴 비디오의 경우 몇 분이 걸리거나 시간이 초과될 수 있습니다. 모범 사례:
- 가능하면 항상
start/end를 사용하여 짧은 세그먼트로 제한 - 전체 길이 비디오의 경우
callback_url을 사용하여 비동기 처리 - 먼저
Timeline에서 비디오를 자른 다음 더 짧은 결과를 reframe
from videodb import ReframeMode
# 항상 짧은 세그먼트를 reframe하는 것을 선호:
reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)
# 전체 길이 비디오에 대한 비동기 reframe (None 반환, 웹훅을 통해 결과 수신):
video.reframe(target="vertical", callback_url="https://example.com/webhook")
# 사전 설정: "vertical" (9:16), "square" (1:1), "landscape" (16:9)
reframed = video.reframe(start=0, end=60, target="square")
# 사용자 정의 크기
reframed = video.reframe(start=0, end=60, target={"width": 1280, "height": 720})
생성형 미디어
image = coll.generate_image(
prompt="산 위의 일몰",
aspect_ratio="16:9",
)
오류 처리
from videodb.exceptions import AuthenticationError, InvalidRequestError
try:
conn = videodb.connect()
except AuthenticationError:
print("VIDEO_DB_API_KEY를 확인하세요")
try:
video = coll.upload(url="https://example.com/video.mp4")
except InvalidRequestError as e:
print(f"업로드 실패: {e}")
일반적인 문제
| 시나리오 | 오류 메시지 | 해결 방법 |
|---|---|---|
| 이미 색인된 비디오 색인 | 이 비디오에 대한 음성 단어 색인이 이미 존재합니다 | video.index_spoken_words(force=True)를 사용하여 이미 색인된 경우 건너뜀 |
| 장면 색인이 이미 존재함 | id XXXX인 장면 색인이 이미 존재합니다 | re.search(r"id\s+([a-f0-9]+)", str(e))로 오류에서 기존 scene_index_id 추출 |
| 검색 결과 없음 | InvalidRequestError: 결과 없음 | 예외를 포착하고 빈 결과로 처리 (shots = []) |
| Reframe 시간 초과 | 긴 비디오에서 무기한 차단 | start/end를 사용하여 세그먼트를 제한하거나 비동기 처리에 callback_url 전달 |
| 타임라인의 음수 타임스탬프 | 자동으로 깨진 스트림 생성 | VideoAsset을 생성하기 전에 항상 start >= 0 검증 |
generate_video() / create_collection() 실패 | 허용되지 않는 작업 또는 최대 한도 | 요금제 제한 기능 — 사용자에게 요금제 제한에 대해 알림 |
추가 문서
참조 문서는 이 SKILL.md 파일과 동일한 디렉토리의 reference/ 디렉토리에 있습니다. 필요한 경우 Glob 도구를 사용하여 찾으세요.
- reference/api-reference.md - 전체 VideoDB Python SDK API 참조
- reference/search.md - 비디오 검색에 대한 심층 가이드 (음성 단어 및 장면 기반)
- reference/editor.md - 타임라인 편집, 자산 및 구성
- reference/streaming.md - HLS 스트리밍 및 즉시 재생
- reference/generative.md - AI 기반 미디어 생성 (이미지, 비디오, 오디오)
- reference/rtstream.md - 라이브 스트림 수집 워크플로우 (RTSP/RTMP)
- reference/rtstream-reference.md - RTStream SDK 메서드 및 AI 파이프라인
- reference/capture.md - 데스크톱 캡처 워크플로우
- reference/capture-reference.md - 캡처 SDK 및 WebSocket 이벤트
- reference/use-cases.md - 일반적인 비디오 처리 패턴 및 예제
화면 녹화 (데스크톱 캡처)
ws_listener.py를 사용하여 녹화 세션 중 WebSocket 이벤트를 캡처하세요. 데스크톱 캡처는 macOS만 지원합니다.
빠른 시작
- 리스너 시작:
python scripts/ws_listener.py & - WebSocket ID 가져오기:
cat /tmp/videodb_ws_id - 캡처 코드 실행 (전체 워크플로우는 reference/capture.md 참조)
- 이벤트 기록 위치:
/tmp/videodb_events.jsonl
이벤트 쿼리
import json
events = [json.loads(l) for l in open("/tmp/videodb_events.jsonl")]
# 모든 트랜스크립트 가져오기
transcripts = [e["data"]["text"] for e in events if e.get("channel") == "transcript"]
# 최근 5분간의 시각적 설명 가져오기
import time
cutoff = time.time() - 300
recent_visual = [e for e in events
if e.get("channel") == "visual_index" and e["unix_ts"] > cutoff]
유틸리티 스크립트
- scripts/ws_listener.py - WebSocket 이벤트 리스너 (JSONL로 덤프)
전체 캡처 워크플로우는 reference/capture.md를 참조하세요.
VideoDB가 작업을 지원하는 경우 ffmpeg, moviepy 또는 로컬 인코딩 도구를 사용하지 마세요. 다음은 모두 VideoDB에서 서버 측에서 처리합니다 — 자르기, 클립 결합, 오디오 또는 음악 오버레이, 자막 추가, 텍스트/이미지 오버레이, 트랜스코딩, 해상도 변경, 종횡비 변환, 플랫폼 요구 사항에 따른 크기 조정, 전사 및 미디어 생성. reference/editor.md의 제한 사항(전환, 속도 변경, 크롭/줌, 색상 그레이딩, 볼륨 믹싱)에 나열된 작업에 대해서만 로컬 도구로 대체하세요.
무엇을 사용할지 선택하는 기준
| 문제 | VideoDB 해결 방법 |
|---|---|
| 플랫폼이 비디오 종횡비 또는 해상도를 거부함 | video.reframe() 또는 VideoConfig와 함께 conn.transcode() 사용 |
| Twitter/Instagram/TikTok용으로 비디오 크기 조정 필요 | video.reframe(target="vertical") 또는 target="square" 사용 |
| 해상도 변경 필요 (예: 1080p → 720p) | VideoConfig(resolution=720)와 함께 conn.transcode() 사용 |
| 비디오에 오디오/음악 오버레이 필요 | Timeline에서 AudioAsset 사용 |
| 자막 추가 필요 | video.add_subtitle() 또는 CaptionAsset 사용 |
| 클립 결합/자르기 필요 | Timeline에서 VideoAsset 사용 |
| 음성 해설, 음악 또는 효과음 생성 필요 | coll.generate_voice(), generate_music(), generate_sound_effect() 사용 |
저장소
https://github.com/video-db/skills
유지 관리자: VideoDB
제한 사항
- 이 스킬은 작업이 위에서 설명한 범위와 명확하게 일치하는 경우에만 사용하세요.
- 출력물을 환경별 검증, 테스트 또는 전문가 검토의 대체물로 취급하지 마세요.
- 필수 입력, 권한, 안전 경계 또는 성공 기준이 누락된 경우 중단하고 명확한 설명을 요청하세요.