VideoDB Python SDK

https://github.com/video-db/videodb-python
Admin
The VideoDB Python SDK provides an interface to the VideoDB serverless database, enabling management...
Tokens:17,224
Snippets:165
Trust Score:9.3
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install VideoDB Capture Dependencies

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Install the necessary dependencies for using the VideoDB capture functionality on your desktop.

```bash
pip install 'videodb[capture]'
```

--------------------------------

### Install VideoDB Python SDK

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Install the SDK using pip. Requires Python 3.8+ and specific dependency versions.

```bash
pip install videodb
```

--------------------------------

### Desktop Client: Request Permissions and Start Capture

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Use the CaptureClient to request necessary permissions (microphone, screen) and start a capture session on the desktop. Configure channels for recording.

```python
client = CaptureClient(session_token=token)

await client.request_permission("microphone")
await client.request_permission("screen")

await client.start_capture_session(
    session_id=cap.id,
    channels=[
        {"type": "mic", "name": "mic:default"},
        {"type": "system_audio", "name": "system_audio:default"},
        {"type": "display", "name": "display:1"},
    ]
)
```

--------------------------------

### Realtime Video Editor Setup

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Initialize the VideoDB connection and upload assets for use in the realtime video editor.

```python
from videodb import connect
from videodb.editor import Timeline, Track, Clip, VideoAsset, AudioAsset

conn = connect(api_key="YOUR_API_KEY")
video = conn.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")
audio = conn.upload(file_path="./music.mp3")
```

--------------------------------

### Create and Manage Capture Sessions

Source: https://context7.com/video-db/videodb-python/llms.txt

Backend and desktop client code for creating, starting, and stopping screen recording sessions. Requires API key for backend operations and a client token for the desktop app.

```python
import videodb
from videodb.capture import CaptureClient

conn = videodb.connect(api_key="YOUR_API_KEY")
coll = conn.get_collection()

# Backend: Create capture session
session = coll.create_capture_session(
    end_user_id="user_12345",
    callback_url="https://myapp.com/webhook/capture-done",
    metadata={"project": "demo-recording"}
)
print(f"Session ID: {session.id}")

# Generate client token for desktop app
token = conn.generate_client_token(expires_in=86400)  # 24 hours

# Desktop client: Initialize capture
client = CaptureClient(session_token=token)

# Request permissions
await client.request_permission("microphone")
await client.request_permission("screen")

# Start capture session
await client.start_capture_session(
    session_id=session.id,
    channels=[
        {"type": "mic", "name": "mic:default"},
        {"type": "system_audio", "name": "system_audio:default"},
        {"type": "display", "name": "display:1"}
    ]
)

# ... recording happens ...

# Stop capture
await client.stop_capture_session()

# Backend: Get session and export
session = coll.get_capture_session(session.id)
export_result = session.export()
print(f"Exported video: {export_result}")

# List all capture sessions
sessions = coll.list_capture_sessions(status="completed")
for s in sessions:
    print(f"Session {s.id}: {s.status}")
```

--------------------------------

### Check Usage and Get Invoices with Python

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Monitor your VideoDB usage and retrieve billing information using `check_usage` and `get_invoices` methods.

```python
# Check usage
usage = conn.check_usage()

# Get invoices
invoices = conn.get_invoices()
```

--------------------------------

### Connect to Real-Time Stream

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Connect to a live video stream using its URL and start or stop processing. Requires SceneExtractionType for indexing.

```python
from videodb import SceneExtractionType

rtstream = coll.connect_rtstream(
    url="rtsp://example.com/stream",
    name="Live Stream"
)

rtstream.stop()
rtstream.start()
```

--------------------------------

### Start and Manage Meeting Recording

Source: https://context7.com/video-db/videodb-python/llms.txt

Initiates a meeting recording, checks its status, and waits for completion. Requires a meeting URL and callback URL for notifications.

```python
import videodb

conn = videodb.connect(api_key="YOUR_API_KEY")
coll = conn.get_collection()

# Start meeting recording
meeting = coll.record_meeting(
    meeting_url="https://meet.google.com/xxx-yyyy-zzz",
    bot_name="VideoDB Recorder",
    meeting_title="Weekly Team Standup",
    callback_url="https://myapp.com/webhook/meeting-done",
    time_zone="America/New_York"
)
print(f"Meeting ID: {meeting.id}, Status: {meeting.status}")
```

```python
# Check meeting status
meeting.refresh()
print(f"Current status: {meeting.status}")
```

```python
# Wait for meeting to complete (polls periodically)
completed = meeting.wait_for_status(
    target_status="done",
    timeout=14400,  # 4 hours max
    interval=120    # Check every 2 minutes
)

if completed and meeting.is_completed:
    # Access recorded video
    video = coll.get_video(meeting.video_id)
    print(f"Recording: {video.name}, Duration: {video.length}s")

    # Generate transcript
    video.generate_transcript()
    transcript = video.get_transcript_text()

    # Access speaker timeline
    if meeting.speaker_timeline:
        for speaker in meeting.speaker_timeline:
            print(f"Speaker {speaker['name']}: {speaker['start']}s - {speaker['end']}s")
```

--------------------------------

### Index Scenes from Real-Time Stream

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Index scenes from a live stream based on time or frame count, with an optional prompt for scene description. Supports starting and stopping the indexing process.

```python
scene_index = rtstream.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 2, "frame_count": 5},
    prompt="Describe the scene"
)

scene_index.stop()
scene_index.start()
```

--------------------------------

