Communitygithub.com

Desesbraker/agentes-vip

影片與音訊的感知、索引與編輯。可攝入檔案/網址/直播串流、建立視覺與語音索引、以時間戳記搜尋、編輯時間軸、加入疊加層與字幕、生成媒體內容,以及建立即時警示。

agentes-vip 是什麼?

VideoDB 技能為 AI 代理(如 Claude Code、Cursor 等)提供了一套完整的影片與音訊處理管線。它不僅能處理上傳的檔案和網址,還能即時監控桌面畫面、麥克風與系統音訊,建立「情節記憶」以便後續查詢。開發者可利用此技能執行視覺與語意搜尋(附精確時間戳記與可播放證據連結),並透過 Timeline API 進行程式化編輯,包括加入字幕、圖片或文字疊加層、背景音樂、旁白,甚至進行解析度與畫面比例的轉換。該技能支援 RTSP 直播串流的即時分析與事件觸發,並提供 Python SDK 整合。平台支援包括 macOS 桌面錄製(WebSocket 事件)與伺服器端轉碼,建議用 VideoDB 的原生 API 取代 ffmpeg 或 moviepy 等本地工具,只有在少數限制操作(如轉場效果、速度調整)時才回退至本地工具。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Desesbraker/agentes-vip/tree/HEAD/full%20skill/plugins/antigravity-awesome-skills-claude/skills/videodb

在你喜歡的 AI 中提問

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

說明文件

VideoDB 技能

感知 + 記憶 + 動作:適用於影片、直播串流與桌面工作階段。

當您需要下列功能時,請使用此技能:

1) 桌面感知

  • 啟動/停止桌面工作階段,擷取螢幕、麥克風與系統音訊
  • 串流即時情境並儲存情節式工作階段記憶
  • 針對畫面上所說與發生的事情執行即時警示/觸發
  • 產出工作階段摘要、可搜尋的時間軸,以及可播放的證據連結

2) 影片攝入與串流

  • 攝入檔案或網址,並回傳可播放的網路串流連結
  • 轉碼/標準化:編碼器、位元率、影格率、解析度、畫面比例

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

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

4) 時間軸編輯與產生

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

5) 直播串流 (RTSP) + 監控

  • 連接 RTSP / 即時饋送
  • 執行即時視覺與語音理解,並發出事件/警示以供監控工作流程使用

常見輸入

  • 本地檔案路徑、公開網址或 RTSP 網址
  • 桌面擷取請求:開始 / 停止 / 摘要工作階段
  • 所需操作:取得情境以便理解、轉碼規格、索引規格、搜尋查詢、剪輯範圍、時間軸編輯、警示規則

常見輸出

  • 串流網址
  • 附帶時間戳記與證據連結的搜尋結果
  • 產出的素材:字幕、音訊、圖片、剪輯片段
  • 直播串流的事件/警示負載
  • 桌面工作階段摘要與記憶項目

典型提示(範例)

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

執行 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 擴充:

pip install videodb python-dotenv

2. 設定 API 金鑰

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

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

在 https://console.videodb.io 可取得免費 API 金鑰(50 次免費上傳,無需信用卡)。

請勿自行讀取、寫入或處理 API 金鑰。務必讓使用者自行設定。

快速參考

上傳媒體

# 網址
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="The End", 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

# 預設優先重塑短片段:
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 進行非同步處理
Timeline 上的負值時間戳記靜默產生毀損串流在建立 VideoAsset 之前務必驗證 start >= 0
generate_video() / create_collection() 失敗Operation not allowed 或 maximum limit方案限制功能——通知使用者方案限制

其他文件

參考文件位於此 SKILL.md 檔案旁邊的 reference/ 目錄中。必要時請使用 Glob 工具來定位。

螢幕錄製(桌面擷取)

使用 ws_listener.py 在錄製工作階段期間擷取 WebSocket 事件。桌面擷取僅支援 macOS。

快速入門

  1. 啟動監聽器:python scripts/ws_listener.py &
  2. 取得 WebSocket ID:cat /tmp/videodb_ws_id
  3. 執行擷取程式碼(完整工作流程請參閱 reference/capture.md)
  4. 事件寫入:/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]

工具指令稿

完整的擷取工作流程請參閱 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

Individual skills in this repo

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

Desesbraker/agentes-vip

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

Desesbraker/agentes-vip

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

Desesbraker/agentes-vip

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

Desesbraker/agentes-vip

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

Desesbraker/agentes-vip

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

Desesbraker/agentes-vip

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

Desesbraker/agentes-vip

Best practices for Remotion - Video creation in React

Desesbraker/agentes-vip

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

Desesbraker/agentes-vip

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

Desesbraker/agentes-vip

Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.

Desesbraker/agentes-vip

Automate TikTok tasks via Rube MCP (Composio): upload/publish videos, post photos, manage content, and view user profiles/stats. Always search tools first for current schemas.

Desesbraker/agentes-vip

Upload, stream, search, edit, transcribe, and generate AI video and audio using the VideoDB SDK.

Desesbraker/agentes-vip

Automate YouTube tasks via Rube MCP (Composio): upload videos, manage playlists, search content, get analytics, and handle comments. Always search tools first for current schemas.

Desesbraker/agentes-vip

Extract transcripts from YouTube videos and generate comprehensive, detailed summaries using intelligent analysis frameworks

Desesbraker/agentes-vip

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

Desesbraker/agentes-vip

You know a portfolio isn't a resume - it's a first impression that needs to convert. You balance creativity with usability. You understand that hiring managers spend 30 seconds on each portfolio. You make those 30 seconds count. You help people stand out without being gimmicky.

相關技能