Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

20.0 KB
Raw Blame

Complete API Reference

Reference material for the VideoDB skill. For usage guidance and workflow selection, start with ../SKILL.md.

Connection

import videodb

conn = videodb.connect(
    api_key="your-api-key",      # or set VIDEO_DB_API_KEY env var
    base_url=None,                # custom API endpoint (optional)
)

Returns: Connection object

Connection Methods

Method Returns Description
conn.get_collection(collection_id="default") Collection Get collection (default if no ID)
conn.get_collections() list[Collection] List all collections
conn.create_collection(name, description, is_public=False) Collection Create new collection
conn.update_collection(id, name, description) Collection Update a collection
conn.check_usage() dict Get account usage stats
conn.upload(source, media_type, name, ...) Video|Audio|Image Upload to default collection
conn.record_meeting(meeting_url, bot_name, ...) Meeting Record a meeting
conn.create_capture_session(...) CaptureSession Create a capture session (see capture-reference.md)
conn.youtube_search(query, result_threshold, duration) list[dict] Search YouTube
conn.transcode(source, callback_url, mode, ...) str Transcode video (returns job ID)
conn.get_transcode_details(job_id) dict Get transcode job status and details
conn.connect_websocket(collection_id) WebSocketConnection Connect to WebSocket (see capture-reference.md)

Transcode

Transcode a video from a URL with custom resolution, quality, and audio settings. Processing happens server-side — no local ffmpeg required.

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),
    audio_config=AudioConfig(mute=False),
)

transcode Parameters

Parameter Type Default Description
source str required URL of the video to transcode (preferably a downloadable URL)
callback_url str required URL to receive the callback when transcoding completes
mode TranscodeMode TranscodeMode.economy Transcoding speed: economy or lightning
video_config VideoConfig VideoConfig() Video encoding settings
audio_config AudioConfig AudioConfig() Audio encoding settings

Returns a job ID (str). Use conn.get_transcode_details(job_id) to check job status.

details = conn.get_transcode_details(job_id)

VideoConfig

from videodb import VideoConfig, ResizeMode

config = VideoConfig(
    resolution=720,              # Target resolution height (e.g. 480, 720, 1080)
    quality=23,                  # Encoding quality (lower = better, default 23)
    framerate=30,                # Target framerate
    aspect_ratio="16:9",         # Target aspect ratio
    resize_mode=ResizeMode.crop, # How to fit: crop, fit, or pad
)
Field Type Default Description
resolution int|None None Target resolution height in pixels
quality int 23 Encoding quality (lower = higher quality)
framerate int|None None Target framerate
aspect_ratio str|None None Target aspect ratio (e.g. "16:9", "9:16")
resize_mode str ResizeMode.crop Resize strategy: crop, fit, or pad

AudioConfig

from videodb import AudioConfig

config = AudioConfig(mute=False)
Field Type Default Description
mute bool False Mute the audio track

Collections

coll = conn.get_collection()

Collection Methods

Method Returns Description
coll.get_videos() list[Video] List all videos
coll.get_video(video_id) Video Get specific video
coll.get_audios() list[Audio] List all audios
coll.get_audio(audio_id) Audio Get specific audio
coll.get_images() list[Image] List all images
coll.get_image(image_id) Image Get specific image
coll.upload(url=None, file_path=None, media_type=None, name=None) Video|Audio|Image Upload media
coll.search(query, search_type, index_type, score_threshold, namespace, scene_index_id, ...) SearchResult Search across collection (semantic only; keyword and scene search raise NotImplementedError)
coll.generate_image(prompt, aspect_ratio="1:1") Image Generate image with AI
coll.generate_video(prompt, duration=5) Video Generate video with AI
coll.generate_music(prompt, duration=5) Audio Generate music with AI
coll.generate_sound_effect(prompt, duration=2) Audio Generate sound effect
coll.generate_voice(text, voice_name="Default") Audio Generate speech from text
coll.generate_text(prompt, model_name="basic", response_type="text") dict LLM text generation — access result via ["output"]
coll.dub_video(video_id, language_code) Video Dub video into another language
coll.record_meeting(meeting_url, bot_name, ...) Meeting Record a live meeting
coll.create_capture_session(...) CaptureSession Create a capture session (see capture-reference.md)
coll.get_capture_session(...) CaptureSession Retrieve capture session (see capture-reference.md)
coll.connect_rtstream(url, name, ...) RTStream Connect to a live stream (see rtstream-reference.md)
coll.make_public() None Make collection public
coll.make_private() None Make collection private
coll.delete_video(video_id) None Delete a video
coll.delete_audio(audio_id) None Delete an audio
coll.delete_image(image_id) None Delete an image
coll.delete() None Delete the collection

