{"id":26210792,"url":"https://github.com/dkaoster/scrolly-video","last_synced_at":"2025-05-14T07:11:08.451Z","repository":{"id":42493687,"uuid":"449573538","full_name":"dkaoster/scrolly-video","owner":"dkaoster","description":"Components for scroll-based (or other externally controlled) playback.","archived":false,"fork":false,"pushed_at":"2025-04-30T18:19:17.000Z","size":59340,"stargazers_count":1051,"open_issues_count":24,"forks_count":40,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-12T05:07:19.119Z","etag":null,"topics":["component","javascript","react","svelte","video","vue"],"latest_commit_sha":null,"homepage":"https://scrollyvideo.js.org/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dkaoster.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-19T06:27:57.000Z","updated_at":"2025-05-10T18:08:49.000Z","dependencies_parsed_at":"2022-08-12T21:50:10.539Z","dependency_job_id":"172bbad2-d1c8-4115-9d31-6a43cb43c7bb","html_url":"https://github.com/dkaoster/scrolly-video","commit_stats":{"total_commits":56,"total_committers":5,"mean_commits":11.2,"dds":0.4821428571428571,"last_synced_commit":"41d93e3c7d11daa1617c65534b32d01814e6fa8c"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dkaoster%2Fscrolly-video","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dkaoster%2Fscrolly-video/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dkaoster%2Fscrolly-video/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dkaoster%2Fscrolly-video/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dkaoster","download_url":"https://codeload.github.com/dkaoster/scrolly-video/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254092798,"owners_count":22013292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component","javascript","react","svelte","video","vue"],"created_at":"2025-03-12T07:34:17.033Z","updated_at":"2025-05-14T07:11:03.435Z","avatar_url":"https://github.com/dkaoster.png","language":"JavaScript","readme":"# ScrollyVideo.js\n\nA component for scroll-based (or other externally controlled) playback. See [`/demos`](https://github.com/dkaoster/scrolly-video/tree/main/demos) for full example usages.\n\n## 🚀 Web\n\nAdd html container to your page:\n\n```html\n\u003cdiv id=\"scrolly-video\"\u003e\u003c/div\u003e\n```\n\nRequire javascript in your page and create the object (before `\u003c/body\u003e`):\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/scrolly-video@latest/dist/scrolly-video.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\"\u003e\n  new ScrollyVideo({\n    scrollyVideoContainer: \"scrolly-video\",\n    src: \"https://scrollyvideo.js.org/goldengate.mp4\"\n  });\n\u003c/script\u003e\n```\n\nYou can replace `@latest` with specific version, example `@0.0.2`.\n\n## 🔵 React\n\nInstall npm module with `npm install scrolly-video --save`:\nImport component in your application:\n\n```javascript\nimport ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.cjs.jsx';\nor\nimport ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.esm.jsx';\n```\n\nAdd the component where you need it:\n\n```html\n\u003cScrollyVideo src=\"https://scrollyvideo.js.org/goldengate.mp4\" /\u003e\n```\n\n## 🟠 Svelte\n\nInstall npm module with `npm install scrolly-video --save`:\nImport component in your application:\n\n```javascript\nimport ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.svelte';\n```\n\nAdd the ScrollyVideo component to your application:\n\n```html\n\u003cScrollyVideo src=\"https://scrollyvideo.js.org/goldengate.mp4\" /\u003e\n```\n\n## 🟢 Vue\n\nInstall npm module with `npm install scrolly-video --save`:\nImport module in your `src/App.vue` and config:\n\n```javascript\nimport ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.vue';\n```\n\nAdd html code to your html component:\n\n```html\n\u003cScrollyVideo src=\"https://scrollyvideo.js.org/goldengate.mp4\" /\u003e\n```\n\n## 🔵 Astro\n\nInstall npm module with `npm install scrolly-video --save`: \nImport component in your frontmatter:\n\n```javascript\nimport ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.astro';\n```\n\n```html\n\u003cScrollyVideo src=\"https://scrollyvideo.js.org/goldengate.mp4\" /\u003e\n```\n\n## 🧰 Options / Attributes\n\n| Parameter             | Description                                                                                              | Values           | Default |\n|:----------------------|:---------------------------------------------------------------------------------------------------------|:-----------------|:--------|\n| src                   | The URL of the video (required)                                                                          | URL              |         |\n| scrollyVideoContainer | The DOM element of the container, only used for plain js                                                 | String / Element |         |\n| transitionSpeed       | Sets the maximum playbackRate for this video                                                             | Number           | 8       |\n| frameThreshold        | When to stop the video animation, in seconds                                                             | Number           | 0.1     |\n| cover                 | Forces the video to cover in it's container                                                              | Boolean          | true    |\n| sticky                | Whether the video should have `position: sticky`                                                         | Boolean          | true    |\n| full                  | Whether the video should take up the entire viewport                                                     | Boolean          | true    |\n| trackScroll           | Whether this object should automatically respond to scroll                                               | Boolean          | true    |\n| lockScroll            | Whether it ignores human scroll while it runs `setVideoPercentage` with enabled `trackScroll`            | Boolean          | true    |\n| useWebCodecs          | Whether the library should use the webcodecs method, see below                                           | Boolean          | true    |\n| videoPercentage       | Manually specify the position of the video between 0..1, only used for react, vue, and svelte components | Number           |         |\n| onReady               | The callback when it's ready to scroll                                                                   | VoidFunction     |         |\n| onChange              | The callback for video percentage change                                                                 | VoidFunction     |         |\n| debug                 | Whether to log debug information                                                                         | Boolean          | false   |\n\n\n## Additional callbacks\n\n***setVideoPercentage***\n\nDescription: 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.\n\nSignature: `(percentage: number, options: { transitionSpeed: number, (progress: number) =\u003e number }) =\u003e void`\n\nExample: `scrollyVideo.setVideoPercentage(0.5, { transitionSpeed: 12, easing: d3.easeLinear })`\n\n\n## Technical Details and Cross Browser Differences\nTo make this library perform optimally in all browsers, three different approaches are taken to animating the video.\n\n### Method 1: WebCodecs and Canvas\n\nUsing 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.\n\nIf WebCodecs is not supported by the browser or has not finished processing all frames, it falls back to method 2:\n\n### Method 2: HTML5 Video and playbackRate\n\nThis method simply embeds the video with an HTML `\u003cvideo\u003e` 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.\n\nThus, if the video needs to be animated backwards, this library falls back to method 3.\n\n### Method 3: HTML5 Video and currentTime\n\nThis method is the way that scrollytelling videos have traditionally been done, using an HTML `\u003cvideo\u003e` 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.\n\n## Known Issues\n- 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.\n\n---\n\nCreated by: [Daniel Kao](https://www.diplateevo.com/)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdkaoster%2Fscrolly-video","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdkaoster%2Fscrolly-video","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdkaoster%2Fscrolly-video/lists"}