# Personalized streaming

> A reference technical solution for composing per-user HLS feeds from indexed moments. Retrieve clips by query, compose them on a chunk-level timeline, apply branding and subtitles as overlay tracks, publish as an HLS manifest. No re-encode step.

---

## Hero

Path: Platform → Solutions → Personalized streaming

Flow: data (video) → transform → stream

A reference technical solution for composing per-user HLS feeds from indexed moments. Retrieve clips by query, compose them on a chunk-level timeline, apply branding and subtitles as overlay tracks, publish as an HLS manifest. No re-encode step.

CTAs: [Try the SDK](/developers) · [Talk to architecture](/company#contact)

---

## Architecture

**The composition pipeline.**

Request resolves against the indexes already built on your collection. Selected moments are composed on a Timeline; overlays apply at the manifest layer; output is an HLS m3u8 URL with per-segment caching.

Stages: REQUEST (source video + "Create highlights of this match" prompt) → MEMORY (scan the source, 2 moments detected) → TRANSFORM (Create clips, Add logo, Add subtitles, Change aspect ratio) → NEW STREAM (hls://highlights.m3u8, focal).

---

## The three stages

**Retrieve. Compose. Stream.** Each stage is a method on the SDK. No infrastructure to operate. No re-encoding pipelines to run.

### 01 — Retrieve from memory

Query the indexes you've already built. Filters, semantic recall, structured constraints — all in one call. Returns ranked moments with playable clip URLs.

```python
# pull moments
moments = vdb.retrieve("goals by player_42")
```

### 02 — Compose the timeline

Merge the moments. Lay overlays on top. Add multilingual subtitles. Reframe for the target aspect ratio. All chunk-level operations. No re-encode.

```python
# compose
tl = vdb.timeline(moments)
tl.overlay(logo="brand.png")
tl.subtitle(lang="en")
```

### 03 — Stream the result

Output is an HLS stream URL. Embeddable in any player, cacheable at the CDN edge, addressable per-user. Generated fresh, on demand.

```python
# publish
stream = tl.stream(format="hls")
# hls://cdn/u/42/highlights.m3u8
```

---

## Full implementation

A complete personalized highlight reel in under 20 lines.

```python
from videodb import connect

vdb = connect(api_key="<your-key>")

# 1. Retrieve. Query the indexes you already built.
#    Filters narrow scope; the index does the ranking.
moments = vdb.retrieve(
    query="goals scored by player_42",
    collection="season_2026",
    filters={"team": "home", "crowd_peak": True},
    limit=20,
)

# 2. Compose. Chunk-level edits, no re-encode.
timeline = vdb.timeline(moments)
timeline.overlay(image="brand.png", position="top-right", opacity=0.85)
timeline.subtitle(language="en", style="caption")
timeline.reframe(aspect="9:16")  # vertical for mobile

# 3. Stream. Fresh HLS URL, cacheable per-user.
stream = timeline.stream(format="hls", ttl="7d")

print(stream.url)
# → https://cdn.videodb.io/u/42/highlights.m3u8
```

---

## Data flow

**What actually happens between request and stream.** The whole pipeline executes inside VideoDB — no round-trip to your services, no re-encoding step.

| Stage | Detail | Note |
|---|---|---|
| REQUEST | user_42 + context | |
| INDEX SCAN | scenes, speech, embeddings, tags | ~90 ms |
| TIMELINE | cut, merge, overlay, caption | chunk-level |
| MANIFEST | HLS playlist + overlay layer | 0 re-encode |
| CDN EDGE | segment cache, per-user TTL | multi-region |
| PLAYER | .m3u8 embedded | |

End-to-end budget: under 1 second for first segment.

---

## What to know before you ship

- **Latency — Sub-second to first segment.** Retrieve is ~120 ms p95. Compose is chunk-pointer math. No re-encode. First HLS segment is served while later segments resolve in the background.
- **Caching — Per-user TTL at the edge.** Each personalized manifest gets a unique URL; CDN segments shared across users are deduplicated. Per-user TTL keeps invalidation cheap.
- **Overlays — Burned at the manifest layer.** Brand marks, subtitles, and reframes are applied as overlay tracks on the HLS manifest. Same source bits; new visual surface.
- **Cost — Usage-based, not minute-based.** Pay for retrievals + unique segments served. No charge for compose-time CPU. The format makes the cuts free.

---

## Use cases

What teams ship with this solution.

- **Sports highlight reels.** Per-fan highlights composed from live games and seasons of archive. Crowd-peak audio detection, player tracking, scoreboard overlay rendering at the manifest layer.
- **Episodic recap for OTT.** "Previously on" cuts generated per viewer based on the last episode watched and which character arcs they're following. Composed inline; output is a per-user HLS manifest.
- **Dynamic ad insertion.** Slot ads at scene boundaries, not on a fixed clock. Brand-safety and audience filters apply at compose time so the same source produces different manifests per viewer.
- **Agent-generated explainers.** An agent pulls source clips from a knowledge base, composes them with synchronized subtitles, and streams the result back to the user. The agent owns the query; VideoDB owns the render.

---

## Closing

Start streaming personalized video in minutes. Same SDK as the rest of the platform. Same six primitives underneath.

CTAs: [Start building](/developers) · [See Realtime alert](/platform/realtime-alert)