Upload Parameters

video = coll.upload(
    url=None,            # Remote URL (HTTP, YouTube)
    file_path=None,      # Local file path
    media_type=None,     # "video", "audio", or "image" (auto-detected if omitted)
    name=None,           # Custom name for the media
    description=None,    # Description
    callback_url=None,   # Webhook URL for async notification
)

Video Object

video = coll.get_video(video_id)

Video Properties

Property Type Description
video.id str Unique video ID
video.collection_id str Parent collection ID
video.name str Video name
video.description str Video description
video.length float Duration in seconds
video.stream_url str Default stream URL
video.player_url str Player embed URL
video.thumbnail_url str Thumbnail URL

Video Methods

Method Returns Description
video.generate_stream(timeline=None) str Generate stream URL (optional timeline of [(start, end)] tuples)
video.play() str Open stream in browser, returns player URL
video.index_spoken_words(language_code=None, force=False) None Index speech for search. Use force=True to skip if already indexed.
video.index_scenes(extraction_type, prompt, extraction_config, metadata, model_name, name, scenes, callback_url) str Index visual scenes (returns scene_index_id)
video.index_visuals(prompt, batch_config, ...) str Index visuals (returns scene_index_id)
video.index_audio(prompt, model_name, ...) str Index audio with LLM (returns scene_index_id)
video.get_transcript(start=None, end=None) list[dict] Get timestamped transcript
video.get_transcript_text(start=None, end=None) str Get full transcript text
video.generate_transcript(force=None) dict Generate transcript
video.translate_transcript(language, additional_notes) list[dict] Translate transcript
video.search(query, search_type, index_type, filter, **kwargs) SearchResult Search within video
video.add_subtitle(style=SubtitleStyle()) str Add subtitles (returns stream URL)
video.generate_thumbnail(time=None) str|Image Generate thumbnail
video.get_thumbnails() list[Image] Get all thumbnails
video.extract_scenes(extraction_type, extraction_config) SceneCollection Extract scenes
video.reframe(start, end, target, mode, callback_url) Video|None Reframe video aspect ratio
video.clip(prompt, content_type, model_name) str Generate clip from prompt (returns stream URL)
video.insert_video(video, timestamp) str Insert video at timestamp
video.download(name=None) dict Download the video
video.delete() None Delete the video

Reframe

Convert a video to a different aspect ratio with optional smart object tracking. Processing is server-side.

Warning: Reframe is a slow server-side operation. It can take several minutes for long videos and may time out. Always use start/end to limit the segment, or pass callback_url for async processing.

from videodb import ReframeMode

# Always prefer short segments to avoid timeouts:
reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)

# Async reframe for full-length videos (returns None, result via webhook):
video.reframe(target="vertical", callback_url="https://example.com/webhook")

# Custom dimensions
reframed = video.reframe(start=0, end=60, target={"width": 1080, "height": 1080})

reframe Parameters

Parameter Type Default Description
start float|None None Start time in seconds (None = beginning)
end float|None None End time in seconds (None = end of video)
target str|dict "vertical" Preset string ("vertical", "square", "landscape") or {"width": int, "height": int}
mode str ReframeMode.smart "simple" (centre crop) or "smart" (object tracking)
callback_url str|None None Webhook URL for async notification

