Communitygithub.com

503496348-ops/mischief-production

비디오와 오디오를 보고, 이해하고, 행동합니다. 로컬 파일, URL, RTSP/라이브 피드 또는 데스크톱 녹화에서 입력을 받아 실시간 컨텍스트와 재생 가능한 스트림 링크를 반환합니다. 프레임을 추출하고, 시각/의미/시간 인덱스를 구축하며, 타임스탬프와 자동 클립으로 순간을 검색합니다. 코덱, FPS, 해상도, 종횡비를 트랜스코딩 및 정규화하고, 자막, 텍스트/이미지 오버레이, 브랜딩, 오디오 오버레이, 더빙, 번역 등 타임라인 편집을 수행하며, 이미지, 오디오, 비디오 등 미디어 에셋을 생성하고, 라이브 스트림이나 데스크톱 캡처에서 이벤트에 대한 실시간 알림을 만듭니다.

mischief-production란 무엇인가요?

이 스킬은 VideoDB SDK를 활용하여 비디오 및 오디오 데이터를 처리, 분석, 편집하는 포괄적인 AI 에이전트 기능을 제공합니다. 주요 기능으로는 데스크톱 화면/마이크/시스템 오디오 캡처, 다양한 소스(로컬 파일, URL, RTSP)로부터의 비디오 수집 및 스트리밍, 음성/시각/키워드 기반 비디오 인덱싱 및 검색, 타임라인 편집(자막 생성/번역/삽입, 오버레이, 오디오 더빙), 생성형 미디어 제작(이미지, 오디오, 비디오), 그리고 라이브 스트림에 대한 실시간 이벤트 알림을 포함합니다. Cursor, Claude Code, Codex와 같은 주요 AI 코딩 도구에서 원활하게 작동하도록 설계되었으며, Python SDK를 통해 모든 작업을 서버 측에서 처리하여 로컬 코덱 도구(ffmpeg 등) 사용을 최소화합니다. 특히 비디오 검색 시 오류 처리(인덱스 중복, 검색 결과 없음)에 대한 명확한 가이드를 제공하며, 데스크톱 캡처 이벤트를 WebSocket을 통해 실시간으로 수집하고 질의하는 기능을 포함합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/503496348-ops/mischief-production/tree/HEAD/skills/ecc-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 저장

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("제품 데모")
    shots = results.get_shots()
    stream_url = results.compile()
except InvalidRequestError as e:
    if "결과를 찾을 수 없음" 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 "결과를 찾을 수 없음" 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 반환, 결과는 webhook을 통해):
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을 전달합니다
Timeline의 음수 타임스탬프묵묵히 깨진 스트림 생성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 솔루션
플랫폼이 비디오 종횡비 또는 해상도를 거부함VideoConfig와 함께 video.reframe() 또는 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 7 individual skills — each has its own dedicated page.

503496348-ops/mischief-production

Use this skill when inspecting Blender characters, rigs, poses, animation retargeting, ground contact, facing direction, or model-vs-motion alignment where screenshots alone are not enough.

503496348-ops/mischief-production

Build reusable Manim explainers for technical concepts, graphs, system diagrams, and product walkthroughs, then hand off to the wider HCP video stack if needed. Use when the user wants a clean animated explainer rather than a generic talking-head script.

503496348-ops/mischief-production

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.

503496348-ops/mischief-production

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.

503496348-ops/mischief-production

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.

503496348-ops/mischief-production

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

503496348-ops/mischief-production

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

관련 스킬