Communitygithub.com

VideoDB 스킬 - 비디오/오디오 분석, 색인, 편집

영상과 오디오를 보고, 이해하고, 조작합니다. 로컬 파일, URL, RTSP 라이브 스트림 또는 데스크톱 캡처에서 입력받아 실시간 컨텍스트와 재생 가능한 스트림 링크를 반환합니다. 프레임 추출, 시각/의미/시간 색인, 타임스탬프 기반 검색 및 자동 클립 생성을 수행하고, 트랜스코딩, 타임라인 편집, 미디어 에셋 생성, 라이브 스트림 이벤트 알림을 제공합니다.

오디오 분석, 색인, 편집란 무엇인가요?

이 스킬은 VideoDB SDK를 통해 비디오, 오디오, 라이브 스트림, 데스크톱 캡처에 대한 종합적인 인지, 메모리, 조작 기능을 제공합니다. 개발자는 로컬 파일, 공개 URL, YouTube 링크, RTSP 라이브 피드를 손쉽게 업로드하고 즉시 재생 가능한 HLS 스트림 링크를 얻을 수 있습니다. 비디오 내부의 대화 음성 인덱싱, 시각적 장면 검색, 키워드 검색을 통해 정확한 타임스탬프와 증거 링크를 반환하며, 검색 결과에서 자동 클립을 생성할 수 있습니다. 타임라인 API를 활용하여 자막 생성/번역/하드코딩, 텍스트/이미지/브랜딩 오버레이, 배경 음악 및 더빙 추가, 동영상 트랜스코딩(코덱, 해상도, 프레임레이트, 종횡비 변경)을 서버 사이드에서 처리합니다. 데스크톱 캡처 기능을 통해 화면, 마이크, 시스템 오디오를 실시간으로 스트리밍하고 세션 메모리를 저장하며, 말한 내용과 화면 이벤트에 대한 실시간 알림을 생성합니다. 모든 무거운 작업은 VideoDB 서버에서 처리되므로 ffmpeg, moviepy와 같은 로컬 도구를 사용할 필요가 없습니다. 이 스킬은 Claude Code, Cursor, Codex 등 다양한 AI 에이전트 환경에서 동작합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cody-W-Tucker/skills/tree/HEAD/skills/videodb

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

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

문서

VideoDB 스킬

비디오, 라이브 스트림, 데스크톱 세션을 위한 인지 + 메모리 + 액션.

사용 시기

데스크톱 인지

  • 데스크톱 세션을 시작/중지하여 화면, 마이크, 시스템 오디오 캡처
  • 실시간 컨텍스트를 스트리밍하고 에피소드 세션 메모리 저장
  • 말한 내용과 화면에서 발생하는 일에 대해 실시간 알림/트리거 실행
  • 세션 요약, 검색 가능한 타임라인, 재생 가능한 증거 링크 생성

비디오 수집 + 스트리밍

  • 파일 또는 URL을 수집하고 재생 가능한 웹 스트림 링크 반환
  • 트랜스코딩/정규화: 코덱, 비트레이트, fps, 해상도, 종횡비

색인 + 검색 (타임스탬프 + 증거)

  • 시각적, 음성, 키워드 색인 구축
  • 타임스탬프와 재생 가능한 증거로 정확한 순간 검색 및 반환
  • 검색 결과에서 클립 자동 생성

타임라인 편집 + 생성

  • 자막: 생성, 번역, 하드코딩
  • 오버레이: 텍스트/이미지/브랜딩, 모션 캡션
  • 오디오: 배경 음악, 내레이션, 더빙
  • 타임라인 연산을 통한 프로그래매틱 구성 및 내보내기

라이브 스트림 (RTSP) + 모니터링

  • RTSP/라이브 피드 연결
  • 실시간 시각 및 음성 이해 실행 및 모니터링 워크플로를 위한 이벤트/알림 방출

작동 방식

일반 입력

  • 로컬 파일 경로, 공개 URL, 또는 RTSP URL
  • 데스크톱 캡처 요청: 세션 시작 / 중지 / 요약
  • 원하는 연산: 컨텍스트 얻기, 트랜스코드 사양, 색인 사양, 검색 쿼리, 클립 범위, 타임라인 편집, 알림 규칙

일반 출력

  • 스트림 URL
  • 타임스탬프 및 증거 링크가 포함된 검색 결과
  • 생성된 에셋: 자막, 오디오, 이미지, 클립
  • 라이브 스트림용 이벤트/알림 페이로드
  • 데스크톱 세션 요약 및 메모리 항목

Python 코드 실행

VideoDB 코드를 실행하기 전에 프로젝트 디렉토리로 이동하여 환경 변수를 로드하세요:

from dotenv import load_dotenv
load_dotenv(".env")

import videodb
conn = videodb.connect()

이 코드는 VIDEO_DB_API_KEY를 다음 순서로 읽습니다:

  1. 환경 변수 (이미 내보낸 경우)
  2. 현재 디렉토리의 프로젝트 .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 extra 없이 설치하세요:

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 저장

