{"id":22243010,"url":"https://github.com/mediamonks/fast-image-sequence","last_synced_at":"2025-07-28T01:32:16.640Z","repository":{"id":208253099,"uuid":"721175753","full_name":"mediamonks/fast-image-sequence","owner":"mediamonks","description":"The fast-image-sequence-renderer is a powerful package that allows you to display a sequence of images at a high frame rate on your website. It can be used to create smooth animations, 360 product views or video-like sequences from a series of images.  Zero dependencies.","archived":false,"fork":false,"pushed_at":"2025-07-21T14:31:32.000Z","size":114149,"stargazers_count":29,"open_issues_count":2,"forks_count":3,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-07-21T14:51:12.827Z","etag":null,"topics":["360","360-view","canvas","flipbook","image-sequence","image-sequence-player"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@mediamonks/fast-image-sequence","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mediamonks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2023-11-20T14:08:53.000Z","updated_at":"2025-07-21T14:31:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"a5c5934a-5936-4b67-a07d-5dd1330fe632","html_url":"https://github.com/mediamonks/fast-image-sequence","commit_stats":null,"previous_names":["mediamonks/fast-image-sequence"],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/mediamonks/fast-image-sequence","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mediamonks%2Ffast-image-sequence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mediamonks%2Ffast-image-sequence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mediamonks%2Ffast-image-sequence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mediamonks%2Ffast-image-sequence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mediamonks","download_url":"https://codeload.github.com/mediamonks/fast-image-sequence/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mediamonks%2Ffast-image-sequence/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267451022,"owners_count":24089291,"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","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["360","360-view","canvas","flipbook","image-sequence","image-sequence-player"],"created_at":"2024-12-03T04:19:30.842Z","updated_at":"2025-07-28T01:32:16.630Z","avatar_url":"https://github.com/mediamonks.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fast Image Sequence Renderer\n\nThe fast-image-sequence is a powerful package that allows you to display a sequence of images at a high frame rate on\nyour website. It can be used to create smooth animations, 360-degree product views or video-like sequences from a series of\nimages.\nZero dependencies.\n\nThe FastImageSequence supports various options for customizing the behaviour of the image sequence, such as preloading\nall images, using a worker to handle tar files, and more.\n\n## Demo\n\n- [Stress test with multiple demos](https://mediamonks.github.io/fast-image-sequence/).\n\nThis is a build from the repository's example/ directory.\n\n## Getting started\n\n### Installing\n\nAdd `@mediamonks/fast-image-sequence` to your project:\n\n```sh\nnpm i @mediamonks/fast-image-sequence\n```\n\n## Basic usage\n\nCreating a FastImageSequence instance and playing an image sequence.\n\n```ts\nimport {FastImageSequence} from '@mediamonks/fast-image-sequence';\n\nconst options = {\n  frames: 100,\n  src:    {\n    imageURL: (index) =\u003e `path/to/your/image/sequence/image${index}.jpg`,\n  },\n\n  loop:      true,\n  objectFit: 'cover',\n};\n\nconst sequence = new FastImageSequence(containerElement, options);\nsequence.play();\n```\n\nIn the options object, you must set the numbers of `frames` and an `imageURL`. The `imageURL` is a function that\ntakes an index as a parameter and returns a string representing the URL of the image at that index in the sequence.\n\n### Loading images from a tar file\n\nIf you want, you can load images from a tar file. This can be useful when you want to preload all images at once with\nminimal memory usage. You can use a tar file by setting the `tarURL` option. You also need to set the `imageURL`, which\nin this case returns the image's URL in the tar file.\n\n```ts\nconst options = {\n  frames: 100,\n  src:    {\n    tarURL:   'path/to/your/tar/file.tar',\n    imageURL: (index) =\u003e `image${index}.jpg`,\n  },\n\n  loop:      true,\n  objectFit: 'cover',\n};\n```\n\n### Advanced usage\n\nYou can also set multiple sources for the FastImageSequence class. This can be useful when you want to load images from\ndifferent sources, such as a tar file *and* an image URL. You can set an array of ImageSource in the src option.\nEach ImageSource can have its imageURL and tarURL.\n\nThe FastImageSequence class will try to load images from the first source in the array. If an image is not available\nyet, it will try to load it from the next source in the\narray, etc. Finally, the best matching available image will be rendered.\n\n```ts\nimport {FastImageSequence} from '@mediamonks/fast-image-sequence';\n\nconst options = {\n  frames: 100,\n\n  src: [\n    {\n      // First try to display a highres image from an image URL\n      imageURL:        (index) =\u003e `path/to/your/image/sequence/highres_image${index}.jpg`,\n      maxCachedImages: 16,\n    },\n    {\n      // Fallback if highres image is not loaded yet: serve a low res image from the tar file\n      tarURL:          'path/to/your/tar/file.tar',\n      imageURL:        (index) =\u003e `lowres_image${index}.jpg`,\n      maxCachedImages: 32,\n    },\n  ],\n\n  loop:      false,\n  objectFit: 'contain',\n};\n\nconst sequence = new FastImageSequence(containerElement, options);\nsequence.play();\n```\n\nThe example above can be useful when you have a large image sequence with high-resolution images or if the user randomly jumps to any frame in the sequence and you want a fast response time.\n\nNote that you can store a subset of the images (all even images, for example) in the tar file. The FastImageSequence\nwill automatically fall back to the best matching available image when rendering a frame.\n\n### Available options for FastImageSequence\n\n- **frames**: `number` - Number of frames in the sequence. Required.\n- **src**: `ImageSourceOptions[] | ImageSourceOptions` The source of the images for the FastImageSequence class. It can\n  either be an array of ImageSourceOptions or a single ImageSourceOptions instance.\n- **loop**: `boolean` - Whether the sequence should loop. Default: `false`\n\n- **objectFit**: `'contain' | 'cover'` - How the image should fit the canvas. Default: `'cover'`\n- **horizontalAlign**: `number` - Horizontal image alignment. Default: `0.5`\n- **verticalAlign**: `number` - Vertical image alignment. Default: `0.5`\n\n- **poster**: `string | undefined` - URL of the poster image. Optional.\n- **fillStyle**: `string` - Fill style of the canvas. Default: `'#00000000'`\n- **clearCanvas**: `boolean` - Clear the canvas before drawing. Default: `false`\n- **scale**: `number` - Scale of the image. Default: `1`\n- **showDebugInfo**: `boolean` - Show debug info. Default: `false`\n- **name**: `string` - Name of the FastImageSequence instance. Default: `'FastImageSequence'`\n\n### Available options for an ImageSource\n\n- **imageURL**: `(index: number) =\u003e string` - Callback returning the URL of an image given its index.\n- **tarURL**: `string | undefined` - URL of the tar file containing images. Optional.\n- **useWorker**: `boolean` - Use a worker to fetch images. Default: `!isMobile()`\n- **maxConnectionLimit**: `number` - Maximum concurrent connections for fetching images. Default: `4`\n- **maxCachedImages**: `number` - Number of images to cache. Default: `32`\n- **available**: `((index: number) =\u003e boolean) | undefined` - Callback returning whether an image is available.\n  Optional.\n- **image**: `((index: number) =\u003e Promise\u003cCanvasImageSource\u003e) | undefined` - Callback returning the image given its\n  index.\n  Optional.\n- **timeout**: `number` - Only start loading an image if the same frame is visible for this time (in\n  milliseconds). Optional.\n\n## Methods\n\nThe following methods are available for a FastImageSequence object:\n\n### tick(func: (dt: number) =\u003e void)\n\nThis method registers a tick function to be called on every frame update.\n\n```typescript\nsequence.tick(func);\n```\n\n- `func` is a function that will be called on every frame update.\n\n### play(fps: number = 30)\n\nThis method starts playing the image sequence at a specified frame rate.\n\n```typescript\nsequence.play(fps);\n```\n\n- `fps` is an optional parameter determining the frame rate at which to play the sequence. If not provided, it defaults\n  to `30`. Note that the fps can also be negative, which will play the sequence in reverse.\n\n### stop()\n\nThis method stops playing the image sequence.\n\n```typescript\nsequence.stop();\n```\n\n### playing\n\nThis getter method returns a boolean indicating whether the image sequence is playing.\n\n```typescript\nconst playingStatus = sequence.playing;\n```\n\n### paused\n\nThis getter method returns a boolean indicating whether the image sequence is paused.\n\n```typescript\nconst pausedStatus = sequence.paused;\n```\n\n### progress\n\nThis getter-and-setter method retrieves or sets the image sequence's current progress (0-1).\n\n```typescript\n// Get the progress\nconst currentProgress = sequence.progress;\n\n// Set the progress\nsequence.progress = value;\n```\n\n- `value` is a number that sets the current progress of the image sequence.\n\n### scale\n\nThis getter-and-setter method retrieves or sets the scale of the image sequence. Default: 1.\n\n```typescript\nsequence.scale = 2; // zoom in\n```\n\n### frameCount\n\nThis getter-and-setter method retrieves or sets the number of frames in the image sequence. You can use it to, for example, increase the number of frames in the sequence dynamically.\n\n```typescript\nsequence.frameCount = sequence.frameCount + 100;\n```\n\n### loadProgress\n\nThis is a getter method that retrieves the current load progress of the image sequence.\n\n```typescript\nconst currentLoadProgress = sequence.loadProgress;\n```\n\nThe `loadProgress` property returns a number between 0 and 1, representing the current load progress of the image\nsequence. Note that the value can decrease if the sequence is played and new frames are loaded.\n\n### getFrameImage(index: number): Promise\u003cCanvasImageSource\u003e\n\nThis method gets the image of a specific frame and returns a Promise that resolves with the image of the frame.\n\n```typescript\nsequence.getFrameImage(index);\n```\n\n- `index` is the index of the frame.\n\n### onLoadProgress(onProgress?: (progress: number) =\u003e void): Promise\u003cvoid\u003e\n\nRegister a callback function that is called with the progress of the loading. The function returns a promise that\nresolves when progress reaches 1.\n\n```typescript\nsequence.onLoadProgress(onProgress);\n```\n\n## ImageSource Methods\n\n### sources[index:number].setMaxCachedImages(maxCache: number, onProgress?: (progress: number) =\u003e void): Promise\u003cvoid\u003e\n\nThis method sets the number of images that should be preloaded and cached in memory for an input source and returns a\nPromise that resolves when all these images are preloaded and cached.\n\n```typescript\nsequence.sources[0].setNumberOfCachedImages(maxCache, onProgress);\n```\n\n- `maxCache` is the number of images to cache. This should be a positive integer.\n- `onProgress` is an optional callback function whenever the loading progress changes. It receives the current progress as a number between 0 and 1.\n\nThe returned Promise resolves when loadProgress reaches 1.\n\n## Creating a Tarball with Images\n\nA tarball is a collection of files and directories stored in a single file. In the context of `FastImageSequence`, you\ncan use a tarball to store (low-resolution preview) images for your image sequence. This can be particularly useful when\nyou want to seek or jump in the sequence quickly or when the internet speed is low.\n\nTo create a tarball with images, you can follow these steps:\n\n1. Prepare your images: Make sure all your images are in a single directory. The images should be in a sequence and\n   named consistently (for example, `image1.jpg`, `image2.jpg`, `image3.jpg`, etc.).\n\n2. Create a tarball file. I have created an easy-to-use online tool for\n   this: [Tar File Creator](https://reindernijhoff.net/tools/tar/) (no ads, login, etc). Drag and drop your selection of\n   images onto the page, and a tarball will be generated that you can download.\n\n3. Alternatively, use a tar tool to create the tarball: if you are comfortable with the command line, you can use\n   the `tar` command in Unix-based systems like this:\n\n    ```sh\n    cd /path/to/your/images\n    tar -cvf sequence.tar -C ./ .\n    ```\n\nOnce you have your tarball, you can use it with `FastImageSequence` by setting the `tarURL` option to the URL of your\ntarball and implement the `imageURL` to return the URL of an image in the tarball, given its index.\n\n## Frequently Asked Questions\n\n### How can I create a tar file (tarball) with images?\n\nI created an easy-to-use online tool for this: [Tar File Creator](https://reindernijhoff.net/tools/tar/). Drag and drop your selection of images onto the page, and a tar file will be generated that you can download.\nYou can also use a tar tool to create the tar file yourself. \n\n### I want to download just 8 frames first and preload the rest of the images later. How can I do this?\n\nYou can set the `maxCachedImages` option to 8. The FastImageSequence will only preload and cache the first 8 images. You can then set the `maxCachedImages` option to a higher number to preload the rest of the images later.\nSee this [example](https://github.com/mediamonks/fast-image-sequence/blob/main/example/src/exampleStillImage.js) for more information.\n\n### I have an image sequence of low-res images and want to download a high-res image when the user stops at a frame. How can I do this?\n\nYou can set multiple sources using the `src` option. The FastImageSequence will try to load images from the first source in the array. If an image is not available yet, it will try to load it from the next source in the array, etc. Finally, the best matching available image will be rendered.\nBy setting a `timeout` option, you can control when the FastImageSequence should start loading an image. For example:\n\n```ts\nconst options = {\n  frames: 100,\n\n  src: [\n    {\n      // First try to display a highres image from an image URL\n      imageURL:        (index) =\u003e `path/to/your/image/sequence/highres_image${index}.jpg`,\n      maxCachedImages: 1,\n      timeout:         16, // only start loading an image if the same frame is visible for 16ms\n    },\n    {\n      // Default: serve a low res image from the sequence\n      imageURL:        (index) =\u003e `path/to/your/image/sequence/lowres_image${index}.jpg`,\n      maxCachedImages: 32,\n    },\n  ],\n\n  loop:      false,\n  objectFit: 'contain',\n};\n\nconst sequence = new FastImageSequence(containerElement, options);\n\n```\n\n### Can I download a tar file myself and use it with FastImageSequence?\n\nYes, you can download the tar file yourself and create a data URL from it. You can then use this data URL as the `tarURL` option. \nSee this [example](https://github.com/mediamonks/fast-image-sequence/blob/main/example/src/exampleLoadTar.js) for more information.\n\n\n## Building\n\nTo build fast-image-sequence, ensure that you have [Git](http://git-scm.com/downloads)\nand [Node.js](http://nodejs.org/) installed.\n\nClone a copy of the repo:\n\n```sh\ngit clone https://github.com/mediamonks/fast-image-sequence-renderer.git\n```\n\nChange to the fast-image-sequence-renderer directory:\n\n```sh\ncd fast-image-sequence-renderer\n```\n\nInstall dev dependencies:\n\n```sh\nnpm i\n```\n\nBuild package:\n\n```sh\nnpm run build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmediamonks%2Ffast-image-sequence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmediamonks%2Ffast-image-sequence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmediamonks%2Ffast-image-sequence/lists"}