### Get Scenes and Create Alerts

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Retrieve indexed scenes from a stream and create alerts for specific events, with options to enable, disable, and set callback URLs.

```python
scenes = scene_index.get_scenes(page=1, page_size=100)

alert_id = scene_index.create_alert(
    event_id=event_id,
    callback_url="https://example.com/callback"
)

scene_index.disable_alert(alert_id)
scene_index.enable_alert(alert_id)
```

--------------------------------

### Record Virtual Meeting

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Start recording a virtual meeting by providing the meeting URL, a bot name, meeting title, and a callback URL for status updates.

```python
meeting = conn.record_meeting(
    meeting_url="https://meet.google.com/xxx-yyyy-zzz",
    bot_name="Recorder Bot",
    meeting_title="Team Meeting",
    callback_url="https://example.com/callback"
)
```

--------------------------------

### Get Meeting Details from Video

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Retrieve meeting details, including the video ID, after a recording is completed. It's also possible to get meeting information directly from a video object.

```python
if meeting.is_completed:
    video_id = meeting.video_id
    video = coll.get_video(video_id)
    
meeting_info = video.get_meeting()
```

--------------------------------

### Retrieve Video Transcript

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Get the video transcript with timestamps, as plain text, or for a specific time range.

```python
transcript = video.get_transcript()
```

```python
text = video.get_transcript_text()
```

```python
transcript = video.get_transcript(start=10, end=60)
```

--------------------------------

### Generate Stream with Player Metadata

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Generate a stream URL from a real-time stream, specifying start and end times, and configuring player metadata like title, description, and slug.

```python
stream_url = rtstream.generate_stream(
    start=1711000000,
    end=1711003600,
    player_config={
        "title": "Live Feed",
        "description": "Stream recording",
        "slug": "live-feed"
    }
)
```

--------------------------------

### Real-Time Video Editor (Timeline)

Source: https://context7.com/video-db/videodb-python/llms.txt

Programmatically build multi-track video compositions using assets, clips, tracks, and timelines. Requires media assets to be uploaded first.

```python
import videodb
from videodb.editor import (
    Timeline, Track, Clip,
    VideoAsset, AudioAsset, ImageAsset, TextAsset, CaptionAsset,
    Font, Background, Alignment, Transition, Position, Fit, Filter, Offset
)

conn = videodb.connect(api_key="YOUR_API_KEY")
coll = conn.get_collection()

# Upload media assets
video = coll.upload(url="https://example.com/video.mp4")
audio = coll.upload(file_path="./background_music.mp3")
logo = coll.upload(file_path="./logo.png")
```

```python
timeline = Timeline(conn)
timeline.background = "#000000"
timeline.resolution = "1920x1080"
```

```python
video_track = Track(z_index=0)
video_asset = VideoAsset(id=video.id, start=10, volume=0.8)
video_clip = Clip(
    asset=video_asset,
    duration=60,
    transition=Transition(in_="fade", out="fade", duration=1),
    fit=Fit.cover
)
video_track.add_clip(0, video_clip)
```

```python
audio_track = Track(z_index=1)
audio_asset = AudioAsset(id=audio.id, start=0, volume=0.3)
audio_clip = Clip(asset=audio_asset, duration=60)
audio_track.add_clip(0, audio_clip)
```

```python
overlay_track = Track(z_index=2)
logo_asset = ImageAsset(id=logo.id)
logo_clip = Clip(
    asset=logo_asset,
    duration=60,
    position=Position.bottom_right,
    scale=0.15,
    opacity=0.8,
    offset=Offset(x=-0.02, y=-0.02)
)
overlay_track.add_clip(0, logo_clip)
```

```python
text_track = Track(z_index=3)
text_asset = TextAsset(
    text="Welcome to Our Channel",
    font=Font(family="Arial", size=48, color="#FFFFFF"),
    background=Background(color="#000000", opacity=0.7, width=500, height=80)
)
text_clip = Clip(
    asset=text_asset,
    duration=5,
    position=Position.center,
    transition=Transition(in_="fade", out="fade", duration=0.5)
)
text_track.add_clip(2, text_clip)  # Start at 2 seconds
```

```python
caption_track = Track(z_index=4)
caption_asset = CaptionAsset(src="auto")
caption_clip = Clip(asset=caption_asset, duration=60)
caption_track.add_clip(0, caption_clip)
```

```python
timeline.add_track(video_track)
timeline.add_track(audio_track)
timeline.add_track(overlay_track)
timeline.add_track(text_track)
timeline.add_track(caption_track)
```

```python
stream_url = timeline.generate_stream()
print(f"Composed video: {stream_url}")
```

```python
embed_code = timeline.get_embed_code(width="100%", height=720)
```

--------------------------------

### Capture Sessions (Desktop Recording)

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Record screen, microphone, and system audio from desktop applications.

```APIDOC
## Capture Sessions (Desktop Recording)

### Description
Record screen, microphone, and system audio from desktop applications using native capture binaries. This involves creating a capture session on the backend, generating a client token, and using the CaptureClient on the desktop to manage the recording.

### Method
N/A (Code Example)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **session_id** (string) - The ID of the capture session.

#### Query Parameters
- **end_user_id** (string) - The ID of the end user for the capture session.
- **callback_url** (string) - The URL to send notifications to upon session completion.
- **expires_in** (integer) - The expiration time for the client token in seconds.
- **type** (string) - The type of channel to record (e.g., `mic`, `system_audio`, `display`).
- **name** (string) - The name of the channel.

### Request Example
```bash
# Install capture dependencies
pip install 'videodb[capture]'
```

```python
from videodb.capture import CaptureClient

