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)
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.
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
)
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
)