Returns a Video object when no callback_url is provided, None otherwise.

Audio Object

audio = coll.get_audio(audio_id)

Audio Properties

Property Type Description
audio.id str Unique audio ID
audio.collection_id str Parent collection ID
audio.name str Audio name
audio.length float Duration in seconds

Audio Methods

Method Returns Description
audio.generate_url() str Generate signed URL for playback
audio.get_transcript(start=None, end=None) list[dict] Get timestamped transcript
audio.get_transcript_text(start=None, end=None) str Get full transcript text
audio.generate_transcript(force=None) dict Generate transcript
audio.delete() None Delete the audio

Image Object

image = coll.get_image(image_id)

Image Properties

Property Type Description
image.id str Unique image ID
image.collection_id str Parent collection ID
image.name str Image name
image.url str|None Image URL (may be None for generated images — use generate_url() instead)

Image Methods

Method Returns Description
image.generate_url() str Generate signed URL
image.delete() None Delete the image

Timeline & Editor

Timeline

from videodb.timeline import Timeline

timeline = Timeline(conn)
Method Returns Description
timeline.add_inline(asset) None Add VideoAsset sequentially on main track
timeline.add_overlay(start, asset) None Overlay AudioAsset, ImageAsset, or TextAsset at timestamp
timeline.generate_stream() str Compile and get stream URL

Asset Types

VideoAsset

from videodb.asset import VideoAsset

asset = VideoAsset(
    asset_id=video.id,
    start=0,              # trim start (seconds)
    end=None,             # trim end (seconds, None = full)
)

AudioAsset

from videodb.asset import AudioAsset

asset = AudioAsset(
    asset_id=audio.id,
    start=0,
    end=None,
    disable_other_tracks=True,   # mute original audio when True
    fade_in_duration=0,          # seconds (max 5)
    fade_out_duration=0,         # seconds (max 5)
)

ImageAsset

from videodb.asset import ImageAsset

asset = ImageAsset(
    asset_id=image.id,
    duration=None,        # display duration (seconds)
    width=100,            # display width
    height=100,           # display height
    x=80,                 # horizontal position (px from left)
    y=20,                 # vertical position (px from top)
)

TextAsset

from videodb.asset import TextAsset, TextStyle

asset = TextAsset(
    text="Hello World",
    duration=5,
    style=TextStyle(
        fontsize=24,
        fontcolor="black",
        boxcolor="white",       # background box colour
        alpha=1.0,
        font="Sans",
        text_align="T",         # text alignment within box
    ),
)

CaptionAsset (Editor API)

CaptionAsset belongs to the Editor API, which has its own Timeline, Track, and Clip system:

from videodb.editor import CaptionAsset, FontStyling

asset = CaptionAsset(
    src="auto",                    # "auto" or base64 ASS string
    font=FontStyling(name="Clear Sans", size=30),
    primary_color="&H00FFFFFF",
)

See editor.md for full CaptionAsset usage with the Editor API.

Video Search Parameters

results = video.search(
    query="your query",
    search_type=SearchType.semantic,       # semantic, keyword, or scene
    index_type=IndexType.spoken_word,      # spoken_word or scene
    result_threshold=None,                 # max number of results
    score_threshold=None,                  # minimum relevance score
    dynamic_score_percentage=None,         # percentage of dynamic score
    scene_index_id=None,                   # target a specific scene index (pass via **kwargs)
    filter=[],                             # metadata filters for scene search
)

Note: filter is an explicit named parameter in video.search(). scene_index_id is passed through **kwargs to the API.

Important: video.search() raises InvalidRequestError with message "No results found" when there are no matches. Always wrap search calls in try/except. For scene search, use score_threshold=0.3 or higher to filter low-relevance noise.

For scene search, use search_type=SearchType.semantic with index_type=IndexType.scene. Pass scene_index_id when targeting a specific scene index. See search.md for details.