# Backend: Create a capture session
cap = coll.create_capture_session(
    end_user_id="user_abc",
    callback_url="https://example.com/webhook"
)

# Generate a client token for secure desktop auth
token = conn.generate_client_token(expires_in=86400)

# Desktop client: Start capture
client = CaptureClient(session_token=token)

# Request permissions
await client.request_permission("microphone")
await client.request_permission("screen")

# Configure channels and start recording
await client.start_capture_session(
    session_id=cap.id,
    channels=[
        {"type": "mic", "name": "mic:default"},
        {"type": "system_audio", "name": "system_audio:default"},
        {"type": "display", "name": "display:1"},
    ]
)

# Stop capture
await client.stop_capture_session()

# Get session details and export
cap = coll.get_capture_session(cap.id)
export_result = cap.export()

# List all capture sessions
sessions = coll.list_capture_sessions()
```

### Response
#### Success Response (200)
- **cap** (object) - Represents a capture session.
- **token** (string) - The client token for desktop authentication.
- **export_result** (object) - The result of the export operation.
- **sessions** (list) - A list of all capture sessions.
```

--------------------------------

### Create Capture Session

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Create a capture session on the backend for desktop recording, providing an end-user ID and a callback URL for notifications.

```python
from videodb.capture import CaptureClient

cap = coll.create_capture_session(
    end_user_id="user_abc",
    callback_url="https://example.com/webhook"
)
```

--------------------------------

### Create and List Collections

Source: https://context7.com/video-db/videodb-python/llms.txt

Connect to VideoDB, create a new collection with specified name, description, and public status, and list all existing collections. Requires an API key.

```python
import videodb

conn = videodb.connect(api_key="YOUR_API_KEY")

# Get default collection
coll = conn.get_collection()

# Create new collection
coll = conn.create_collection(
    name="Training Videos",
    description="Employee training content",
    is_public=False
)
print(f"Created collection: {coll.id}")

# List all collections
collections = conn.get_collections()
for c in collections:
    print(f"{c.name} (ID: {c.id}, Public: {c.is_public})")
```

--------------------------------

### Establishing a Connection

Source: https://context7.com/video-db/videodb-python/llms.txt

Learn how to establish a connection to the VideoDB API using your API key or session token. This is the initial step for all SDK operations.

```APIDOC
## Establishing a Connection

The `connect()` function creates a connection to the VideoDB API using an API key or session token. This is the entry point for all SDK operations.

### Method
`videodb.connect()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import videodb

# Connect with API key directly
conn = videodb.connect(api_key="YOUR_API_KEY")

# Or use environment variable VIDEO_DB_API_KEY
import os
os.environ["VIDEO_DB_API_KEY"] = "your-api-key"
conn = videodb.connect()

# Connect with custom base URL and logging
import logging
conn = videodb.connect(
    api_key="YOUR_API_KEY",
    base_url="https://api.videodb.io",
    log_level=logging.DEBUG
)

# Access default collection
coll = conn.get_collection()
print(f"Connected to collection: {coll.id}")
```

### Response
#### Success Response (200)
- **conn** (object) - A connection object to interact with the VideoDB API.
- **coll** (object) - A collection object representing the default collection.
```

--------------------------------

### Generate Various Media Types with Python

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Use the `generate_image`, `generate_music`, `generate_sound_effect`, `generate_voice`, `generate_video`, and `generate_text` methods for AI-powered media creation. Specify prompts, durations, and model names as needed.

```python
# Generate image
image = coll.generate_image(
    prompt="A beautiful sunset over mountains",
    aspect_ratio="16:9"
)

# Generate music
audio = coll.generate_music(
    prompt="Upbeat electronic music",
    duration=30
)

# Generate sound effects
audio = coll.generate_sound_effect(
    prompt="Door closing sound",
    duration=2
)

# Generate voice from text
audio = coll.generate_voice(
    text="Hello, welcome to VideoDB",
    voice_name="Default"
)

# Generate video
video = coll.generate_video(
    prompt="A cat playing with a ball",
    duration=5
)

# Generate text using LLM
response = coll.generate_text(
    prompt="Summarize this content",
    model_name="pro",  # basic, pro, or ultra
    response_type="text"  # text or json
)
```

--------------------------------

### Video Composition

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Demonstrates how to compose video and audio tracks into a timeline and generate a streamable output.

```APIDOC
## Video Composition

### Description
This section shows how to create a video timeline by adding video and audio clips, and then generating a streamable output.

### Method
N/A (Code Example)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# Create timeline
timeline = Timeline(conn)

# Video track
video_track = Track()
video_asset = VideoAsset(id=video.id, start=10)
video_clip = Clip(asset=video_asset, duration=30)
video_track.add_clip(0, video_clip)

# Audio track
audio_track = Track()
audio_asset = AudioAsset(id=audio.id, start=0, volume=0.3)
audio_clip = Clip(asset=audio_asset, duration=30)
audio_track.add_clip(0, audio_clip)

# Compose and render
timeline.add_track(video_track)
timeline.add_track(audio_track)
stream_url = timeline.generate_stream()
```

### Response
#### Success Response (200)
- **stream_url** (string) - The URL of the generated stream.
```

--------------------------------

### Style Text Overlays with Python

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Configure text overlay styles using the `TextStyle` class. Set font size, color, font family, and background box properties for visual emphasis.

```python
from videodb import TextStyle

