VideoDB Documentation
Transcoding Quickstart
Welcome to the VideoDB Transcoding Service! Quickly convert any video file into MP4 or HLS outputs. Follow this straightforward guide to ingest your source video, transcode it, and manage your jobs seamlessly.
Input Limits
Capability
Limit
Max Resolution
4K (3840 × 2160)
Max Frame Rate
100 fps
Max File Size
8 GB
Audio Support
AAC, MP3, or mute
There are no rows in this table
Output Options:
1. Install and Setup
Install and import the SDK:
!pip install videodb
import videodb
conn = videodb.connect(api_key="YOUR_API_KEY")
2.Quickstart Example:
Use this Python snippet to transcode your first video:
from videodb import TranscodeMode, VideoConfig, AudioConfig, ResizeMode
job_id = conn.transcode(
source="https://example.com/sample.mp4",
callback_url="https://example.com/webhooks/videodb",
mode=TranscodeMode.lightning, # or TranscodeMode.economy
video_config=VideoConfig(
resolution=360,
framerate=24,
resize_mode=ResizeMode.crop # crop | fit | pad
),
audio_config=AudioConfig(
mute=True # or False
)
)
print(f"Job queued ➜ {job_id}")
3. Configuration Reference
TranscodeMode
Mode
Ideal for
Notes
lightning
Fast response time
Optimized for speed (higher cost)
economy
Batch jobs
Cost-sensitive
There are no rows in this table
ResizeMode
Value
Behavior
crop
Crop edges to fill target aspect ratio
fit
Scale uniformly with letterboxing
pad
Add black bars to fill remaining space
There are no rows in this table
VideoConfig
Field
Type
Default
Notes
resolution
int
720
Height in pixels (auto-calculates width)
quality
int
23
CRF (Constant Rate Factor), lower is better
framerate
int or None
Source
Adjust frame rate (max 100 fps)
aspect_ratio
str or None
Source
e.g., 16:9, 1:1, None to retain original
resize_mode
ResizeMode
crop
How to adjust aspect ratio
There are no rows in this table
Quality presets (CRF)
Label
CRF Range
Best Use
Visually Lossless
18–20
Archival
Good Quality
21–23
General delivery
Lower Quality
24–28
Web, previews
There are no rows in this table
AudioConfig
Field
Type
Default
Notes
mute
bool
False
True removes audio track
There are no rows in this table
4. Job Lifecycle
Check job status:
job = conn.get_transcode_details(job_id)
print(job.status) # pending | processing | completed | failed
print(job.output) # Available URL when completed
5. Webhook Payloads
Success
{
"success": true,
"data": {
"job_id": "<job_id>",
"output": "<transcoded_output_url>"
},
"message": "Transcode job completed"
}
Failure
{
"success": false,
"job_id": "<job_id>",
"code": "invalid_source",
"message": "Failed to download source media",
"reason": "HTTP 403 Forbidden"
}
Respond with HTTP 2xx to confirm receipt.
6. Error Codes
Code
Meaning
Fix Suggestions
invalid_video_config
Resolution/FPS/CRF error
Check ≤4K, ≤100 fps
invalid_audio_config
Conflicting audio params
Adjust audio config
invalid_source
URL not accessible
Check URL accessibility
invalid_media
Unsupported media format
Convert to supported format
internal_server_error
Unexpected error
Retry or contact support
There are no rows in this table
Example Job output
{
"audio_config":{
"mute":false
},
"completed_at":1749564100,
"cost":0.1058,
"created_at":1749564014,
"input_details":{
"audio_codec":"mp3",
"duration":634.53, # in seconds
"format":"None",
"framerate":30,
"resolution":"1920x1080",
"size":263.34, # in mb
"video_codec":"h264"
},
"job_id":"<job_id>",
"mode":"lightning",
"output":"<mp4_url>",
"output_details":{
"audio_codec":"aac",
"duration":635.06,
"format":"mp4",
"framerate":30,
"resolution":"1920x1080",
"size":253.84,
"video_codec":"h264"
},
"source":"<source_url>",
"started_at":1749564014,
"status":"completed",
"video_config":{
"aspect_ratio":"None",
"codec":"libx264",
"framerate":"None",
"height":"None",
"quality":"None",
"resize_mode":"crop"
}
}
Want to print your doc?
This is not the way.
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.