SearchResult Object

results = video.search("query", search_type=SearchType.semantic)
Method Returns Description
results.get_shots() list[Shot] Get list of matching segments
results.compile() str Compile all shots into a stream URL
results.play() str Open compiled stream in browser

Shot Properties

Property Type Description
shot.video_id str Source video ID
shot.video_length float Source video duration
shot.video_title str Source video title
shot.start float Start time (seconds)
shot.end float End time (seconds)
shot.text str Matched text content
shot.search_score float Search relevance score
Method Returns Description
shot.generate_stream() str Stream this specific shot
shot.play() str Open shot stream in browser

Meeting Object

meeting = coll.record_meeting(
    meeting_url="https://meet.google.com/...",
    bot_name="Bot",
    callback_url=None,          # Webhook URL for status updates
    callback_data=None,         # Optional dict passed through to callbacks
    time_zone="UTC",            # Time zone for the meeting
)

Meeting Properties

Property Type Description
meeting.id str Unique meeting ID
meeting.collection_id str Parent collection ID
meeting.status str Current status
meeting.video_id str Recorded video ID (after completion)
meeting.bot_name str Bot name
meeting.meeting_title str Meeting title
meeting.meeting_url str Meeting URL
meeting.speaker_timeline dict Speaker timeline data
meeting.is_active bool True if initializing or processing
meeting.is_completed bool True if done

Meeting Methods

Method Returns Description
meeting.refresh() Meeting Refresh data from server
meeting.wait_for_status(target_status, timeout=14400, interval=120) bool Poll until status reached

RTStream & Capture

For RTStream (live ingestion, indexing, transcription), see rtstream-reference.md.

For capture sessions (desktop recording, CaptureClient, channels), see capture-reference.md.

Enums & Constants

SearchType

from videodb import SearchType

SearchType.semantic    # Natural language semantic search
SearchType.keyword     # Exact keyword matching
SearchType.scene       # Visual scene search (may require paid plan)
SearchType.llm         # LLM-powered search

SceneExtractionType

from videodb import SceneExtractionType

SceneExtractionType.shot_based   # Automatic shot boundary detection
SceneExtractionType.time_based   # Fixed time interval extraction
SceneExtractionType.transcript   # Transcript-based scene extraction

SubtitleStyle

from videodb import SubtitleStyle

style = SubtitleStyle(
    font_name="Arial",
    font_size=18,
    primary_colour="&H00FFFFFF",
    bold=False,
    # ... see SubtitleStyle for all options
)
video.add_subtitle(style=style)

SubtitleAlignment & SubtitleBorderStyle

from videodb import SubtitleAlignment, SubtitleBorderStyle

TextStyle

from videodb import TextStyle
# or: from videodb.asset import TextStyle

style = TextStyle(
    fontsize=24,
    fontcolor="black",
    boxcolor="white",
    font="Sans",
    text_align="T",
    alpha=1.0,
)

Other Constants

from videodb import (
    IndexType,          # spoken_word, scene
    MediaType,          # video, audio, image
    Segmenter,          # word, sentence, time
    SegmentationType,   # sentence, llm
    TranscodeMode,      # economy, lightning
    ResizeMode,         # crop, fit, pad
    ReframeMode,        # simple, smart
    RTStreamChannelType,
)

Exceptions

from videodb.exceptions import (
    AuthenticationError,     # Invalid or missing API key
    InvalidRequestError,     # Bad parameters or malformed request
    RequestTimeoutError,     # Request timed out
    SearchError,             # Search operation failure (e.g. not indexed)
    VideodbError,            # Base exception for all VideoDB errors
)
Exception Common Cause
AuthenticationError Missing or invalid VIDEO_DB_API_KEY
InvalidRequestError Invalid URL, unsupported format, bad parameters
RequestTimeoutError Server took too long to respond
SearchError Searching before indexing, invalid search type
VideodbError Server errors, network issues, generic failures