Skip to content

📽️ Ultra tiny library to add cinematics to your HTML5 videos!

Notifications You must be signed in to change notification settings

simonwep/cinematic

Repository files navigation


Logo


Cinematic - Add cinematic effects to your videos!

License MIT No dependencies Support me version Buy me a coffee Build Status gzip size brotli size

Features 🤘

  • 🌟 Modern bundle.
  • 🔩 Ultra tiny (~1kb compressed)
  • 👌 Minimalistic and straight-forward API.
  • ⚡ Performant - uses only native browser features to achieve the affect!
  • 0️⃣ Zero dependencies.
  • 🌅 Video-to-video transitions.

Usage

Install it using your preferred package manager (taking npm as example):

npm install cinematic-effect

Your HTML:

<div id="container">
  <canvas id="background"></canvas>
  <video id="video" src="..."></video>
</div>

Your TypeScript (check out options and the effect api):

import { createCinematicEffect } from 'cinematic-effect';

const effect = createCinematicEffect({
  target: '#background', // Canvas to project effect onto
  src: '#video' // Source video element or selector
});

Your CSS:

This library is mainly taking care of creating a smooth effect and syncing the frames, the final effect is applied by you using css properties!

#container {
    display: flex;
    position: relative;
}

#background {
    position: absolute;
    z-index: -1;
    opacity: 0.75;
    transform: scale(1.05);
    filter: blur(45px);
    width: 100%;
    height: 100%;
}

Check out the demo for a full-fledged demo!

Options

The following options are available when creating a new instance:

import { createCinematicEffect } from 'cinematic-effect';

const effect = createCinematicEffect({
  
  // Target element the effect is rendered to.
  // Can be a selector or the element itself.
  target: '#background',
  
  // Video source, can be a selector or the video element itself.
  src: '#video',

  // Transition speed, default is 0.01, realtime is 1.
  sensitivity: 0.01
});

API

Each cinematic effect comes with the following API. It is highly recommended to use the API when changing the video instead of destroying / re-instantiating an effect, this way you will get a video-to-video transition and it's more performant.

interface CinematicEffect {

  // Destroy instance.
  destroy(): void;

  // Change source, target or sensitivity.
  setSource(video: string | HTMLVideoElement): void;
  setTarget(target: string | HTMLCanvasElement): void;
  setSensitivity(sensitivity: number): void;

  // Get current source and target elements.
  get source(): HTMLVideoElement;
  get target(): HTMLCanvasElement;
}