{"id":15064983,"url":"https://github.com/hashbite/gatsby-transformer-video","last_synced_at":"2025-04-10T13:09:16.861Z","repository":{"id":46194071,"uuid":"374413920","full_name":"hashbite/gatsby-transformer-video","owner":"hashbite","description":"Integrates FFMPEG with Gatsby","archived":false,"fork":false,"pushed_at":"2023-12-15T05:59:08.000Z","size":9419,"stargazers_count":8,"open_issues_count":9,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2024-10-30T04:28:52.691Z","etag":null,"topics":["ffmpeg","gatsbyjs","video"],"latest_commit_sha":null,"homepage":"https://gatsbytransformervideo.gatsbyjs.io/","language":"TypeScript","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/hashbite.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2021-06-06T16:48:12.000Z","updated_at":"2022-04-25T07:03:17.000Z","dependencies_parsed_at":"2024-06-19T09:41:45.064Z","dependency_job_id":null,"html_url":"https://github.com/hashbite/gatsby-transformer-video","commit_stats":{"total_commits":61,"total_committers":2,"mean_commits":30.5,"dds":"0.016393442622950838","last_synced_commit":"373c187afdd4517e0daf15ce7ccf6998e7db46d0"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashbite%2Fgatsby-transformer-video","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashbite%2Fgatsby-transformer-video/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashbite%2Fgatsby-transformer-video/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashbite%2Fgatsby-transformer-video/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hashbite","download_url":"https://codeload.github.com/hashbite/gatsby-transformer-video/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248224702,"owners_count":21068073,"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":["ffmpeg","gatsbyjs","video"],"created_at":"2024-09-25T00:28:58.696Z","updated_at":"2025-04-10T13:09:16.844Z","avatar_url":"https://github.com/hashbite.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gatsby-transformer-video\n\n\u003e Convert videos via FFMPEG. Easily convert \u0026 host **small** videos on your own.\n\n[![NPM Version Badge](https://badgen.net/npm/v/gatsby-transformer-video)](https://www.npmjs.com/package/gatsby-transformer-video)\n[![NPM Monthly Downloads Badge](https://badgen.net/npm/dm/gatsby-transformer-video)](https://www.npmjs.com/package/gatsby-transformer-video)\n[![Github Check Badge](https://badgen.net/github/checks/hashbite/gatsby-transformer-video/main)](https://github.com/hashbite/gatsby-transformer-video/actions)\n[![License Badge](https://badgen.net/npm/license/gatsby-transformer-video)](https://github.com/hashbite/gatsby-transformer-video/blob/main/LICENSE)\n\n**This is a beta plugin and supports Gatsby v4.1.4 only. The videos will work fine on your website, we are working hard on improving the implementation code and to provide new features.**\n\n:warning::warning::warning: Converting videos might take a lot of time. Make sure to have an effective caching mechanism in place. See [caching](#caching)\n\n## Features\n\n- Source: Works with nodes from `gatsby-source-filesystem` and `gatsby-source-contentful`\n- Defaults optimized for small files with decent quality and quick and seamless streaming\n- Supported codecs: h264, h265, VP9, WebP \u0026 gif\n- Several parameters to tweak the output: maxWidth/maxHeight, overlay, saturation, duration, fps, ...\n- Create video conversion profiles. Create a converter function using `fluent-ffmpeg` to unlock all FFMPEG features.\n- Take screenshots at any position of the video\n\n## Usage example\n\nhttps://github.com/hashbite/gatsby-transformer-video/tree/main/packages/example\n\n## Installation\n\n```sh\nnpm i gatsby-transformer-video gatsby-plugin-sharp gatsby-source-filesystem\n```\n\n## Prerequisites\n\nTo properly convert and analyze videos, this relies on `ffmpeg` and `ffprobe`. If these are not available for your node process, they will be **downloaded automatically** and cached to your disk.\n\nIf you want to use your own version of `ffmpeg` and `ffprobe`, it should be compiled with at least the following flags enabled:\n\n`--enable-gpl --enable-nonfree --enable-libx264 --enable-libx265 --enable-libvpx --enable-libwebp --enable-libopus`\n\nSome operating systems may provide these FFMPEG via a package manager. Some may **not include** `ffprobe` when installing `ffmpeg`.\n\nIf you can't find a way to get ffmpeg with all requirements for your system, you can always compile it on your own: https://trac.ffmpeg.org/wiki/CompilationGuide\n\n**How to link your custom binaries to this plugin**\n\n- Provide the path to ffmpeg \u0026\u0026 ffprobe via GatsbyJS plugin configuration\n- Or set an environment variable -\u003e https://github.com/fluent-ffmpeg/node-fluent-ffmpeg#ffmpeg-and-ffprobe\n- Or add the static binaries to any folder in your `$PATH`\n\n### Linux\n\nLinux/Debian users might be able to: `sudo apt-get install ffmpeg`\n\nMake sure you have `ffprobe` installed as well.\n\n### OSX\n\nIf you got [brew](https://brew.sh/) installed, you can get FFMPEG including FFPROBE via:\n\n```sh\nbrew tap homebrew-ffmpeg/ffmpeg\nbrew install homebrew-ffmpeg/ffmpeg/ffmpeg --with-fdk-aac --with-webp\n```\n\n\u003csub\u003e(Source: https://trac.ffmpeg.org/wiki/CompilationGuide/macOS#ffmpegthroughHomebrew)\u003c/sub\u003e\n\n## Usage\n\n### Configuration via `gatsby-config.js`\n\nThe plugin works fine in most cases without any configuration options set.\n\nHere is a full list of available, optional, options:\n\n```js\nconst { resolve } = require(`path`)\nconst { platform } = require(`os`)\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-transformer-video`,\n      options: {\n        /**\n         * Alternative directory for the video cache\n         * Default: '.cache-video'\n         */\n        cacheDirectory: resolve('node_modules', '.cache-video'),\n\n        /**\n         * Alternative directory for the ffmpeg binaries\n         * Default: resolve(`.bin`, `gatsby-transformer-video`)\n         */\n        cacheDirectoryBin: resolve('node_modules', '.cache-video-bin'),\n\n        /**\n         * Set if FFMPEG \u0026 FFPROBE should be downloaded if they are not found locally\n         *\n         * Downloaded binaries are stored in `.bin/gatsby-transformer-video/`\n         *\n         * Default: true\n         */\n        downloadBinaries: false,\n\n        /**\n         * Pass your own FFMPEG \u0026\u0026 FFPROBE binaries\n         *\n         * Assumes you store your binaries in the following pattern:\n         * ./bin/darwin/ffmpeg\n         * ./bin/darwin/ffprobe\n         * ./bin/linux/ffmpeg\n         * ./bin/linux/ffprobe\n         * ...\n         *\n         * Default: null\n         */\n        ffmpegPath: resolve(__dirname, 'bin', platform(), 'ffmpeg'),\n        ffprobePath: resolve(__dirname, 'bin', platform(), 'ffprobe'),\n\n        /**\n         * Define custom profiles to convert videos with full fluent-ffmpeg access\n         *\n         * Learn more: https://github.com/fluent-ffmpeg/node-fluent-ffmpeg\n         */\n        profiles: {\n          sepia: {\n            extension: `mp4`,\n            converter: function({ ffmpegSession, videoStreamMetadata }) {\n              // Example:\n              // https://github.com/hashbite/gatsby-transformer-video/blob/main/packages/example/gatsby-config.js#L24-L55\n            },\n          },\n        },\n      },\n    },\n  ],\n}\n```\n\n### GraphQL Query\n\nCheck out your GraphiQL interface for all available options: http://localhost:8000/___graphql\n\n```graphql\nquery {\n  allFile {\n    edges {\n      node {\n        id\n        videoGif(duration: 2, fps: 3, maxWidth: 300) {\n          path\n        }\n        videoH264(\n          overlay: \"gatsby.png\"\n          overlayX: \"end\"\n          overlayY: \"start\"\n          overlayPadding: 25\n          screenshots: \"0,50%\" (See: https://github.com/fluent-ffmpeg/node-fluent-ffmpeg#screenshotsoptions-dirname-generate-thumbnails)\n        ) {\n          path #String\n          absolutePath #String\n          name #String\n          ext #String\n          formatName #String\n          formatLongName #String\n          startTime #Float\n          duration #Float\n          size #Int\n          bitRate #Int\n          width #Int\n          height #Int\n          aspectRatio #Float\n        }\n        videoProfile(profile: \"yourProfileName\") {\n          path\n        }\n      }\n    }\n  }\n  allContentfulAsset {\n    edges {\n      node {\n        # Same fields available as above\n      }\n    }\n  }\n}\n```\n\n### Rendering your videos\n\n- Plain implementation: https://github.com/hashbite/gatsby-transformer-video/blob/main/packages/example/src/pages/index.tsx\n- We plan to prove a component for this: https://github.com/hashbite/gatsby-transformer-video/issues/8\n\n## Caching\n\nGenerating videos take time. A lot. You should cache your results. Otherwise, you might not even be able to publish on your hosting platform.\n\nOur `Rolling Cache` implementation will avoid extra video conversions even when you clear your GatsbyJS cache. The cache will be regenerated regularly to ensure stale files are removed from the cache.\n\nYou need to cache the `cacheDirectory` to make this work. Consider cachine the `cacheDirectoryBin` directory if your build platform does not provide FFMPEG \u0026 FFPROBE.\n\n### Building your website on Gatsby Cloud, Netlify and others\n\nIf your build setup does not allow you to cache additional folders, you can abuse their caching of the `node_modules` folder. To do so, tell the cache to store files in `node_modules` via  `cacheDirectory` and `cacheDirectoryBin`:\n\n```js\nconst { resolve } = require(`path`)\nconst { platform } = require(`os`)\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-transformer-video`,\n      options: {\n        cacheDirectory: resolve('node_modules', '.cache-video'),\n        cacheDirectoryBin: resolve('node_modules', '.cache-video-bin'),\n      },\n    },\n  ],\n}\n```\n\n### Plugins that might help with caching:\n\n- Netlify: https://www.gatsbyjs.org/packages/gatsby-plugin-netlify-cache/\n- Via SFTP: https://www.gatsbyjs.org/packages/gatsby-plugin-sftp-cache/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhashbite%2Fgatsby-transformer-video","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhashbite%2Fgatsby-transformer-video","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhashbite%2Fgatsby-transformer-video/lists"}