style = TextStyle(
    fontsize=24,
    fontcolor="black",
    font="Sans",
    box=True,
    boxcolor="white",
    boxborderw="10"
)
```

--------------------------------

### Handle Authentication Errors

Source: https://context7.com/video-db/videodb-python/llms.txt

Demonstrates how to catch and handle `AuthenticationError` when connecting to VideoDB with an invalid API key.

```python
import videodb
from videodb.exceptions import (
    VideodbError,
    AuthenticationError,
    InvalidRequestError,
    SearchError
)

# Handle authentication errors
try:
    conn = videodb.connect(api_key="invalid_key")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
    # Prompt user for valid API key
```

--------------------------------

### Generate Video from Prompt

Source: https://context7.com/video-db/videodb-python/llms.txt

Generates a video clip based on a text prompt, specifying the desired content and duration. Enables programmatic video creation.

```python
video = coll.generate_video(
    prompt="A cat playing with a ball of yarn in a sunny room",
    duration=5
)
print(f"Generated video: {video.stream_url}")
```

--------------------------------

### Upload Media to VideoDB

Source: https://context7.com/video-db/videodb-python/llms.txt

Handles uploads of video, audio, and image files from URLs (including YouTube) or local paths. Supports specifying names, descriptions, and asynchronous callbacks.

```python
import videodb

conn = videodb.connect(api_key="YOUR_API_KEY")
coll = conn.get_collection()

# Upload from YouTube URL
video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")
print(f"Uploaded: {video.name}, Duration: {video.length}s")

# Upload from public URL
video = coll.upload(
    url="https://example.com/video.mp4",
    name="My Video",
    description="Video description"
)

# Upload from local file
video = coll.upload(file_path="./my_video.mp4")

# Upload audio file
audio = coll.upload(file_path="./background_music.mp3")
print(f"Audio ID: {audio.id}, Length: {audio.length}s")

# Upload image
image = coll.upload(file_path="./thumbnail.png")
print(f"Image ID: {image.id}")

# Upload with async callback
video = coll.upload(
    url="https://example.com/large_video.mp4",
    callback_url="https://myapp.com/webhook/upload-complete"
)
```

--------------------------------

### Connect to WebSocket for Real-Time Events

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Establish a WebSocket connection to receive real-time transcript and indexing events. The connection ID is printed upon successful connection.

```python
ws = conn.connect_websocket()
await ws.connect()
print(f"Connection ID: {ws.connection_id}")

async for event in ws.receive():
    print(event)

await ws.close()
```

--------------------------------

### Describe and Index Scenes

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Describe individual scenes using a custom model and index scenes for semantic search.

```python
scenes = video.get_scene_index(scene_collection.scene_index_id)
scene = scenes[0]
scene.describe(
    prompt="Describe this scene",
    model_config={"model_name": "pro", "temperature": 0.5}
)
```

```python
scene_index_id = video.index_scenes(
    extraction_type=SceneExtractionType.shot_based,
    prompt="Describe the visual content of this scene"
)
```

--------------------------------

### Create Video Timeline

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Compose video and audio tracks to create a timeline and generate a stream URL. Supports various asset types like VideoAsset, AudioAsset, ImageAsset, TextAsset, and CaptionAsset.

```python
timeline = Timeline(conn)

video_track = Track()
video_asset = VideoAsset(id=video.id, start=10)
video_clip = Clip(asset=video_asset, duration=30)
video_track.add_clip(0, video_clip)

audio_track = Track()
audio_asset = AudioAsset(id=audio.id, start=0, volume=0.3)
audio_clip = Clip(asset=audio_asset, duration=30)
audio_track.add_clip(0, audio_clip)

timeline.add_track(video_track)
timeline.add_track(audio_track)
stream_url = timeline.generate_stream()
```

--------------------------------

### Real-Time Stream Processing (RTStream)

Source: https://context7.com/video-db/videodb-python/llms.txt

Connect to live video streams for real-time scene indexing, transcription, and event-based alerting. Requires a valid RTSP URL.

```python
import videodb
from videodb import SceneExtractionType

conn = videodb.connect(api_key="YOUR_API_KEY")
coll = conn.get_collection()
```

```python
rtstream = coll.connect_rtstream(
    url="rtsp://example.com/live/stream",
    name="Security Camera Feed",
    sample_rate=30,
    store=True  # Enable recording storage
)
print(f"RTStream ID: {rtstream.id}, Status: {rtstream.status}")
```

```python
rtstream.start()
```

```python
scene_index = rtstream.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 5, "frame_count": 3},
    prompt="Describe any people, vehicles, or unusual activity"
)
```

```python
event_id = conn.create_event(
    event_prompt="Person entering restricted area",
    label="security_alert"
)
```

```python
alert_id = scene_index.create_alert(
    event_id=event_id,
    callback_url="https://myapp.com/webhook/security-alert"
)
```

```python
scenes_data = scene_index.get_scenes(page=1, page_size=50)
for scene in scenes_data["scenes"]:
    print(f"Scene at {scene['start']}: {scene['description']}")
```

```python
results = rtstream.search("person with red jacket")
for shot in results.get_shots():
    print(f"Found at {shot.start} - {shot.end}: {shot.text}")