무료 API 키는 console.videodb.io에서 받을 수 있습니다 (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에서 비디오를 자른 다음, 더 짧은 결과를 리프레임
from videodb import ReframeMode

# 항상 짧은 세그먼트 리프레이밍을 선호:
reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)

# 전체 길이 비디오를 위한 비동기 리프레임 (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: No results found예외를 잡아서 빈 결과로 처리 (shots = [])
리프레임 시간 초과긴 비디오에서 무기한 차단됨start/end를 사용하여 세그먼트 제한, 또는 비동기 처리를 위해 callback_url 전달
타임라인의 음수 타임스탬프자동으로 깨진 스트림 생성VideoAsset 생성 전에 항상 start >= 0 확인
generate_video() / create_collection() 실패작업이 허용되지 않음 또는 최대 한도요금제에 따라 제한되는 기능 — 사용자에게 요금제 한도 안내

예제

표준 프롬프트

  • "데스크톱 캡처를 시작하고 비밀번호 필드가 나타나면 알림을 보내줘."
  • "내 세션을 녹화하고 종료 시 실행 가능한 요약을 생성해줘."
  • "이 파일을 수집하고 재생 가능한 스트림 링크를 반환해줘."
  • "이 폴더를 인덱싱하고 사람이 있는 모든 장면을 찾아 타임스탬프를 반환해줘."
  • "자막을 생성하고, 하드코딩하고, 가벼운 배경 음악을 추가해줘."
  • "이 RTSP URL에 연결하고 사람이 구역에 들어오면 알림을 보내줘."

화면 녹화 (데스크톱 캡처)

녹화 세션 중 WebSocket 이벤트를 캡처하려면 ws_listener.py를 사용하세요. 데스크톱 캡처는 macOS만 지원합니다.

빠른 시작

  1. 상태 디렉토리 선택: STATE_DIR="${VIDEODB_EVENTS_DIR:-$HOME/.local/state/videodb}"
  2. 리스너 시작: VIDEODB_EVENTS_DIR="$STATE_DIR" python scripts/ws_listener.py --clear "$STATE_DIR" &
  3. WebSocket ID 가져오기: cat "$STATE_DIR/videodb_ws_id"
  4. 캡처 코드 실행 (전체 워크플로는 reference/capture.md 참조)
  5. 이벤트 기록 위치: $STATE_DIR/videodb_events.jsonl

새로운 캡처 실행을 시작할 때는 항상 --clear를 사용하여 오래된 음성 및 시각 이벤트가 새 세션에 유출되지 않도록 하세요.

이벤트 조회

import json
import os
import time
from pathlib import Path

events_dir = Path(os.environ.get("VIDEODB_EVENTS_DIR", Path.home() / ".local" / "state" / "videodb"))
events_file = events_dir / "videodb_events.jsonl"
events = []

if events_file.exists():
    with events_file.open(encoding="utf-8") as handle:
        for line in handle:
            try:
                events.append(json.loads(line))
            except json.JSONDecodeError:
                continue

transcripts = [e["data"]["text"] for e in events if e.get("channel") == "transcript"]
cutoff = time.time() - 300
recent_visual = [
    e for e in events
    if e.get("channel") == "visual_index" and e["unix_ts"] > cutoff
]

추가 문서

참조 문서는 이 SKILL.md 파일과 동일한 디렉토리의 reference/에 있습니다. 필요한 경우 Glob 도구를 사용하여 찾으세요.

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
내레이션, 음악 또는 SFX 생성 필요coll.generate_voice(), generate_music(), generate_sound_effect()

출처

이 스킬의 참조 자료는 skills/videodb/reference/ 아래에 로컬로 제공됩니다.

런타임에 외부 저장소 링크를 따르는 대신 위의 로컬 복사본을 사용하세요.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

Cody-W-Tucker/skills

Landing page quality assessment for paid advertising campaigns. Evaluates message match, page speed, mobile experience, trust signals, form optimization, and conversion rate potential. Use when user says landing page, post-click experience, landing page audit, conversion rate, or landing page optimization.

Cody-W-Tucker/skills

TikTok Ads deep analysis covering creative quality, tracking, bidding, campaign structure, and TikTok Shop. Evaluates 28 checks with emphasis on creative-first strategy, safe zone compliance, and Smart+ campaigns. Use when user says TikTok Ads, TikTok marketing, TikTok Shop, Spark Ads, Smart+, or TikTok campaign.

Cody-W-Tucker/skills

YouTube Ads specific analysis covering campaign types, creative quality, audience targeting, and measurement. Evaluates video ad performance across skippable, non-skippable, bumper, Shorts, Demand Gen, and Connected TV formats. Covers VAC→Demand Gen migration, Shorts creative requirements, and CTV shoppable ads. Use when user says YouTube Ads, video ads, pre-roll, bumper ads, YouTube campaign, Shorts ads, or CTV ads.

Cody-W-Tucker/skills

