Video System Overview

The video system spans Application-Frontend (configuration, upload, VAST generation), Creative-Engine (playback, controls), and external infrastructure (Bunny CDN, Cloudflare delivery). This document covers the full pipeline from upload to delivery.

Architecture

Upload Flow:
  FileUploader.vue -> videoUpload.ts mixin -> Bunny CDN (TUS protocol)
    -> Bunny transcodes -> streamParser.ts polls + parses M3U8

Playback Flow:
  Builder preview / Standalone delivery
    -> CreativeVideoBlock.vue reads block properties
    -> streaming=true:  @cavai/minimal-video (HLS.js wrapper)
    -> streaming=false: native <video> with MP4 source

VAST Flow:
  TagGenerator.ts -> VAST 4.3 XML
    -> MediaFiles: Mezzanine + HLS streams + MP4 fallbacks
    -> TrackingEvents: start/quartiles/complete
    -> CompanionAds: responsive + format-specific

Key Files

Component	Path	Purpose
Type definitions	AF/src/pages/Chatbots/components/BuilderVisuals/Blocks/data/types.ts	VideoProperties interface
Defaults	AF/src/pages/Chatbots/components/BuilderVisuals/Blocks/data/defaults.ts	videoDefaults object
Configuration UI	AF/src/pages/Chatbots/components/BuilderVisuals/Configuration/configs/VideoConfiguration.vue	Main video settings panel
Video upload	AF/src/mixins/videoUpload.ts	Bunny upload flow and validation
File uploader	AF/src/components/common/FileUploader.vue	Generic file/video input component
Stream parser	AF/src/utils/streamParser.ts	M3U8 HLS manifest parsing
Video proxy	AF/src/services/videoProxy.ts	Upload status polling with soft progress bar
VAST generation	AF/src/utils/TagGenerator.ts	VAST 4.3 XML with streaming + MP4 fallbacks
Video flow op	AF/src/pages/Chatbots/components/CavaiFlow/operators/VideoOp.vue	Flow: add YouTube/stream video
Change video op	AF/src/pages/Chatbots/components/CavaiFlow/operators/ChangeVideoOp.vue	Flow: swap video with before/after comparison
Engine renderer	CE/src/components/creative/CreativeVideoBlock/CreativeVideoBlock.vue	Video playback (MP4 or HLS)
Engine controls	CE/src/components/creative/CreativeVideoBlock/CreativeVideoControls.vue	Play/Mute UI overlay
Delivery utils	AF/src/utils/delivery.ts	URL helpers for video thumbnails and originals
API service	AF/src/services/chatbotService.js	Bunny token, video delete endpoints

Video Block Properties

type VideoProperties = BlockBase & {
  video: {
    streamId: string        // Bunny CDN ID (UUID v4)
    fileName: string
    duration: number
    aspectRatio: number
  }
  playback: {
    autoplay: boolean
    pauseAfter: number      // seconds or loop count
    pauseMeasure: string    // 'infinity' | 'sec' | 'loop'
  }
  streaming: boolean        // HLS streaming toggle
  forceStreaming: boolean   // Override streaming (master/child system)
  pauseOutOfView: boolean
  forcePauseOutOfView: boolean
  layout: VideoLayout       // 'scale' | 'preserve' | 'stretch'
  // ... plus border, shadow, alignment, rotation, customCSS
}

Key defaults: autoplay: true, pauseMeasure: 'infinity', streaming: false, layout: 'scale'.

Layout modes map from legacy names: scale = cover with crop, preserve = contain with letterbox, stretch = fill.

CDN and Delivery Infrastructure

All video assets are served through Cloudflare (delivery-6.cavai.com) backed by Bunny CDN.

URL Patterns

Asset	URL
Original MP4	https://delivery-6.cavai.com/{streamId}/original
Preview thumbnail	https://delivery-6.cavai.com/{streamId}/preview.webp
Animated preview	https://delivery-6.cavai.com/{streamId}/preview.gif
HLS master playlist	https://delivery-6.cavai.com/{streamId}/playlist.m3u8
HLS per-rendition	https://delivery-6.cavai.com/{streamId}/{rendition}/video.m3u8
MP4 rendition	https://delivery-6.cavai.com/{streamId}/play_{rendition}.mp4

Delivery Domains

• Local dev: localhost:3333 (backend), localhost:8787 (video status proxy)
• Production: delivery-1/2/3/4/6.cavai.com (Cloudflare multi-region)

Stream ID

The streamId is a UUID v4 assigned by Bunny CDN during upload. It's the primary identifier used everywhere -- block properties, flow operators, VAST tags, CDN URLs. Validated with /^[\da-f-]{36}$/.