Skip to main content
Transcoding converts video to standardized formats for playback and processing. Not all uploads need transcoding - use this guide to decide.

​
Quick Example

from videodb import TranscodeMode, VideoConfig

job_id = conn.transcode(
    source="https://example.com/source.mov",
    callback_url="https://your-backend.com/webhooks",
    mode=TranscodeMode.lightning
)
print(f"Job queued: {job_id}")

​
When You Need Transcoding

ScenarioTranscode?Why
MOV, MKV, AVI inputYesConvert to MP4/HLS for playback
4K source → 720p deliveryYesReduce size and bandwidth
High framerate (120fps) → 30fpsYesNormalize for web
Custom aspect ratioYesCrop or letterbox
MP4 already in target formatNoUpload directly
Already optimized for webNoSave processing cost

​
Input Limits

CapabilityLimit
Max Resolution4K (3840 × 2160)
Max Frame Rate100 fps
Max File Size8 GB
Audio SupportAAC, MP3, or mute
Need larger files or custom pipelines? Contact Sales or reach out on Discord.

​
Processing Modes

Choose based on your latency and cost requirements:
ModeBest ForTrade-off
lightningReal-time workflowsFaster, higher cost
economyBatch processingSlower, lower cost
from videodb import TranscodeMode

# Fast - for user-facing flows
job_id = conn.transcode(
    source=url,
    callback_url=callback,
    mode=TranscodeMode.lightning
)

# Economical - for batch jobs
job_id = conn.transcode(
    source=url,
    callback_url=callback,
    mode=TranscodeMode.economy
)

​
Job Lifecycle

  1. Submit Job - conn.transcode() → Status: pending
  2. Processing - Fetch & encode → Status: processing
  3. Complete - Webhook triggers with output URL

​
Check Status

job = conn.get_transcode_details(job_id)
print(job.status)  # pending | processing | completed | failed
print(job.output)  # URL when completed

​
Webhook Callbacks

​
Success

{
  "success": true,
  "data": {
    "job_id": "xxx",
    "output": "https://transcoded-output-url.mp4"
  },
  "message": "Transcode job completed"
}

​
Failure

{
  "success": false,
  "job_id": "xxx",
  "code": "invalid_source",
  "message": "Failed to download source media",
  "reason": "HTTP 403 Forbidden"
}

​
Error Codes

CodeMeaningFix
invalid_video_configResolution/FPS/CRF errorCheck ≤4K, ≤100 fps
invalid_audio_configConflicting audio paramsAdjust audio config
invalid_sourceURL not accessibleCheck URL permissions
invalid_mediaUnsupported formatConvert to supported format
internal_server_errorUnexpected errorRetry or contact support

​
Decision Flowchart

Source file arrives
        │
        ▼
Is it MP4/HLS at target resolution? ──Yes──► Upload directly
        │
       No
        ▼
Need resolution change? ──────────────────► Transcode
        │
       No
        ▼
Need format conversion? ──────────────────► Transcode
        │
       No
        ▼
Need framerate adjustment? ────────────────► Transcode
        │
       No
        ▼
Upload directly

​
Next Steps

Output Formats

MP4/HLS, resolutions, quality settings

Upload Video

Ingest media into VideoDB