Craft the story that makes investors say \"I want in.\" Master the narrative structure that Reid Hoffman, Sequoia, and top founders use to raise capital. Use when: **Preparing to fundraise** to develop your story before the deck; **Investor meetings** to structure conversations that convert; **Pitch practice** to refine your narrative arc; **Cold outreach** to write compelling investor emails; **Pivoting** to reframe your story after a change

Cody-W-Tucker/skills

Identify the best GTM motions and tools across 7 motion types: Inbound, Outbound, Paid Digital, Community, Partners, ABM, and PLG. Use when selecting marketing channels, choosing between inbound and outbound strategy, or planning cross-channel campaigns.

Cody-W-Tucker/skills

Produce a print-grade single-page kami (紙 / 纸) document — warm parchment canvas, ink-blue accent, serif at one weight, no italic, no cool grays. The output reads like a professional white paper or studio one-pager, not an app UI. Multilingual by design (EN · zh-CN · ja). One self-contained HTML file, zero dependencies.

Cody-W-Tucker/skills

Optimize landing pages for maximum conversions using proven frameworks from Unbounce and Oli Gardner—apply the \"one goal, one message, one action\" principle with data-driven design, copy, and CTA best practices. Use when: **Create a new landing page** for a campaign; **Optimize an existing landing page** that isn't converting; **Review landing page design** before launch; **Improve form conversion rates** on lead gen pages; **A/B test landing page elements** systematically

Cody-W-Tucker/skills

Advanced motion patterns for React / Next.js — drag & drop, gestures, text animations, SVG path drawing, custom hooks, imperative sequences (useAnimate), loaders, and the full API decision tree. Requires motion-foundations.

Cody-W-Tucker/skills

Motion tokens, spring presets, performance rules, device adaptation, accessibility enforcement, and SSR safety for React / Next.js using motion/react. Foundation layer — all other motion skills depend on this.

Cody-W-Tucker/skills

A single-frame motion-design composition with looping CSS animations — rotating type ring, animated globe, ticking timer, parallax labels. Renders as a hero video poster you can hand straight to HyperFrames or any keyframe-based exporter. Use when the brief asks for "motion design", "animated hero", "loop", "video poster", "title card", or pairs Open Claude Design with HyperFrames for a kinetic export.

Cody-W-Tucker/skills

Production-ready animation patterns for React / Next.js — button, modal, toast, stagger, page transitions, exit animations, scroll, and layout — built on motion-foundations tokens and springs.

Cody-W-Tucker/skills

Production-ready UI motion system for React/Next.js. Use when implementing animations, transitions, or motion patterns.

Cody-W-Tucker/skills

Produce a single-file slide deck in the Atelier Zero visual language (warm-paper background, italic-serif emphasis spans, coral terminating dots, surreal collage plates) — Open Design's brand deck recipe. The deck uses **horizontal magazine-style swipe pagination** (←/→, wheel, swipe), a per-slide chrome strip with brand mark and slide counter, an ESC overview grid, a coral progress bar, and inherits the canonical stylesheet + 16-slot image library from the sister `open-design-landing` skill.

Cody-W-Tucker/skills

Produce a world-class single-page editorial landing site in the Atelier Zero visual language (Monocle / Apartamento / Études editorial collage) — the same aesthetic Open Design uses for its own marketing surface. The agent fills a typed `inputs.json` from a brand brief, optionally generates 16 collage assets via gpt-image-2, then runs a pure-function composer that emits a self-contained HTML file; a separate path can mirror the Astro marketing site in `apps/landing-page/`. Drop-in scroll-reveal motion and a Headroom-style sticky nav are wired automatically.

Cody-W-Tucker/skills

Best practices for Remotion - Video creation in React. 29 domain-specific rules covering 3D, animations, audio, captions, charts, transitions, and more.

Cody-W-Tucker/skills

Single-page SaaS landing with hero, features, social proof, pricing, and CTA. Respects the active DESIGN.md color/typography/layout tokens. Trigger keywords: "saas landing", "marketing page", "product landing".

Cody-W-Tucker/skills

Single-page SaaS landing with hero, features, social proof, pricing, and CTA. Respects the active DESIGN.md color/typography/layout tokens. Trigger keywords: "saas landing", "marketing page", "product landing".

Cody-W-Tucker/skills

Master April Dunford's 8-step sales narrative from \"Sales Pitch\" (2023). Transform your positioning into a compelling story that wins enterprise deals. Use when: Structuring B2B sales presentations and demos; Creating pitch decks for complex products; Training sales teams on narrative-driven selling; Converting positioning strategy into sales conversations; Winning against entrenched competitors

Cody-W-Tucker/skills

Swiss-style user-research narrative template in warm-paper editorial aesthetics. Use when users ask for a premium research deck or story-first live artifact with minimalist typography, high-clarity layout, subtle motion, donut breakdowns, and keyboard/click navigation across slides in a single HTML file.

Cody-W-Tucker/skills

Download YouTube videos with customizable quality and format options. Use this skill when the user asks to download, save, or grab YouTube videos. Supports various quality settings (best, 1080p, 720p, 480p, 360p), multiple formats (mp4, webm, mkv), and audio-only downloads as MP3.

관련 스킬