Skip to main content
View as Markdown

Best Practices - Avatar Videos

Best Practices​

  • Generate the KS server-side. The KS is visible in client-side code — generate it on your backend and pass it to the widget
  • Set partnerId as a number. The VOD Avatar widget requires partnerId as a number type (e.g., 12345 rather than "12345")
  • Ensure captions before composing. Source entries need captions or transcripts for AI composition. Use REACH to add captions first
  • Poll at 10-second intervals. The widget uses 10-second polling; match this in server-side integrations
  • Handle error states. Use resetStatus to recover from compose-error or generate-error, then modify scenes and retry
  • Preview audio before generating. Use previewAudio to verify narration quality — generation is more expensive
  • Reuse b-roll entries at different start times. The same entry at different startTime offsets gives visual variety without adding sources. Prefer fewer entries with longer durations for maximum reuse
  • Prepare b-roll entries. Ensure all b-roll source videos use standard frame rates (25 or 30 fps). Re-encode PowerPoint exports and screen recordings before uploading. Kaltura's transcoding pipeline handles codec conversion and adds audio tracks automatically
  • Write at least one full sentence per scene. The API validates narration text at video/add time — provide at least one complete sentence (~4+ words) per scene to produce sufficient TTS audio (1.5+ seconds)
  • Budget narration for b-roll scenes. TTS speaks at ~2.4 words/second. For b-roll scenes, keep word count below (clip_duration - startTime) × 2.1 to leave a safety margin. Use previewAudio and ffprobe to verify actual TTS duration for scenes close to the budget
  • Use long KS expiry for generation. Generation can take 10–20 minutes for complex videos. Use 86400s (24h) expiry to ensure the session remains valid throughout
  • Process generated videos. The resulting Kaltura entry can be enriched via REACH (captions, translation, chapters, summaries) or Agents (automated workflows)
  • Use HTTPS. The embeds loader and all widget bundles require HTTPS

Multi-Region CDN​

RegionServer-Side APIWidget URL
NVP1 (US East, default)https://video-avatar.nvp1.ovp.kaltura.com/api/v1https://unisphere.nvp1.ovp.kaltura.com/v1
IRP2 (EU West)https://video-avatar.irp2.ovp.kaltura.com/api/v1https://unisphere.irp2.ovp.kaltura.com/v1
FRP2 (EU Central)https://video-avatar.frp2.ovp.kaltura.com/api/v1https://unisphere.frp2.ovp.kaltura.com/v1
CAP2 (Canada)https://video-avatar.cap2.ovp.kaltura.com/api/v1https://unisphere.cap2.ovp.kaltura.com/v1
SGP2 (Singapore)https://video-avatar.sgp2.ovp.kaltura.com/api/v1https://unisphere.sgp2.ovp.kaltura.com/v1
SYP2 (Australia)https://video-avatar.syp2.ovp.kaltura.com/api/v1https://unisphere.syp2.ovp.kaltura.com/v1