Top Related Projects
Video.js - open source HTML5 video player
Interact with and control an embedded Vimeo Player.
A simple HTML5, YouTube and Vimeo player
:clapper: An extensible media player for the web.
The HTML5 video player for the web
Quick Overview
Scrolly-video is a lightweight JavaScript library that enables smooth, scroll-based video playback on web pages. It allows developers to create engaging, interactive video experiences where video playback is controlled by the user's scrolling action, enhancing storytelling and user engagement on websites.
Pros
- Easy to implement with minimal setup required
- Supports both horizontal and vertical scrolling
- Customizable with various options for playback control and styling
- Works well on both desktop and mobile devices
Cons
- Limited browser compatibility (mainly modern browsers)
- May impact page load times for large video files
- Requires careful consideration of video content to ensure a smooth user experience
- Potential accessibility concerns for users who rely on keyboard navigation
Code Examples
- Basic implementation:
import ScrollyVideo from 'scrolly-video';
new ScrollyVideo({
scrollyVideoContainer: document.querySelector('.scrolly-video'),
src: 'path/to/your/video.mp4'
});
- Customizing playback options:
new ScrollyVideo({
scrollyVideoContainer: document.querySelector('.scrolly-video'),
src: 'path/to/your/video.mp4',
playbackRate: 0.5,
frameThreshold: 0.1,
startScrollPercent: 0.2,
endScrollPercent: 0.8
});
- Using multiple video sources:
new ScrollyVideo({
scrollyVideoContainer: document.querySelector('.scrolly-video'),
src: [
{ src: 'path/to/video.webm', type: 'video/webm' },
{ src: 'path/to/video.mp4', type: 'video/mp4' }
]
});
Getting Started
-
Install the library:
npm install scrolly-video
-
Import and initialize in your JavaScript file:
import ScrollyVideo from 'scrolly-video'; document.addEventListener('DOMContentLoaded', () => { new ScrollyVideo({ scrollyVideoContainer: document.querySelector('.scrolly-video'), src: 'path/to/your/video.mp4' }); });
-
Add the necessary HTML structure:
<div class="scrolly-video"></div>
-
Style your container as needed:
.scrolly-video { width: 100%; height: 100vh; }
Competitor Comparisons
Video.js - open source HTML5 video player
Pros of video.js
- Extensive feature set and plugin ecosystem
- Broad browser and device compatibility
- Large community and active development
Cons of video.js
- Larger file size and potential performance overhead
- Steeper learning curve for advanced customization
- May be overkill for simple video playback needs
Code Comparison
scrolly-video:
import ScrollyVideo from 'scrolly-video';
const video = new ScrollyVideo({
src: 'path/to/video.mp4',
scrollyVideoContainer: document.querySelector('.scrolly-video')
});
video.js:
import videojs from 'video.js';
const player = videojs('my-video', {
controls: true,
sources: [{ src: 'path/to/video.mp4', type: 'video/mp4' }]
});
Key Differences
- scrolly-video focuses on scroll-based video playback, while video.js is a full-featured video player
- video.js offers more customization options and plugins
- scrolly-video has a simpler API for its specific use case
Use Cases
- Choose scrolly-video for scroll-triggered video animations in web pages
- Opt for video.js when building feature-rich video players with advanced controls and compatibility requirements
Interact with and control an embedded Vimeo Player.
Pros of player.js
- More comprehensive API for controlling video playback and interactions
- Supports multiple video hosting platforms beyond Vimeo
- Larger community and more extensive documentation
Cons of player.js
- Focused on embedded players, not scroll-based video playback
- Requires more setup and configuration for custom implementations
- Heavier library with more features that may not be needed for simple scroll-based videos
Code Comparison
scrolly-video:
import ScrollyVideo from 'scrolly-video';
const video = new ScrollyVideo({
src: 'path/to/video.mp4',
scrollyVideoContainer: document.querySelector('.scrolly-video')
});
player.js:
import Player from '@vimeo/player';
const player = new Player('handstick', {
id: 19231868,
width: 640
});
player.on('play', function() {
console.log('Played the video');
});
Key Differences
- scrolly-video is specifically designed for scroll-based video playback, making it easier to implement this specific feature
- player.js offers more extensive control over video playback and events, suitable for complex video player implementations
- scrolly-video has a simpler API focused on scroll-based interactions, while player.js provides a broader set of features for general video player functionality
A simple HTML5, YouTube and Vimeo player
Pros of Plyr
- More comprehensive media player with support for audio, video, and YouTube/Vimeo
- Extensive customization options and API for advanced control
- Larger community and more frequent updates
Cons of Plyr
- Heavier library with more features, which may be unnecessary for simple scroll-based video playback
- Requires more setup and configuration for basic usage
- Not specifically designed for scroll-based video interactions
Code Comparison
Scrolly-video:
import { ScrollyVideo } from 'scrolly-video';
new ScrollyVideo({
scrollyVideoContainer: document.querySelector('.scrolly-video'),
src: 'path/to/video.mp4'
});
Plyr:
import Plyr from 'plyr';
const player = new Plyr('#player', {
controls: ['play-large', 'play', 'progress', 'current-time', 'mute', 'volume', 'fullscreen']
});
Summary
Scrolly-video is a lightweight, specialized library for scroll-based video playback, while Plyr is a feature-rich, general-purpose media player. Scrolly-video is easier to implement for scroll-triggered video interactions, but Plyr offers more extensive customization and broader media support. Choose based on your specific project requirements and desired functionality.
:clapper: An extensible media player for the web.
Pros of Clappr
- More comprehensive media player with support for various formats and plugins
- Larger community and more active development
- Better suited for complex video playback scenarios
Cons of Clappr
- Heavier and more complex to implement for simple use cases
- May have unnecessary features for scroll-based video playback
- Less focused on scroll-triggered video interactions
Code Comparison
Scrolly-video:
import ScrollyVideo from 'scrolly-video';
new ScrollyVideo({
scrollyVideoContainer: document.querySelector('.scrolly-video'),
src: 'path/to/video.mp4'
});
Clappr:
var player = new Clappr.Player({
source: "http://your.video/here.mp4",
parentId: "#player"
});
Key Differences
- Scrolly-video is specifically designed for scroll-based video playback, while Clappr is a more general-purpose video player.
- Clappr offers more customization options and plugins, but Scrolly-video provides a simpler API for scroll-triggered video interactions.
- Scrolly-video is lighter and more focused on its specific use case, while Clappr is more feature-rich but potentially overkill for simple scroll-based video playback.
The HTML5 video player for the web
Pros of Flowplayer
- More comprehensive video player solution with a wider range of features
- Extensive documentation and community support
- Commercial-grade player with professional support options
Cons of Flowplayer
- Larger codebase and potentially more complex to implement
- May include unnecessary features for simple scrolling video implementations
- Commercial licensing required for some features
Code Comparison
Scrolly-video (basic usage):
import ScrollyVideo from 'scrolly-video';
new ScrollyVideo({
scrollyVideoContainer: document.querySelector('.scrolly-video'),
src: 'path/to/video.mp4'
});
Flowplayer (basic usage):
import flowplayer from 'flowplayer';
flowplayer('#player', {
clip: {
sources: [
{ type: 'video/mp4', src: 'path/to/video.mp4' }
]
}
});
Summary
Scrolly-video is a lightweight solution specifically designed for scroll-based video playback, while Flowplayer is a full-featured video player with broader capabilities. Scrolly-video may be more suitable for simple scroll-triggered video implementations, whereas Flowplayer offers a more robust set of features for complex video playback needs.
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
ScrollyVideo.js
A component for scroll-based (or other externally controlled) playback. See /demos
for full example usages.
ð Web
Add html container to your page:
<div id="scrolly-video"></div>
Require javascript in your page and create the object (before </body>
):
<script src="https://cdn.jsdelivr.net/npm/scrolly-video@latest/dist/scrolly-video.js"></script>
<script type="text/javascript">
new ScrollyVideo({
scrollyVideoContainer: "scrolly-video",
src: "https://scrollyvideo.js.org/goldengate.mp4"
});
</script>
You can replace @latest
with specific version, example @0.0.2
.
ðµ React
Install npm module with npm install scrolly-video --save
:
Import component in your application:
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.cjs.jsx';
or
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.esm.jsx';
Add the component where you need it:
<ScrollyVideo src="https://scrollyvideo.js.org/goldengate.mp4" />
ð Svelte
Install npm module with npm install scrolly-video --save
:
Import component in your application:
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.svelte';
Add the ScrollyVideo component to your application:
<ScrollyVideo src="https://scrollyvideo.js.org/goldengate.mp4" />
ð¢ Vue
Install npm module with npm install scrolly-video --save
:
Import module in your src/App.vue
and config:
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.vue';
Add html code to your html component:
<ScrollyVideo src="https://scrollyvideo.js.org/goldengate.mp4" />
ð§° Options / Attributes
Parameter | Description | Values | Default |
---|---|---|---|
src | The URL of the video (required) | URL | |
scrollyVideoContainer | The DOM element of the container, only used for plain js | String / Element | |
transitionSpeed | Sets the maximum playbackRate for this video | Number | 8 |
frameThreshold | When to stop the video animation, in seconds | Number | 0.1 |
cover | Forces the video to cover in it's container | Boolean | true |
sticky | Whether the video should have position: sticky | Boolean | true |
full | Whether the video should take up the entire viewport | Boolean | true |
trackScroll | Whether this object should automatically respond to scroll | Boolean | true |
lockScroll | Whether it ignores human scroll while it runs setVideoPercentage with enabled trackScroll | Boolean | true |
useWebCodecs | Whether the library should use the webcodecs method, see below | Boolean | true |
videoPercentage | Manually specify the position of the video between 0..1, only used for react, vue, and svelte components | Number | |
onReady | The callback when it's ready to scroll | VoidFunction | |
onChange | The callback for video percentage change | VoidFunction | |
debug | Whether to log debug information | Boolean | false |
Additional callbacks
setVideoPercentage
Description: A way to set currentTime manually. Pass a progress in between of 0 and 1 that specifies the percentage position of the video. If trackScroll
enabled - it performs scroll automatically.
Signature: (percentage: number, options: { transitionSpeed: number, (progress: number) => number }) => void
Example: scrollyVideo.setVideoPercentage(0.5, { transitionSpeed: 12, easing: d3.easeLinear })
Technical Details and Cross Browser Differences
To make this library perform optimally in all browsers, three different approaches are taken to animating the video.
Method 1: WebCodecs and Canvas
Using the new WebCodecs API we are able to get all frames in the video and have them ready to draw to a canvas. This method is the most performant, but has two drawbacks: first, depending on the device and the size of the video, using the WebCodecs API will take some time to process all the frames, so the animation will not be available immediately upon page load. Secondly, the WebCoedecs API is currently only available on Chrome, and the WebCodecs polyfill does not work for this application.
If WebCodecs is not supported by the browser or has not finished processing all frames, it falls back to method 2:
Method 2: HTML5 Video and playbackRate
This method simply embeds the video with an HTML <video>
tag, and it plays the video when the video needs to be animated. To adjust to the scroll speed, this method modulates the playbackRate
attribute on the video in order to dynamically mimic a faster or slower scroll speed. This method is extremely smooth when the scroll direction is moving the video forward, but unfortunately does not work in reverse because playbackRate
cannot be a negative value.
Thus, if the video needs to be animated backwards, this library falls back to method 3.
Method 3: HTML5 Video and currentTime
This method is the way that scrollytelling videos have traditionally been done, using an HTML <video>
tag and skipping directly to frames using currentTime. However, this method requires the video to be encoded at keyframe = 1, which causes the video to be a lot larger or the quality to drop. Unfortunately, this is the only option for scenarios where methods 1 and 2 are not supported, or on mobile safari browsers where somehow this method performs better than method 2. Thus, to achieve maximum performance under all circumstances, it is still recommended to encode videos with keyframe = 1, if possible.
Known Issues
- On iOS, ScrollyVideo will not work if battery saver mode is on. Unfortunately, there is no workaround for this due to the way that iOS handles videos and battery saving functions.
Created by: Daniel Kao
Top Related Projects
Video.js - open source HTML5 video player
Interact with and control an embedded Vimeo Player.
A simple HTML5, YouTube and Vimeo player
:clapper: An extensible media player for the web.
The HTML5 video player for the web
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot