Documentation

Cinematic Player

Our video player tracks when viewers replay parts of your videos. You see exactly which moments resonate. No guessing.

What It Does

• Full-screen video playback
• Custom play/pause controls that match your brand
• Tracks every second watched (stored in Cloudflare KV)
• Shows "Most Replayed" heatmap overlay
• Picture-in-picture mode (keeps playing while browsing)

How Engagement Tracking Works

The player divides your video into 20 equal segments. Every time someone watches a segment, we record it. When they seek backwards to rewatch something, we weight that twice as much. This data becomes your engagement heatmap.

Integration

import { videoPlayer } from '$lib/stores/videoPlayer';

const video = {
  id: 'v1',
  title: 'Your Video Title',
  src: 'https://cdn.example.com/video.mp4',
  thumbnail: 'https://cdn.example.com/thumb.jpg'
};

// Open the player
videoPlayer.play(video);

Data Storage

Engagement data lives in Cloudflare KV with the key engagement:{videoId}. Each bucket stores watch counts. Replay events count double.

Engagement Heatmap

See which parts of your video people replay. The heatmap shows engagement intensity as vertical bars. Taller bars = more replays.

What It Shows

• 20 bars representing video segments (each is 5% of total duration)
• Bar height = engagement level (0-100%)
• Animated reveal when the player opens
• Real-time updates as viewers interact

How to Read It

Tall bars mean viewers rewound and rewatched that part. Short bars mean people watched once and moved on. Use this to find:

• Hooks that work (tall bars early on)
• Confusing parts (tall bars in the middle = people rewatching to understand)
• Drop-off points (sudden decrease in bar height)

Technical Implementation

// Data structure from KV
{
  "videoId": "v1",
  "buckets": [0.3, 0.5, 0.9, 0.7, ...], // 20 values
  "live": true
}

// Normalized to 0-1 range for visualization
const maxValue = Math.max(...buckets);
const heights = buckets.map(v => (v / maxValue) * 100);

Performance

Heatmap data fetches once when the player opens. Updates happen via POST when viewers interact (debounced to every 2 seconds to reduce API calls).

Metric Card

Clean, animated number displays for your key metrics. Shows total views, watch time, or any other stat that matters.

Features

• Animated count-up on first load
• Icon + label + large number layout
• Trend indicator (up/down arrow with percentage)
• Glassmorphism background effect

Example Usage

<div class="metric-card">
  <div class="metric-icon">
    <Eye size={20} />
  </div>
  <div class="metric-label">Total Views</div>
  <div class="metric-value">847,293</div>
  <div class="metric-trend positive">
    ↑ 12.3%
  </div>
</div>

Animation Details

The count-up animation uses JavaScript's requestAnimationFrame for smooth 60fps rendering. It increments from 0 to the target value over 1.2 seconds with easing.

When to Use

Use metric cards for your dashboard overview. They work best when showing 3-4 key numbers side-by-side. Keep labels short (1-2 words).