```

```python
stream_url = rtstream.generate_stream(
    start=1711000000,  # Unix timestamp
    end=1711003600,
    player_config={
        "title": "Security Recording",
        "description": "Camera 1 footage"
    }
)
```

```python
scene_index.stop()
rtstream.stop()
```

--------------------------------

### Manage Video Collections

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Create, retrieve, update, and delete video collections. Upload videos and search within collections.

```python
# Get default collection
coll = conn.get_collection()
```

```python
# Create new collection
coll = conn.create_collection(
    name="My Collection",
    description="Collection description",
    is_public=False
)
```

```python
# List all collections
collections = conn.get_collections()
```

```python
# Update collection
coll = conn.update_collection(
    id="collection_id",
    name="Updated Name",
    description="Updated description"
)
```

```python
# Upload to collection
video = coll.upload(url="https://example.com/video.mp4")
```

```python
# Get videos in collection
videos = coll.get_videos()
video = coll.get_video(video_id)
```

```python
# Search across collection
results = coll.search(query="specific content")
```

```python
# Search by title
results = coll.search_title("video title")
```

```python
# Make collection public/private
coll.make_public()
coll.make_private()
```

```python
# Delete collection
coll.delete()
```

--------------------------------

### Establish Connection to VideoDB

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Connect to VideoDB using an API key. The API key can be provided directly or set as an environment variable.

```python
import videodb

# Connect using API key
conn = videodb.connect(api_key="YOUR_API_KEY")

# Or set environment variable VIDEO_DB_API_KEY
# conn = videodb.connect()
```

--------------------------------

### Transcode Video with Python SDK

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Initiate a video transcoding job using the `transcode` method. Specify the source URL, callback URL, transcode mode, and detailed video and audio configurations.

```python
from videodb import TranscodeMode, VideoConfig, AudioConfig

# Start transcoding job
job_id = conn.transcode(
    source="https://example.com/video.mp4",
    callback_url="https://example.com/callback",
    mode=TranscodeMode.economy,
    video_config=VideoConfig(resolution=1080, quality=23),
    audio_config=AudioConfig(mute=False)
)

# Check transcode status
status = conn.get_transcode_details(job_id)
```

--------------------------------

### Compile and Play Search Results

Source: https://context7.com/video-db/videodb-python/llms.txt

Compile search results into a playable stream URL or play them directly. Search for videos by title.

```python
stream_url = results.compile()
print(f"Watch results: {stream_url}")

# Play results directly
results.play()

# Search by video title
title_results = coll.search_title("team meeting")
for result in title_results:
    print(f"Video: {result['video'].name}")
```

--------------------------------

### Index and Search Scenes

Source: https://context7.com/video-db/videodb-python/llms.txt

Index scenes for semantic search using a specified prompt and model. Search indexed scenes with a query. Requires a video object.

```python
import videodb
from videodb import SceneExtractionType, SearchType, IndexType

conn = videodb.connect(api_key="YOUR_API_KEY")
video = conn.get_collection().get_video("m-video-id")

# Index scenes for semantic search
scene_index_id = video.index_scenes(
    extraction_type=SceneExtractionType.shot_based,
    prompt="Describe the visual content focusing on people and actions",
    model_name="pro"
)

# Search indexed scenes
results = video.search(
    query="outdoor landscape with mountains",
    search_type=SearchType.scene,
    index_type=IndexType.scene
)

# List all scene indexes
indexes = video.list_scene_index()
for idx in indexes:
    print(f"Index: {idx['name']} (ID: {idx['scene_index_id']})")

# Delete scene collection when done
video.delete_scene_collection(scene_collection.id)
```

--------------------------------

### Uploading Media

Source: https://context7.com/video-db/videodb-python/llms.txt

This section covers how to upload videos, audio files, and images from URLs or local file paths using the `upload()` method.

```APIDOC
## Uploading Media

The `upload()` method handles video, audio, and image uploads from URLs (including YouTube) or local files. Returns a `Video`, `Audio`, or `Image` object based on media type.

### Method
`collection.upload()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string) - URL of the media to upload (e.g., YouTube URL, public URL).
- **file_path** (string) - Local file path of the media to upload.
- **name** (string) - Optional. A custom name for the uploaded media.
- **description** (string) - Optional. A description for the uploaded media.
- **callback_url** (string) - Optional. A URL to receive a webhook notification when the upload is complete.

### Request Example
```python
import videodb

conn = videodb.connect(api_key="YOUR_API_KEY")
coll = conn.get_collection()

# Upload from YouTube URL
video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")
print(f"Uploaded: {video.name}, Duration: {video.length}s")

# Upload from public URL
video = coll.upload(
    url="https://example.com/video.mp4",
    name="My Video",
    description="Video description"
)

# Upload from local file
video = coll.upload(file_path="./my_video.mp4")

# Upload audio file
audio = coll.upload(file_path="./background_music.mp3")
print(f"Audio ID: {audio.id}, Length: {audio.length}s")

# Upload image
image = coll.upload(file_path="./thumbnail.png")
print(f"Image ID: {image.id}")

# Upload with async callback
video = coll.upload(
    url="https://example.com/large_video.mp4",
    callback_url="https://myapp.com/webhook/upload-complete"
)
```

### Response
#### Success Response (200)
- **Video/Audio/Image object** - An object representing the uploaded media, containing properties like `id`, `name`, `length`, etc.
```

--------------------------------

### Connect to WebSocket and Stream Events

Source: https://context7.com/video-db/videodb-python/llms.txt

Establishes a WebSocket connection to receive real-time events such as transcript updates and scene indexing. Requires an API key for authentication.

```python
import videodb
import asyncio

conn = videodb.connect(api_key="YOUR_API_KEY")

async def listen_for_events():
    # Connect to WebSocket
    ws = conn.connect_websocket()
    await ws.connect()
    print(f"Connected with ID: {ws.connection_id}")

    try:
        # Stream events
        async for event in ws.receive():
            print(f"Event received: {event}")

            if event.get("type") == "transcript_update":
                print(f"New transcript: {event['text']}")
            elif event.get("type") == "scene_indexed":
                print(f"Scene indexed: {event['scene_id']}")
    finally:
        await ws.close()

# Run event listener
asyncio.run(listen_for_events())
```

--------------------------------

### Generate Video Thumbnails

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Generate a default thumbnail, a thumbnail at a specific timestamp, or retrieve all thumbnails for a video.

```python
# Get default thumbnail
thumbnail_url = video.generate_thumbnail()
```

```python
# Generate thumbnail at specific timestamp
thumbnail_image = video.generate_thumbnail(time=30.5)
```

```python
# Get all thumbnails
thumbnails = video.get_thumbnails()
```

--------------------------------

### Download Video

Source: https://context7.com/video-db/videodb-python/llms.txt

Download a video backup with a specified name. Requires a video object.

```python
import videodb

conn = videodb.connect(api_key="YOUR_API_KEY")
video = conn.get_collection().get_video("m-video-id")

# Download video
download_info = video.download(name="my_video_backup")
print(f"Download: {download_info}")
```

--------------------------------

### Download Compiled Stream with Python

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Download a compiled stream using the `download` method, providing the stream link and a desired name for the downloaded file.

```python
# Download compiled stream
download_info = conn.download(
    stream_link="https://stream.videodb.io/...",
    name="my_compilation"
)
```

--------------------------------

### Export Recording as Video Asset

Source: https://context7.com/video-db/videodb-python/llms.txt

Exports a recording as a video asset. Requires a valid recording name.

```python
export_result = rtstream.export(name="Security_Recording_2024")
print(f"Exported video ID: {export_result.video_id}")
```

--------------------------------

### Generate Client Token for Capture

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Generate a secure client token for authentication with the desktop capture client. The token has a specified expiration time in seconds.

```python
token = conn.generate_client_token(expires_in=86400)
```

--------------------------------

### Access and Describe Scenes

Source: https://context7.com/video-db/videodb-python/llms.txt

Access individual scenes from a scene collection and describe a specific scene using an AI model. Requires a scene collection object.

```python
# Access individual scenes
for scene in scene_collection.scenes[:3]:
    print(f"Scene {scene.id}: {scene.start}s - {scene.end}s")
    for frame in scene.frames:
        print(f"  Frame at {frame.frame_time}s: {frame.url}")

# Describe a specific scene with AI
scene = scene_collection.scenes[0]
description = scene.describe(
    prompt="Describe what's happening in this scene",
    model_config={"model_name": "pro", "temperature": 0.5}
)
print(f"Scene description: {description}")
```

--------------------------------

### Generate Background Music

Source: https://context7.com/video-db/videodb-python/llms.txt

Generates background music based on a prompt, specifying mood, genre, and tempo. Allows for custom audio creation.

```python
music = coll.generate_music(
    prompt="Upbeat electronic music with synth pads, 120 BPM",
    duration=60
)
print(f"Music ID: {music.id}, Length: {music.length}s")
```

--------------------------------

### Connect to VideoDB API

Source: https://context7.com/video-db/videodb-python/llms.txt

Establishes a connection to the VideoDB API using an API key or session token. Can also configure custom base URLs and logging levels.

```python
import videodb

# Connect with API key directly
conn = videodb.connect(api_key="YOUR_API_KEY")

# Or use environment variable VIDEO_DB_API_KEY
import os
os.environ["VIDEO_DB_API_KEY"] = "your-api-key"
conn = videodb.connect()

# Connect with custom base URL and logging
import logging
conn = videodb.connect(
    api_key="YOUR_API_KEY",
    base_url="https://api.videodb.io",
    log_level=logging.DEBUG
)

# Access default collection
coll = conn.get_collection()
print(f"Connected to collection: {coll.id}")
```

--------------------------------

### Generate Embed Code and Thumbnail

Source: https://context7.com/video-db/videodb-python/llms.txt

Generate embed code for web integration and create video thumbnails. Specify dimensions, title, and fullscreen options for embed code. For thumbnails, specify time for a specific frame.

```python
import videodb

conn = videodb.connect(api_key="YOUR_API_KEY")
video = conn.get_collection().get_video("m-video-id")

# Generate embed code for web integration
embed_code = video.get_embed_code(
    width="100%",
    height=480,
    title="My Video Player",
    allow_fullscreen=True
)
print(embed_code)  # <iframe src="..." ...>

# Generate thumbnail
thumbnail_url = video.generate_thumbnail()
print(f"Thumbnail: {thumbnail_url}")

# Generate thumbnail at specific timestamp
thumbnail_image = video.generate_thumbnail(time=45.5)
print(f"Thumbnail at 45.5s: {thumbnail_image.url}")
```

--------------------------------

### Transcode Videos

Source: https://context7.com/video-db/videodb-python/llms.txt

Initiates a video transcoding job with specified source, callback URL, and configuration for video and audio.

