### Easing Function Examples
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/types.md
Provides examples of different easing functions, including linear, quadratic ease-in, quadratic ease-out, and cubic ease-in-out.
```javascript
// Linear (no easing)
easing: (p) => p
```
```javascript
// Ease in (quadratic)
easing: (p) => p * p
```
```javascript
// Ease out (quadratic)
easing: (p) => 1 - (1 - p) * (1 - p)
```
```javascript
// Ease in-out (cubic)
easing: (p) => p < 0.5 ? 4 * p * p * p : 1 - Math.pow(-2 * p + 2, 3) / 2
```
--------------------------------
### ScrollyVideo Constructor Example
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-scrolly-video.md
Instantiate ScrollyVideo with configuration options for video source, container, and playback behavior. Callbacks for ready and change events are also demonstrated.
```javascript
const scrollyVideo = new ScrollyVideo({
scrollyVideoContainer: 'my-video-container',
src: 'https://example.com/video.mp4',
transitionSpeed: 12,
onReady: () => console.log('Video ready'),
onChange: (percentage) => console.log(`At ${percentage * 100}%`),
});
```
--------------------------------
### Install Scrolly Video npm Module
Source: https://github.com/dkaoster/scrolly-video/blob/main/README.md
Install the scrolly-video npm module using npm. This is the first step before importing it into your project.
```bash
npm install scrolly-video --save
```
--------------------------------
### Custom Error Examples
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/types.md
These examples show the standard JavaScript errors thrown by the library for various invalid conditions. Ensure proper validation before initializing ScrollyVideo.
```javascript
throw new Error('scrollyVideoContainer must be a valid DOM object');
```
```javascript
throw new Error('Must provide valid video src to ScrollyVideo');
```
```javascript
console.error('ScrollyVideo must be initiated in a DOM context');
```
```javascript
throw new Error('URL provided is not a valid mp4 video file.');
```
--------------------------------
### Vue Component Usage Example
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-vue.md
Demonstrates how to use the ScrollyVideo Vue component in a template and script. It shows how to pass props like src, videoPercentage, onReady, and onChange, and how to handle component events.
```vue
```
--------------------------------
### Fallback Behavior Example
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-videodecoder.md
Demonstrates the immediate return of the videoDecoder function when WebCodecs is unavailable. The onFrame callback will not be invoked, signaling the need for a fallback strategy.
```javascript
// Returns immediately without error
const result = await videoDecoder(src, onFrame, debug);
// onFrame is never called
// Caller must fall back to Strategy 2 or 3
```
--------------------------------
### Access ScrollyVideo Instance via Console Log
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-astro.md
This example demonstrates how to access the ScrollyVideo instance by hooking into console.log to capture the initialization object. Use this method when you need to control the video playback programmatically from custom JavaScript functions.
```astro
---import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.astro';---
```
--------------------------------
### Callback Argument Coercion
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/types.md
Shows how the 'onChange' callback receives a percentage value. This example demonstrates converting the 0-1 range to a 0-100 percent scale for display.
```javascript
// onChange receives number
onChange: (percentage) => {
// percentage is between 0 and 1
console.log(percentage * 100); // Percent
}
```
--------------------------------
### Basic Scrolly Video Integration in Astro
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-astro.md
Demonstrates the fundamental setup for embedding a Scrolly Video component in an Astro page. Ensure the `src` prop points to your video file.
```astro
---import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.astro';---
My Scrolly Video Page
Scroll me
```
--------------------------------
### FFmpeg Command for Keyframe Interval
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-videodecoder.md
Example FFmpeg command to encode a video with a keyframe interval of 1. This ensures every frame is a keyframe, enabling frame-accurate seeking.
```bash
ffmpeg -i input.mp4 -g 1 output.mp4
```
--------------------------------
### Integrate with Reactive State (React, Vue, Svelte)
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/README.md
Use these examples to integrate Scrolly Video with reactive state management in frameworks like React, Vue, or Svelte. The 'videoPercentage' prop and 'onChange' event allow for two-way binding with your state.
```javascript
// React
```
```javascript
// Vue
```
```javascript
// Svelte
(progress = p)}
trackScroll={false}
/>
```
--------------------------------
### Implement Jump Controls for Scrolly Video
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/README.md
Add click handlers to buttons to control video playback. Use `setVideoPercentage` with `{ jump: true }` for instant jumps to the start or end, or without for smooth transitions.
```javascript
document.querySelector('.btn-restart').onclick = () => {
scrollyVideo.setVideoPercentage(0, { jump: true });
};
document.querySelector('.btn-middle').onclick = () => {
scrollyVideo.setVideoPercentage(0.5);
};
document.querySelector('.btn-end').onclick = () => {
scrollyVideo.setVideoPercentage(1, { jump: true });
};
```
--------------------------------
### Error Handling for Video Decoding
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-videodecoder.md
Implement robust error handling for the videoDecoder function. This example shows how to catch specific errors, like invalid MP4 files, and provides a fallback mechanism.
```javascript
try {
await videoDecoder(src, onFrame, debug);
} catch (error) {
if (error.message.includes('not a valid mp4')) {
console.error('File is not a valid MP4 video');
} else {
console.error('Decoding failed:', error);
// Fall back to video element
}
}
```
--------------------------------
### With Callbacks
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-svelte.md
Illustrates how to use callback props like `onReady` and `onChange` to react to component events, such as when the video is ready to play or when its playback progress changes.
```APIDOC
## With Callbacks
### Description
This example shows how to leverage callback props (`onReady`, `onChange`) to handle events emitted by the ScrollyVideo component. This allows for dynamic UI updates or other logic based on the video's state, such as loading status and playback progress.
### Usage
```svelte
{#if !isReady}
Loading video...
{:else}
Progress: {Math.round(progress * 100)}%
{/if}
```
```
--------------------------------
### ScrollyVideo Class and Instance Methods
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/INDEX.md
Documentation for the ScrollyVideo class constructor and its instance methods, including methods for controlling video playback, scroll position, styling, frame manipulation, and cleanup.
```APIDOC
## ScrollyVideo Class
### Description
Represents the main ScrollyVideo player instance.
### Methods
- **constructor(options)**: Initializes a new ScrollyVideo instance.
- **setVideoPercentage(percentage)**: Controls video playback position.
- **setScrollPercent(percentage)**: Programmatically controls scroll position.
- **setCoverStyle(style)**: Applies styling to the container.
- **decodeVideo()**: Initiates WebCodecs frame extraction.
- **paintCanvasFrame()**: Renders a frame to the canvas.
- **transitionToTargetTime()**: Animates to a target video time.
- **destroy()**: Cleans up the instance and removes event listeners.
### Properties
- **[Public properties with types and descriptions]**
### Events
- **onReady**: Callback when the player is ready.
- **onChange**: Callback when the player state changes.
```
--------------------------------
### Configure ScrollyVideo with Environment Variables
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
Use environment variables to set configuration options like video source, debug mode, and WebCodecs usage. Pass these options to the ScrollyVideo constructor.
```javascript
const config = {
src: process.env.VIDEO_URL || 'default.mp4',
debug: process.env.NODE_ENV === 'development',
useWebCodecs: !process.env.DISABLE_WEBCODECS
};
new ScrollyVideo({
scrollyVideoContainer: 'container',
...config
});
```
--------------------------------
### Basic ScrollyVideo Usage with Scroll Tracking
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-svelte.md
This is the most basic setup for ScrollyVideo. The video will automatically respond to page scroll events to control playback.
```svelte
```
--------------------------------
### Execute Code When Video is Ready
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
Use the `onReady` callback to execute code once the video is prepared for playback. The timing differs based on whether WebCodecs is used.
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
onReady: () => {
console.log('Video is ready');
document.querySelector('.loading-spinner').style.display = 'none';
}
});
```
```javascript
onReady: () => {
document.querySelector('.loader').classList.add('hidden');
}
```
```javascript
onReady: () => {
console.log(`Decoded ${scrollyVideo.frames.length} frames`);
}
```
```javascript
onReady: () => {
document.querySelector('.controls').disabled = false;
}
```
--------------------------------
### Astro Client Script Initialization
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-astro.md
Imports the ScrollyVideo class and instantiates it on the client-side using all passed props. This script runs after the DOM is ready.
```astro
```
--------------------------------
### Initialize and Use VideoDecoder
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-videodecoder.md
Demonstrates how to import and use the videoDecoder function to decode an MP4 video file. It pushes each decoded frame into an array and logs the total count upon completion. Ensure the video source is CORS-accessible.
```javascript
import videoDecoder from 'scrolly-video/src/videoDecoder.js';
const frames = [];
await videoDecoder(
'https://example.com/video.mp4',
(frame) => {
frames.push(frame);
console.log(`Decoded frame: ${frames.length}`);
},
true // debug
);
console.log(`Total frames: ${frames.length}`);
```
--------------------------------
### Import ScrollyVideo using CommonJS
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-react.md
Import the ScrollyVideo component using the CommonJS module system. This is typically used in Node.js environments or older build setups.
```javascript
const ScrollyVideo = require('scrolly-video/dist/ScrollyVideo.cjs.jsx');
```
--------------------------------
### High-Quality Scroll Experience Configuration
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
Configure Scrolly Video for a high-quality experience with options like `cover`, `sticky`, `full`, `trackScroll`, `lockScroll`, `transitionSpeed`, `frameThreshold`, and `useWebCodecs`. Includes `onReady` and `onChange` callbacks.
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
cover: true,
sticky: true,
full: true,
trackScroll: true,
lockScroll: true,
transitionSpeed: 8,
frameThreshold: 0.1,
useWebCodecs: true,
onReady: () => console.log('Ready'),
onChange: (p) => updateUI(p),
debug: false
});
```
--------------------------------
### Import ScrollyVideo for React
Source: https://github.com/dkaoster/scrolly-video/blob/main/README.md
Import the ScrollyVideo component from the 'scrolly-video' npm module for use in your React application. Choose the appropriate import path based on your build setup.
```javascript
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.cjs.jsx';
or
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.esm.jsx';
```
--------------------------------
### Initialize ScrollyVideo in HTML
Source: https://github.com/dkaoster/scrolly-video/blob/main/README.md
Include the ScrollyVideo.js script and instantiate the ScrollyVideo object with the container ID and video source.
```html
```
--------------------------------
### Control Video Playback with setVideoPercentage
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-react.md
Use `useRef` to get a reference to the ScrollyVideo component and call `setVideoPercentage` to control playback. Options like `jump` and `transitionSpeed` can be provided.
```jsx
import { useRef } from 'react';
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.esm.jsx';
function PlayerWithControls() {
const scrollyRef = useRef(null);
return (
<>
);
}
```
--------------------------------
### ScrollyVideo with Callbacks for Ready and Change Events
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-svelte.md
Utilize `onReady` and `onChange` callbacks to manage component state and user interaction. Display loading indicators or progress information based on these events.
```svelte
{#if !isReady}
Loading video...
{:else}
Progress: {Math.round(progress * 100)}%
{/if}
```
--------------------------------
### Initialize Scrolly Video with onReady Callback
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-scrolly-video.md
Use the `onReady` callback to execute code once the video is prepared for playback. This is particularly useful for hiding loading indicators after the video is ready, especially when using WebCodecs.
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
onReady: () => {
console.log('Video is ready to play');
document.querySelector('.loading-spinner').style.display = 'none';
},
});
```
--------------------------------
### With Imperative Controls
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-svelte.md
Shows how to use imperative methods like `setVideoPercentage` to control video playback from buttons or other UI elements, disabling automatic scroll tracking.
```APIDOC
## With Imperative Controls
### Description
This example demonstrates controlling the ScrollyVideo component imperatively using its exported methods, such as `setVideoPercentage`. Buttons are used to trigger actions like restarting the video or playing it to the end, with automatic scroll tracking disabled.
### Usage
```svelte
```
```
--------------------------------
### Import ScrollyVideo for Different Frameworks
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/INDEX.md
Import the ScrollyVideo class from the main entry point or specific framework paths. Choose the path that matches your project's framework (vanilla JS, React, Svelte, Vue, Astro).
```javascript
import ScrollyVideo from 'scrolly-video';
// or from specific paths:
// 'scrolly-video/dist/scrolly-video.js' (vanilla JS)
// 'scrolly-video/dist/ScrollyVideo.cjs.jsx' (React CommonJS)
// 'scrolly-video/dist/ScrollyVideo.esm.jsx' (React ES6)
// 'scrolly-video/dist/ScrollyVideo.svelte' (Svelte)
// 'scrolly-video/dist/ScrollyVideo.vue' (Vue)
// 'scrolly-video/dist/ScrollyVideo.astro' (Astro)
```
--------------------------------
### Configure WebCodecs Decoding Option
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
Set `useWebCodecs` to `true` to attempt hardware-accelerated frame extraction, falling back to HTML5 video if unavailable. Set to `false` to force the HTML5 video element fallback.
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
useWebCodecs: true
});
```
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
useWebCodecs: false
});
```
--------------------------------
### Debounce Function Example
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-utils.md
Creates a debounced version of a function. Use this to limit the rate at which a function can be called, such as handling scroll events. The function will only execute after a specified delay has passed without further invocations.
```javascript
import { debounce } from 'scrolly-video/src/utils.js';
// Create a debounced scroll handler
const handleScroll = debounce(() => {
console.log('Scroll ended');
}, 100);
window.addEventListener('scroll', handleScroll);
// Console logs only once after scroll stops for 100ms
```
--------------------------------
### Scrolly Video Template Structure
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-vue.md
Defines the basic template structure for a Scrolly Video container. The `ref` attribute is used to get a reference to the DOM element for the ScrollyVideo constructor, and `data-scrolly-container` is for styling and identification.
```vue
```
--------------------------------
### Initialize ScrollyVideo in Vanilla JavaScript
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/README.md
Instantiate ScrollyVideo with a container ID and video source. Ensure the scrolly-video JavaScript file is imported.
```javascript
import ScrollyVideo from 'scrolly-video/dist/scrolly-video.js';
new ScrollyVideo({
scrollyVideoContainer: 'scrolly-video',
src: 'https://example.com/video.mp4'
});
```
--------------------------------
### ScrollyVideo Constructor and Options
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/README.md
Instantiate the ScrollyVideo class with required and optional configuration settings to control video behavior and appearance.
```APIDOC
## Constructor
`new ScrollyVideo(options)`
### Description
Initializes a new ScrollyVideo instance.
### Parameters
#### Path Parameters
None
#### Query Parameters
None
#### Request Body
None
### Configuration Options
**Required:**
- `src` (string) - URL of the video file.
- `scrollyVideoContainer` (string or HTMLElement) - The ID of the container element or the element itself.
**Playback:**
- `trackScroll` (boolean, default: `true`) - Whether to automatically track the scroll position.
- `lockScroll` (boolean, default: `true`) - Whether to lock the page scroll while the video is animating.
**Display:**
- `cover` (boolean, default: `true`) - Whether the video should fill the container like `background-size: cover`.
- `sticky` (boolean, default: `true`) - Whether to use `position: sticky` for the container.
- `full` (boolean, default: `true`) - Whether to make the video container occupy the full viewport height and width.
**Animation:**
- `transitionSpeed` (number, default: `8`) - Multiplier for animation speed.
- `frameThreshold` (number, default: `0.1`) - Minimum time in seconds to consider an animation complete.
**Features:**
- `useWebCodecs` (boolean, default: `true`) - Enable hardware-accelerated video decoding.
- `debug` (boolean, default: `false`) - Enable console logging for debugging.
```
--------------------------------
### Use ScrollyVideo with Vue Composition API
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-vue.md
Integrate the ScrollyVideo component using Vue's Composition API. This example demonstrates importing the component, managing component references with `ref`, and controlling video playback programmatically.
```vue
Loading video...
Progress: {{ Math.round(progress * 100) }}%
```
--------------------------------
### Initialize ScrollyVideo Data Property
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-vue.md
Sets up the `scrollyVideo` data property to hold the ScrollyVideo instance, initialized to null.
```javascript
data() {
return {
scrollyVideo: null,
};
}
```
--------------------------------
### Check Scroll Position Within Target Example
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-utils.md
Checks if the current page scroll position is within a specified threshold of a target scroll position. This is useful for detecting when scroll animations have completed or when a specific scroll point is reached.
```javascript
import { isScrollPositionAtTarget } from 'scrolly-video/src/utils.js';
// Check if user has scrolled to 1000px
const atTarget = isScrollPositionAtTarget(1000, 1);
console.log(atTarget); // true if window.pageYOffset is between 999-1001px
// With larger threshold for less precision
const nearTarget = isScrollPositionAtTarget(1000, 50);
console.log(nearTarget); // true if window.pageYOffset is between 950-1050px
```
--------------------------------
### Configure Full Viewport Behavior
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
Use the `full` option to make the video container occupy the entire viewport. Set to `true` for `100vh` height and `overflow: hidden`, or `false` for natural container sizing.
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
full: true
});
```
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
full: false
});
```
--------------------------------
### ScrollyVideo Complete Options Object
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
All available options for ScrollyVideo initialization. 'src' and 'scrollyVideoContainer' are mandatory.
```javascript
{
src: "https://example.com/video.mp4", // Required
scrollyVideoContainer: "container-id", // Required
cover: true, // Optional
sticky: true, // Optional
full: true, // Optional
trackScroll: true, // Optional
lockScroll: true, // Optional
transitionSpeed: 8, // Optional
frameThreshold: 0.1, // Optional
useWebCodecs: true, // Optional
onReady: () => {}, // Optional
onChange: () => {}, // Optional
debug: false // Optional
}
```
--------------------------------
### ScrollyVideo Constructor
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-scrolly-video.md
Initializes a new ScrollyVideo instance. This constructor sets up the video player, applies styling, and configures event listeners based on the provided options.
```APIDOC
## ScrollyVideo Constructor
### Description
Creates and initializes a ScrollyVideo instance with the given configuration.
### Signature
```javascript
constructor({
src,
scrollyVideoContainer,
cover = true,
sticky = true,
full = true,
trackScroll = true,
lockScroll = true,
transitionSpeed = 8,
frameThreshold = 0.1,
useWebCodecs = true,
onReady = () => {},
onChange = () => {},
debug = false
})
```
### Parameters:
#### Path Parameters
None
#### Query Parameters
None
#### Request Body
None
### Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `src` | string | Yes | — | URL of the MP4 video file to load |
| `scrollyVideoContainer` | string \| HTMLElement | Yes | — | DOM element ID (string) or HTMLElement where the video will be rendered |
| `cover` | boolean | No | `true` | Forces the video to cover its container using CSS transforms and sizing, similar to `background-size: cover` |
| `sticky` | boolean | No | `true` | Applies `position: sticky; top: 0` to the container for fixed positioning during scroll |
| `full` | boolean | No | `true` | Sets container to `width: 100%; height: 100vh; overflow: hidden` |
| `trackScroll` | boolean | No | `true` | Automatically responds to page scroll events and updates video playback accordingly |
| `lockScroll` | boolean | No | `true` | When true, scroll is locked while `setVideoPercentage()` is animating if `trackScroll` is enabled |
| `transitionSpeed` | number | No | `8` | Controls the speed of video transitions; higher values make transitions faster |
| `frameThreshold` | number | No | `0.1` | Minimum time difference (in seconds) to stop animation; prevents jitter near target frames |
| `useWebCodecs` | boolean | No | `true` | Attempts to use the WebCodecs API for frame extraction (Chrome only); falls back gracefully |
| `onReady` | function | No | `() => {}` | Callback fired when the video is decoded and ready for playback |
| `onChange` | function | No | `() => {}` | Callback fired when video percentage changes; receives percentage (0-1) as argument |
| `debug` | boolean | No | `false` | Enables console logging for debugging video playback and frame extraction |
### Request Example
```javascript
const scrollyVideo = new ScrollyVideo({
scrollyVideoContainer: 'my-video-container',
src: 'https://example.com/video.mp4',
transitionSpeed: 12,
onReady: () => console.log('Video ready'),
onChange: (percentage) => console.log(`At ${percentage * 100}%`)
});
```
### Response
#### Success Response (200)
Returns the `ScrollyVideo` instance.
#### Response Example
```json
{
"instance": "ScrollyVideo"
}
```
### Throws
- `Error` if `scrollyVideoContainer` is invalid or not found in DOM
- `Error` if `src` is not provided
```
--------------------------------
### Precise Control Configuration
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
Configure Scrolly Video for precise control with a low `transitionSpeed` and a small `frameThreshold`. Ensures `useWebCodecs` is enabled for accurate frame rendering.
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
transitionSpeed: 8,
frameThreshold: 0.05, // Very precise
useWebCodecs: true
});
```
--------------------------------
### Initialize ScrollyVideo
Source: https://github.com/dkaoster/scrolly-video/blob/main/demos/html/index.html
Instantiate ScrollyVideo by providing the ID of the container element and the video source URL. Ensure the container element exists in your HTML.
```javascript
new ScrollyVideo({ scrollyVideoContainer: "scrolly-video", src: "https://scrollyvideo.js.org/goldengate.mp4" });
```
--------------------------------
### Set Video Percentage with Options
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-scrolly-video.md
Control video playback position by setting a target percentage. Use the `jump` option for instant changes or animate with `transitionSpeed` and custom `easing` functions.
```javascript
scrollyVideo.setVideoPercentage(0.5, { jump: true });
scrollyVideo.setVideoPercentage(0.75, {
transitionSpeed: 12,
easing: (p) => p * p, // quadratic easing
});
```
--------------------------------
### Import Individual Utilities using ES6 Modules
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-utils.md
Use this pattern to import individual utility functions when using ES6 Modules.
```javascript
import { debounce } from 'scrolly-video/src/utils.js';
import { isScrollPositionAtTarget } from 'scrolly-video/src/utils.js';
```
--------------------------------
### Maximum Compatibility Configuration
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
Configure Scrolly Video for maximum compatibility by forcing the HTML5 fallback with `useWebCodecs: false` and using a slower `transitionSpeed` for better performance on older devices.
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
useWebCodecs: false, // Force HTML5 fallback
transitionSpeed: 4, // Slower for better compatibility
frameThreshold: 0.2
});
```
--------------------------------
### Fast Animation Playback Configuration
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
Configure Scrolly Video for fast animation playback using `transitionSpeed` and `frameThreshold`. Ensures `useWebCodecs` is enabled for performance.
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
transitionSpeed: 16,
frameThreshold: 0.2,
useWebCodecs: true
});
```
--------------------------------
### Import Utilities using ES6 Modules
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-utils.md
Use this pattern to import multiple utility functions when using ES6 Modules.
```javascript
import { debounce, isScrollPositionAtTarget } from 'scrolly-video/src/utils.js';
```
--------------------------------
### Using ScrollyVideo Svelte Component
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-svelte.md
Demonstrates how to integrate the ScrollyVideo Svelte component into an application. It shows binding a range input to control the video percentage and handling the `onReady` and `onChange` events.
```svelte
console.log('Ready')}
onChange={(pct) => (videoPercent = pct)}
/>
```
--------------------------------
### ScrollyVideoOptions Interface
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/types.md
Defines the configuration options for initializing the ScrollyVideo.
```APIDOC
## Interface: ScrollyVideoOptions
### Description
Options to configure the ScrollyVideo instance upon initialization.
### Properties
- `src` (string) - Required - The URL of the video file.
- `scrollyVideoContainer` (string | HTMLElement) - Required - The selector or element for the scrolly video container.
- `cover` (boolean) - Optional - Whether to enable cover mode.
- `sticky` (boolean) - Optional - Whether to enable sticky mode.
- `full` (boolean) - Optional - Whether to enable full mode.
- `trackScroll` (boolean) - Optional - Whether to track scroll events.
- `lockScroll` (boolean) - Optional - Whether to lock scroll.
- `transitionSpeed` (number) - Optional - The speed of transitions in seconds.
- `frameThreshold` (number) - Optional - The threshold for frame loading.
- `useWebCodecs` (boolean) - Optional - Whether to use WebCodecs for decoding.
- `onReady` (() => void) - Optional - Callback function when the video is ready.
- `onChange` ((percentage: number) => void) - Optional - Callback function when the video percentage changes.
- `debug` (boolean) - Optional - Whether to enable debug mode.
```
--------------------------------
### Initialize Scroll-Driven Narrative
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/README.md
Use this pattern for the default behavior where the video automatically plays as the user scrolls. Ensure 'trackScroll' and 'sticky' are set to true.
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
trackScroll: true, // Respond to scroll
sticky: true, // Stay at top
full: true // Full viewport
});
```
--------------------------------
### ScrollyVideo Initialization with scrollyVideoContainer (ID)
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
Initialize ScrollyVideo using the 'scrollyVideoContainer' option with a string ID. The element must exist in the DOM.
```javascript
// Using element ID
new ScrollyVideo({
scrollyVideoContainer: 'scrolly-video'
});
```
--------------------------------
### Basic Usage with Scroll Tracking
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-svelte.md
Demonstrates the basic usage of the ScrollyVideo component where the video automatically responds to page scroll events.
```APIDOC
## Basic Usage with Scroll Tracking
### Description
This example shows the simplest way to integrate ScrollyVideo, where the video playback is automatically synchronized with the user's scroll position on the page.
### Usage
```svelte
```
```
--------------------------------
### Scrolly Video with Environment Variables
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-astro.md
Shows how to use environment variables to configure the video source and debug mode for the Scrolly Video component. `PUBLIC_VIDEO_URL` is used for the video source, falling back to a default if not set. The `debug` prop is enabled when not in production mode.
```astro
---import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.astro';
const videoSrc = import.meta.env.PUBLIC_VIDEO_URL || '/default.mp4';
const isProduction = import.meta.env.PROD;---
```
--------------------------------
### Configure Video Cover Behavior
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
Use the `cover` option to control whether the video scales to fill its container. Set to `true` for CSS cover-like behavior, or `false` for native video size.
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
cover: true
});
```
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
cover: false
});
```
--------------------------------
### ScrollyVideo Initialization with scrollyVideoContainer (HTMLElement)
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
Initialize ScrollyVideo using the 'scrollyVideoContainer' option with an HTMLElement. The element must exist in the DOM.
```javascript
// Using HTMLElement
const container = document.querySelector('#my-container');
new ScrollyVideo({
scrollyVideoContainer: container
});
```
--------------------------------
### Responsive Container
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-svelte.md
Shows how to make the ScrollyVideo component responsive by nesting it within a container that tracks its width, allowing props like `cover`, `sticky`, and `full` to be adjusted based on screen size.
```APIDOC
## Responsive Container
### Description
This example demonstrates how to achieve responsiveness with ScrollyVideo by placing it inside a container element whose width is tracked. Based on the container's width, props like `cover`, `sticky`, and `full` can be conditionally applied to adjust the video's behavior for different screen sizes (e.g., mobile vs. desktop).
### Usage
```svelte
```
```
--------------------------------
### decodeVideo
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/types.md
Asynchronously decodes the video. This can be called to pre-load and prepare the video for playback, potentially improving initial load times.
```APIDOC
## decodeVideo (async)
### Description
Asynchronously decodes the video.
### Returns
- **Promise** - A promise that resolves when the video has been decoded.
### Example
```javascript
async function loadVideo() {
await player.decodeVideo();
console.log('Video decoded and ready.');
}
loadVideo();
```
```
--------------------------------
### Astro Props Flow Diagram
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-astro.md
Illustrates the lifecycle of props from Astro components to the ScrollyVideo instance on the client.
```text
Astro Props (TypeScript/JavaScript)
↓
Frontmatter Destructuring
↓
Server renders HTML with ID
↓
Client script receives all props
↓
ScrollyVideo instance created
↓
Video plays based on scroll
```
--------------------------------
### ScrollyVideo with Imperative Controls
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-svelte.md
Implement imperative controls like 'Restart' and 'Play to End' using the `setVideoPercentage` method. Set `trackScroll` to `false` when using manual controls.
```svelte
```
--------------------------------
### Import Utilities using CommonJS
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-utils.md
Use this pattern to import multiple utility functions when using CommonJS module system.
```javascript
const { debounce, isScrollPositionAtTarget } = require('scrolly-video/src/utils.js');
```
--------------------------------
### Astro Video Serving with CDN
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-astro.md
Serve video files using a CDN by constructing the video URL with the SITE environment variable. This ensures proper serving of video assets.
```astro
---import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.astro';
const videoUrl = new URL('/videos/demo.mp4', import.meta.env.SITE).toString();
---
```
--------------------------------
### transitionToTargetTime
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/types.md
Transitions the video playback to a target time based on configured options. This method allows for smooth seeking to specific points in the video.
```APIDOC
## transitionToTargetTime
### Description
Transitions the video playback to a target time.
### Parameters
- **options** (TransitionOptions) - Required - Configuration for the transition.
- **jump** (boolean) - Optional - If true, jumps directly to the target time without transition.
- **transitionSpeed** (number) - Optional - The duration of the transition in seconds.
- **easing** (function) - Optional - A function to define the easing curve for the transition. It takes a progress value (0 to 1) and returns an eased value.
### Example
```javascript
player.transitionToTargetTime({ jump: false, transitionSpeed: 2 });
```
```
--------------------------------
### Enable Debug Logging
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md
Enable verbose console logging for debugging Scrolly Video. Use `true` for development and `false` for production. Conditional debugging based on hostname is also shown.
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
debug: true
});
```
```javascript
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
debug: false
});
```
```javascript
const isDevMode = window.location.hostname === 'localhost';
new ScrollyVideo({
src: 'video.mp4',
scrollyVideoContainer: 'container',
debug: isDevMode
});
```
--------------------------------
### Configuring Scrolly Video Props
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-astro.md
Illustrates various configuration options available for the Scrolly Video component, including `transitionSpeed`, `frameThreshold`, `sticky`, `full`, `cover`, `trackScroll`, `lockScroll`, `useWebCodecs`, and `debug`. The `debug` prop is conditionally set based on the development environment.
```astro
---import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.astro';
const isDevelopment = import.meta.env.DEV;---
```
--------------------------------
### Astro: Server-Side Callback Limitation
Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference-astro.md
Shows that callbacks like `onReady` are only invoked client-side and will not execute during server-side rendering. The console log will only appear in the browser.
```astro
---
// ❌ Server-side callback won't execute
const handleReady = () => {
console.log('Ready'); // Only logs in browser
};
---
```