Communitygithub.com

ComeOnOliver/skillshub

針對影片和音訊進行「觀察、理解、行動」。可從本機檔案、URL、RTSP/即時串流或桌面畫面進行輸入;回傳即時情境與可播放的串流連結;提取影格、建立視覺/語意/時間索引、搜尋片段並提供時間戳記與自動剪輯;進行轉碼與正規化、時間軸編輯、媒體資產生成,並為即時串流與桌面錄製建立即時警示。

skillshub 是什麼?

這是一個 VideoDB 技能的本地化說明。該技能為 AI 代理(如 Claude Code)提供全面的影片與音訊處理能力,涵蓋「感知、記憶與行動」三個層面。它支援從多種來源(本機檔案、URL、RTSP 即時串流、桌面畫面與音訊)進行內容攝取,並能回傳可播放的串流連結。在理解層面,技能可建立影片的視覺、語意與時間索引,並透過語義或關鍵字搜尋找到精確的片段,回傳時間戳記與可播放的證據。在行動層面,它支援轉碼(解析度、幀率、編碼格式調整)、時間軸編輯(字幕產生、翻譯與燒錄;文字/圖片覆疊;音訊覆疊、配音與翻譯)以及基於 AI 的媒體資產生成(圖片、音訊、影片)。此外,技能還包含桌面錄製功能,可捕捉螢幕、麥克風與系統音訊,提供即時警報和會話摘要。該技能透過 Python SDK 與 VideoDB 服務互動,提供了詳盡的 API 參考與範例程式碼,並特別強調錯誤處理與使用時機的最佳實踐。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/affaan-m/everything-claude-code/videodb

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

VideoDB 技能

影片、即時串流與桌面會話的感知 + 記憶 + 行動。

使用時機

桌面感知

  • 啟動/停止 桌面會話,捕捉螢幕、麥克風與系統音訊
  • 串流即時情境並儲存情節性會話記憶
  • 針對螢幕上發生的內容與對話執行即時警示/觸發器
  • 產生會話摘要、可搜尋的時間軸以及可播放的證據連結

影片攝取 + 串流

  • 攝取檔案或 URL 並回傳可播放的網路串流連結
  • 轉碼/正規化:編碼格式、位元率、幀率、解析度、畫面比例

索引 + 搜尋(時間戳記 + 證據)

  • 建立視覺、語音和關鍵字索引
  • 搜尋並回傳確切的片段,附帶時間戳記與可播放的證據
  • 從搜尋結果中自動建立剪輯

時間軸編輯 + 生成

  • 字幕:產生、翻譯、燒錄
  • 覆疊:文字/圖片/品牌標誌、動態字幕
  • 音訊:背景音樂、旁白、配音
  • 透過時間軸操作進行程式化組合與匯出

即時串流 (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

如果 videodb[capture] 在 Linux 上失敗,請安裝不含 capture 擴充的版本:

pip install videodb python-dotenv

2. 設定 API 金鑰

使用者必須使用任一種方法設定 VIDEO_DB_API_KEY:

  • 在終端機中匯出(啟動 Claude 之前):export VIDEO_DB_API_KEY=你的金鑰
  • 專案 .env 檔案:將 VIDEO_DB_API_KEY=你的金鑰 儲存在專案的 .env 檔案中

請前往 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 "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,結果透過 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}")

常見陷阱

情境錯誤訊息解決方案
對已建立索引的影片再次索引Spoken word index for video already exists使用 video.index_spoken_words(force=True) 跳過(如果已建立索引)
場景索引已存在Scene index with id XXXX already exists使用 re.search(r"id\s+([a-f0-9]+)", str(e)) 從錯誤中取出現有的 scene_index_id
搜尋找不到匹配結果InvalidRequestError: No results found捕捉異常並視為空結果(shots = [])
Reframe 超時長影片會無限期阻塞使用 start/end 限制片段,或傳遞 callback_url 進行非同步處理
時間軸上的負數時間戳記默默地產生損毀的串流在建立 VideoAsset 之前,務必驗證 start >= 0
generate_video() / create_collection() 失敗Operation not allowed 或 maximum limit方案限制的功能 — 通知使用者方案限制相關資訊

範例

標準提示

  • 「開始桌面錄製,並在出現密碼欄位時發出警示。」
  • 「錄製我的會話,並在結束時產生可操作的摘要。」
  • 「攝取此檔案並回傳可播放的串流連結。」
  • 「為此資料夾建立索引,找出所有有人物的場景,回傳時間戳記。」
  • 「產生字幕,燒錄進去,並加入輕柔的背景音樂。」
  • 「連接此 RTSP URL,並在有人進入區域時發出警示。」

螢幕錄製(桌面擷取)

使用 ws_listener.py 在錄製會話期間擷取 WebSocket 事件。桌面擷取僅支援 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
需要產生旁白、音樂或音效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.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Next.js 16+ uses App Router with Server Components by default. Client Components are only used when interactivity is needed (hooks, event handlers, browser APIs).

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

相關技能