video-ambient-glow


Inspired by YouTube's immersive glow, this tiny, zero-dependency library adds a smooth, color-reactive effect behind HTML5 videos—no thumbnails or spritesheets needed.

📦 Install from npm

Demo

🎬 Live Example | Original on CodePen

Features

- 🎨 Extracts colors directly from the video
- 🌊 Smooth frame blending for natural transitions
- ⚡ Small bundle size (~5.8KB minified, ~2.0KB gzipped)
- 🎛️ Customizable blur, opacity, brightness, saturation
- 📦 Universal imports (ESM, CJS, UMD), auto-detects environment, tree-shakeable
- 🔒 Written in TypeScript with full types
- ♿ Accessible (canvas uses aria-hidden)

Install

``bash
npm install video-ambient-glow
`

Import Methods

$3

The package automatically detects your environment and serves the optimal format:

#### ES Modules (Recommended)

`typescript
import { AmbientGlow } from 'video-ambient-glow'
// TypeScript types included automatically
import type { GlowOptions } from 'video-ambient-glow'
`

#### CommonJS (Node.js)

`javascript
const { AmbientGlow } = require('video-ambient-glow')
`

#### Script Tag / CDN

`html






`

#### Dynamic Import

`javascript
const { AmbientGlow } = await import('video-ambient-glow')
`

> 💡 No configuration needed! Modern bundlers (Webpack 5+, Vite, Rollup, Parcel) automatically pick the best format based on your project setup.

Quick Start

`ts
import { AmbientGlow } from 'video-ambient-glow'

const video = document.querySelector('video')
const glow = new AmbientGlow(video, {
blur: 96,
opacity: 0.65,
brightness: 1.1,
saturate: 1.2
})

video.play()

// Cleanup
glow.destroy()
`

API

$3

Creates a glow behind a video element.

video — target HTMLVideoElement
options — optional configuration

`ts
interface GlowOptions {
blur?: number // default: 96
opacity?: number // 0–1, default: 0.65
brightness?: number // default: 1.1
saturate?: number // default: 1.2
scale?: number // canvas scale, default: 1.08
downscale?: number // sampling 0.01–0.5, default: 0.08
updateInterval?: number // in ms, default: 98
blendOld?: number // @deprecated Use responsiveness instead. Old frame weight, default: 0.85 (ignored if responsiveness is set)
blendNew?: number // @deprecated Use responsiveness instead. New frame weight, default: 0.15 (ignored if responsiveness is set)
responsiveness?: number // 0.0–1.0, simplified blending control, default: undefined. Higher = more responsive to changes. Overrides blendOld/blendNew when set.
}
`

$3

`ts
glow.updateOptions({ blur: 120, opacity: 0.8 }) // Update settings
glow.destroy() // Remove glow + listeners
`

Examples

$3

`ts
const glow = new AmbientGlow(document.querySelector('video'))
`

$3

`ts
const glow = new AmbientGlow(video, {
blur: 120,
opacity: 0.8,
brightness: 1.3,
saturate: 1.5,
updateInterval: 500
})
`

$3

`ts
glow.updateOptions({ opacity: 0.4, blur: 60 })
glow.updateOptions({ opacity: 0.9, blur: 150, saturate: 2.0 })
`

$3

`tsx
import { useEffect, useRef } from 'react'
import { AmbientGlow } from 'video-ambient-glow'

export function VideoPlayer({ src }: { src: string }) {
const ref = useRef(null)

useEffect(() => {
if (!ref.current) return
const glow = new AmbientGlow(ref.current, { blur: 96, opacity: 0.65 })
return () => glow.destroy()
}, [])

return `

$3

`svelte


`

$3

`ts
import {
Component,
ViewChild,
AfterViewInit,
OnDestroy,
Input,
ElementRef
} from '@angular/core'
import { AmbientGlow } from 'video-ambient-glow'

@Component({
selector: 'app-video-player',
template: ''
})
export class VideoPlayerComponent implements AfterViewInit, OnDestroy {
@Input() src!: string
@ViewChild('video', { static: false })
videoElement!: ElementRef

private glow: AmbientGlow | null = null

ngAfterViewInit() {
if (this.videoElement?.nativeElement) {
this.glow = new AmbientGlow(this.videoElement.nativeElement, {
blur: 96,
opacity: 0.65
})
}
}

ngOnDestroy() {
this.glow?.destroy()
}
}
`

$3

`vue



`

$3

`bash
cd example
npm install
npm run dev
`

Then open http://localhost:5173

How It Works

1. Captures frames from the video (downscaled for speed)
2. Blends new and old frames for smooth transitions
3. Draws the result to a background canvas
4. Applies CSS filters (blur, brightness, saturation)
5. Uses requestAnimationFrame at a throttled rate for performance

Low update rates and small sampling keep it lightweight while still reactive.

Architecture

- index.ts — Main class
- lib/ — Internal modules
- canvas.ts — Canvas creation and styling
- frameProcessor.ts — Color extraction and blending
- eventHandlers.ts — Safe event listeners
- constants.ts — Default config values
- types.ts — Type definitions

Modular, typed, and easy to extend.

Performance Tips

- Lower downscale for faster performance
- Increase updateInterval to save CPU
- Use responsiveness for blending control (recommended). blendOld/blendNew are deprecated.
- Auto-pauses when the video stops or scrolls out of view (uses IntersectionObserver)

Development

$3

| Script | Description |
| ----------------------- | ------------------------------------------ |
| npm run dev | Start development mode with watch (Rollup) |
| npm run build | Build the library for production |
| npm run build:example | Build library and example app |
| npm test | Run tests once |
| npm run test:watch | Run tests in watch mode |
| npm run lint | Format code and run ESLint |
| npm run format | Format code with Prettier |
| npm run format:check | Check code formatting without writing |

Testing

Uses Vitest + happy-dom.

`bash
npm test
npm run test:watch
``

License

MIT © video-ambient-glow contributors