```python
import videodb
from videodb import TranscodeMode, VideoConfig, AudioConfig

conn = videodb.connect(api_key="YOUR_API_KEY")

# Start transcoding job
job_id = conn.transcode(
    source="https://example.com/raw_video.mov",
    callback_url="https://myapp.com/webhook/transcode-done",
    mode=TranscodeMode.economy,
    video_config=VideoConfig(resolution=1080, quality=23),
    audio_config=AudioConfig(mute=False)
)
print(f"Transcode job ID: {job_id}")

# Check transcode status
status = conn.get_transcode_details(job_id)
print(f"Status: {status}")
```

--------------------------------

### List Real-Time Streams

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Retrieve a list of all configured real-time streams associated with the collection.

```python
streams = coll.list_rtstreams()
```

--------------------------------

### Manage Scene Indexes

Source: https://github.com/video-db/videodb-python/blob/main/README.md

List all available scene indexes and retrieve a specific scene index by its ID.

```python
scene_indexes = video.list_scene_index()
```

```python
scenes = video.get_scene_index(scene_index_id)
```

--------------------------------

### Generate and Play Video Stream

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Generate a stream URL for a video and play it using the VideoDB player or directly in a browser/notebook.

```python
# Generate stream URL
stream_url = video.generate_stream()

# Play stream using VideoDB player
videodb.play_stream(stream_url)

# Play in browser/notebook
video.play()
```

--------------------------------

### Manage Audio and Image Media

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Retrieve, generate URLs for, and delete audio and image files associated with a collection.

```python
# Get audio files
audios = coll.get_audios()
audio = coll.get_audio(audio_id)
```

```python
# Generate audio URL
audio_url = audio.generate_url()
```

```python
# Get images
images = coll.get_images()
image = coll.get_image(image_id)
```

```python
# Generate image URL
image_url = image.generate_url()
```

```python
# Delete media
audio.delete()
image.delete()
```

--------------------------------

### Desktop Client: Stop Capture and Export Session

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Stop the ongoing desktop capture session and retrieve session details. The session can then be exported as a video asset.

```python
await client.stop_capture_session()

cap = coll.get_capture_session(cap.id)
export_result = cap.export()
```

--------------------------------

### Handle Search Errors

Source: https://context7.com/video-db/videodb-python/llms.txt

Illustrates catching `SearchError` which may occur if a video is not yet indexed for searching.

```python
import videodb
from videodb.exceptions import (
    VideodbError,
    AuthenticationError,
    InvalidRequestError,
    SearchError
)

# Handle search errors
try:
    video = conn.get_collection().get_video("m-video-id")
    results = video.search("query")
except SearchError as e:
    print(f"Search failed: {e}")
    # Video may not be indexed yet
```

--------------------------------

### Handle VideoDB Errors with Python Exceptions

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Implement robust error handling using `try-except` blocks with specific VideoDB exceptions like `AuthenticationError`, `InvalidRequestError`, and `SearchError`. This ensures graceful failure and informative feedback.

```python
from videodb.exceptions import (
    VideodbError,
    AuthenticationError,
    InvalidRequestError,
    SearchError
)

try:
    conn = videodb.connect(api_key="invalid_key")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")

try:
    video = conn.upload(url="invalid_url")
except InvalidRequestError as e:
    print(f"Invalid request: {e}")

try:
    results = video.search("query")
except SearchError as e:
    print(f"Search error: {e}")
```

--------------------------------

### Add Subtitles with Default Styling

Source: https://context7.com/video-db/videodb-python/llms.txt

Add subtitles to a video using its transcript data. Ensure the transcript exists before adding subtitles. Requires a video object.

```python
import videodb
from videodb import SubtitleStyle, SubtitleAlignment, SubtitleBorderStyle

conn = videodb.connect(api_key="YOUR_API_KEY")
video = conn.get_collection().get_video("m-video-id")

# Ensure transcript exists
video.generate_transcript()

# Add subtitles with default styling
stream_url = video.add_subtitle()
print(f"Video with subtitles: {stream_url}")
```

--------------------------------

### Generate Image from Prompt

Source: https://context7.com/video-db/videodb-python/llms.txt

Generates an image based on a text prompt and specified aspect ratio. Useful for creating visual content programmatically.

```python
image = coll.generate_image(
    prompt="A futuristic cityscape at sunset with flying cars",
    aspect_ratio="16:9"
)
print(f"Generated image: {image.url}")
```

--------------------------------

### Generate Video Transcript

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Generate a transcript for a video, optionally specifying a language code.

```python
video.generate_transcript()
```

```python
video.generate_transcript(language_code="en")
```

--------------------------------

### Generate and Play Video Stream

Source: https://context7.com/video-db/videodb-python/llms.txt

Generate a stream URL for a video and access its player URL. Stream specific timeline segments. Requires a video object.

```python
import videodb

conn = videodb.connect(api_key="YOUR_API_KEY")
video = conn.get_collection().get_video("m-video-id")

# Generate stream URL
stream_url = video.generate_stream()
print(f"Stream URL: {stream_url}")
print(f"Player URL: {video.player_url}")

# Generate stream for specific timeline segments
stream_url = video.generate_stream(
    timeline=[(0, 30), (60, 90), (120, 150)]  # Specific time ranges
)

# Play video in browser/notebook
video.play()
```

--------------------------------

### Customize Subtitle Styles with Python

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Define custom subtitle styles using the `SubtitleStyle` class. Configure font, colors, borders, alignment, and margins for precise subtitle appearance.

