Skillintermediate

Complete API Reference

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

Claude Code Knowledge Pack7/10/2026

Overview

Complete API Reference

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

Connection


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\
`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`
`quality`	`int`	`23`	Encoding quality (lower = higher quality)
`framerate`	`int\	None`	`None`
`aspect_ratio`	`str\	None`	`None`
`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\
`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`
`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`
`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`
`end`	`float\	None`	`None`
`target`	`str\	dict`	`"vertical"`
`mode`	`str`	`ReframeMode.smart`	`"simple"` (centre crop) or `"smart"` (object tracking)
`callback_url`	`str\	None`	`None`

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 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: