How It Works
overlay_type must be a valid OverlayType (lowercase kebab-case). properties dict varies by type. Do NOT use this for charts/graphs/data — use add_data_viz instead.
FOR AUDIO OVERLAYS — three distinct types, pick the right one:
sound — Background music, ambient tracks, instrumentals. Use when user says "add music",
"background music", "add a beat", "ambient sound", "add a track". Goes on the BGM mixer
channel (gets automatically ducked under voiceover).
sfx — Sound effects, transitions, impacts, whooshes, risers. Use when user says "add a
whoosh", "transition sound", "impact", "ding", "boom", "notification sound", "applause".
Goes on the SFX mixer channel.
voiceover — AI-generated narration. Do NOT use add_overlay for voiceover — use adhoc_vo_solo
instead, which generates the audio from text via TTS.
For sound and sfx: set media_query to describe what the user wants (e.g. "upbeat electronic", "dramatic whoosh", "soft piano", "crowd cheering"). The system searches the audio library and auto-fills the real asset URL. NEVER put a URL in properties. properties for sound/sfx: {content: "display label", styles: {volume: 0.8}}.
FOR MAPS: Use place NAMES, not coordinates. The backend auto-resolves to real coords via PostGIS (5M+ cities, 4.4K regions, 236 countries). overlay_type determines the map skin — pick based on user intent:
map — basic clean map (default if user just says "add a map")
map-satellite-zoom — satellite imagery with zoom-in effect (space-to-ground reveals)
map-route-tracker — animated vehicle following a route (car, plane, boat, motorcycle, train)
map-tactical — military/intelligence briefing style (green phosphor, grid, targets)
map-vintage-explorer — old explorer/treasure map aesthetic (sepia, compass, landmarks)
map-news-broadcast — TV news broadcast style (headline, brand color, data items)
map-neon-city — cyberpunk/neon nightlife style (glowing markers, particles)
map-topographic — hiking/trail with elevation data (waypoints, elevation chart)
map-flight-path — airline route arcs (flights, plane icons, info cards)
map-data-choropleth — data visualization heat map (regions with values, color scales)
map-cinematic-split — split screen with map on one side and video on the other
Location — set ONE of: cityName:"Tokyo", iso_a2:"JP", regionName:"California". Backend resolves coords. Camera motion — use cameraCombo for preset motion instead of manual camera values:
smooth-zoom, dramatic-drop, bounce-land, slow-rotate, quarter-orbit, full-orbit,
tilt-reveal, crane-down, cinematic-swoop, flyover, satellite-descent, epic-reveal.
Easing: easeOutExpo (default), spring, easeOutBack, easeOutElastic, easeOutBounce, easeInOutCubic, linear, steps. Tile base: tileStyle — liberty, bright, positron, dark_matter, satellite, topo, watercolor, terrain. Pin icons: pinIcon — dot, pulse, modern-pin, pin, plus, x-mark, flag, anchor, skull, summit, camp, trail. Points of interest: points:[{label:"London"},{label:"Paris"}] — unified array, backend resolves coords. Routes: routes:[{fromLabel:"London", toLabel:"Paris", curved:true}] — backend resolves coords + arcs. Effects: vignette, grain, bloom (boolean) + vignetteAmount, grainAmount, bloomAmount (0-1), opacity (0-1). Borders: borders:{show:true, color:"#hex", width:2}. Fills: fills:{countries:["US","CA"], color:"#hex"}. Skin-specific arrays (backend migrates these into unified points[]):
route-tracker: waypoints[{label}], tactical: targets[{designation, type}],
vintage-explorer: landmarks[{label, icon}], neon-city: locations[{label}],
topographic: waypoints[{label, elevation}], flight-path: flights[{fromLabel, toLabel}],
data-choropleth: regions[{isoA2, value}], cinematic-split: syncPoints[{label, videoTimestamp}].
FOR STICKERS: overlay_type='sticker'. Properties must include: content — REQUIRED. "premium:{id}" for built-in SVG or "giphy:{giphy_id}" for GIPHY animated stickers. category — Social, Reactions, Arrows, Badges, Bubbles, Decorative, Emoji, Info (premium) or Search (GIPHY). src — GIPHY stickers need the transparent GIF/WebP URL. styles — {scale: 0.1-3, opacity: 0-1, fill: "#hex" (SVG only), animation: {enter: "fade"|"bounce"|"pop"|"spin"|"shake"|"float"}}. Premium sticker IDs match their name in kebab-case. Categories contain 8-18 stickers each. If unsure which sticker, emit a sticker_grid UI block with category filter so user can browse and pick.
FOR TEXT OVERLAYS: overlay_type='text'. properties must include content and styles. Minimum required style keys: fontSize, fontWeight, color, backgroundColor, fontFamily, fontStyle, textDecoration. All additional keys from change_text_style are also supported (letterSpacing, lineHeight, textTransform, textShadow, background, WebkitBackgroundClip, WebkitTextFillColor, padding, borderRadius, border, boxShadow, backdropFilter, opacity, filmGrain, vignette, breathe, cinemaComposition, animation). To apply a design template after creation, follow with apply_text_template. Quick-start: properties: { content: "Your Text", styles: { fontSize: "48px", fontWeight: "700",
color: "#FFFFFF", backgroundColor: "", fontFamily: "font-sans", fontStyle: "normal", textDecoration: "none" } }
Available fonts: font-sans (Inter), font-serif (Merriweather), font-mono (Roboto Mono),
font-retro (VT323), font-league-spartan, font-bungee-inline, font-poppins,
font-playfair-display, font-oswald, font-bebas-neue, font-pacifico
FOR COUNTER OVERLAYS: overlay_type='counter'. properties MUST include:
value — REQUIRED (number). The target number to count up to (e.g. 1000, 99.9, 50).
The counter animates from 0 to this value.
label — text shown above the digits (e.g. "SUBSCRIBERS", "REVENUE", "GOALS").
prefix — text before digits ("$", "#", "+").
suffix — text after digits ("%", "pts", "K", "views").
decimals — decimal places (0-4, default 0). Use 1-2 for currency/percentages.
skin — visual style. Pick based on user intent:
"rolling-digits" (default split-flap board), "scoreboard" (LED sports display),
"ticker-tape" (stock market/finance), "digital-clock" (7-segment LED),
"neon-counter" (glowing neon, PRO), "odometer" (car mechanical),
"minimal" (clean thin), "circular-progress" (ring with number),
"milestone" (achievement burst, PRO), "hud" (sci-fi readout, PRO).
Skin selection guide: sports → scoreboard, finance/stats → ticker-tape,
tech/sci-fi → hud or digital-clock, celebrations → milestone, clean/modern → minimal,
retro → rolling-digits or odometer, futuristic → neon-counter.
Style overrides (optional): digitColor (#hex), labelColor (#hex or rgba),
bgColor (#hex or transparent), ringColor (#hex for progress bar),
digitFont (font-family string), labelFont (font-family string),
opacity (0-1), scale (0.1-3), easing (linear|ease-out|spring|bounce),
totalFramesOverride (animation duration in frames, default ~36 = 1.2s).
Quick-start: properties: { value: 1000, label: "SUBSCRIBERS", skin: "rolling-digits" }
Example: "add a counter showing $50K revenue" →
properties: { value: 50000, label: "REVENUE", prefix: "$", suffix: "K", skin: "ticker-tape" }
FOR CALENDAR OVERLAYS: overlay_type='calendar'. Similar to counter — uses nested props.