```python
from videodb import SubtitleStyle, SubtitleAlignment, SubtitleBorderStyle

style = SubtitleStyle(
    font_name="Arial",
    font_size=18,
    primary_colour="&H00FFFFFF",      # White
    secondary_colour="&H000000FF",     # Blue
    outline_colour="&H00000000",       # Black
    back_colour="&H00000000",          # Black
    bold=False,
    italic=False,
    underline=False,
    strike_out=False,
    scale_x=1.0,
    scale_y=1.0,
    spacing=0,
    angle=0,
    border_style=SubtitleBorderStyle.outline,
    outline=1.0,
    shadow=0.0,
    alignment=SubtitleAlignment.bottom_center,
    margin_l=10,
    margin_r=10,
    margin_v=10
)
```

--------------------------------

### Upload Media to VideoDB

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Upload videos, audio, or images from YouTube, public URLs, or local files. Metadata can be included during upload.

```python
# Upload video from YouTube URL
video = conn.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")

# Upload from public URL
video = conn.upload(url="https://example.com/video.mp4")

# Upload from local file
video = conn.upload(file_path="./my_video.mp4")

# Upload with metadata
video = conn.upload(
    file_path="./video.mp4",
    name="My Video",
    description="Video description"
)
```

--------------------------------

### Semantic Search in Videos

Source: https://context7.com/video-db/videodb-python/llms.txt

Enables indexing of spoken words for semantic search and performing searches within a single video or across an entire collection. Supports filtering by search type and sorting results.

```python
import videodb
from videodb import SearchType, IndexType

conn = videodb.connect(api_key="YOUR_API_KEY")
coll = conn.get_collection()
video = coll.get_video("m-video-id")

# Index spoken words for semantic search
video.index_spoken_words()

# Search within a single video
results = video.search("morning sunlight")
shots = results.get_shots()
for shot in shots:
    print(f"Found at {shot.start}s - {shot.end}s (score: {shot.search_score:.2f})")
    print(f"  Text: {shot.text}")

# Search across entire collection
results = coll.search(
    query="important announcement",
    search_type=SearchType.semantic,
    result_threshold=10,
    score_threshold=0.5
)

# Sort results by timestamp instead of relevance
results = coll.search(
    query="quarterly results",
    sort_docs_on="start"
)
```

--------------------------------

### Real-Time Streams (RTStream)

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Manage and process live video streams in real-time, including scene indexing, alerts, and stream generation.

```APIDOC
## Real-Time Streams (RTStream)

### Description
Process live video streams in real-time using the RTStream API. This includes connecting to streams, starting/stopping processing, indexing scenes, creating alerts, generating streamable outputs, and exporting recordings.

### Method
N/A (Code Example)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **url** (string) - The RTSP URL of the live stream.
- **name** (string) - The name for the real-time stream.
- **extraction_type** (SceneExtractionType) - The type of scene extraction (e.g., `time_based`).
- **extraction_config** (dict) - Configuration for scene extraction.
- **prompt** (string) - A prompt to describe the scene for indexing.
- **event_id** (string) - The ID of the event for which to create an alert.
- **callback_url** (string) - The URL to send alert notifications to.
- **start** (integer) - The start timestamp for generating the stream.
- **end** (integer) - The end timestamp for generating the stream.
- **player_config** (dict) - Configuration for the stream player.
- **name** (string) - The name for the exported recording.
- **page** (integer) - Page number for listing scenes.
- **page_size** (integer) - Number of scenes per page.

### Request Example
```python
from videodb import SceneExtractionType

# Connect to real-time stream
rtstream = coll.connect_rtstream(
    url="rtsp://example.com/stream",
    name="Live Stream"
)

# Start or Stop processing
rtstream.stop()
rtstream.start()

# Index scenes from stream
scene_index = rtstream.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 2, "frame_count": 5},
    prompt="Describe the scene"
)

# Start or Stop scene indexing
scene_index.stop()
scene_index.start()

# Get scenes
scenes = scene_index.get_scenes(page=1, page_size=100)

# Create alerts for events
alert_id = scene_index.create_alert(
    event_id=event_id,
    callback_url="https://example.com/callback"
)

# Enable/disable alerts
scene_index.disable_alert(alert_id)
scene_index.enable_alert(alert_id)

# Generate stream with player metadata
stream_url = rtstream.generate_stream(
    start=1711000000,
    end=1711003600,
    player_config={
        "title": "Live Feed",
        "description": "Stream recording",
        "slug": "live-feed"
    }
)

# Export a stopped stream as a video/audio asset
rtstream.stop()
export_result = rtstream.export(name="my_recording")

# List streams
streams = coll.list_rtstreams()
```

### Response
#### Success Response (200)
- **rtstream** (object) - Represents a real-time stream connection.
- **scene_index** (object) - Represents the scene indexing object.
- **scenes** (list) - A list of indexed scenes.
- **alert_id** (string) - The ID of the created alert.
- **stream_url** (string) - The URL of the generated stream.
- **export_result** (object) - The result of the export operation.
- **streams** (list) - A list of available real-time streams.
```

--------------------------------

### Retrieve Meeting Information from Video

Source: https://context7.com/video-db/videodb-python/llms.txt

Retrieves meeting metadata associated with a given video ID. Useful for accessing details of a past meeting recording.

```python
video = coll.get_video("m-video-id")
meeting_info = video.get_meeting()
if meeting_info:
    print(f"Meeting: {meeting_info.meeting_title}")
```

--------------------------------

### List Capture Sessions

Source: https://github.com/video-db/videodb-python/blob/main/README.md

Retrieve a list of all capture sessions associated with the account.

```python
sessions = coll.list_capture_sessions()
```
Tokens:
Raw