Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including gatsby-transformer-video with all npm packages installed. Try it out:

var gatsbyTransformerVideo = require("gatsby-transformer-video")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

gatsby-transformer-video v0.1.18

Convert videos into well supported formats via FFMPEG. Supports generating previews as well.


Convert videos via FFMPEG. Easily convert & host small videos on your own.

:warning: Converting videos might take a lot of time. Make sure to have an effective caching mechanism in place. See caching


  • Source: Works with nodes from gatsby-source-filesystem and gatsby-source-contentful
  • Defaults optimized for small files with decent quality and quick and seamless streaming
  • Supported codecs: h264, h265, VP9, WebP & gif
  • Several parameters to tweak the output: maxWidth/maxHeight, overlay, saturation, duration, fps, ...
  • Create video conversion profiles. Create a converter function using fluent-ffmpeg to unlock all FFMPEG features.
  • Take screenshots at any position of the video


npm i gatsby-transformer-video


To properly convert and analyze videos, this relies on ffmpeg and ffprobe. These will be downloaded automatically except you turn it off via configuration.

If you want to use your own version of ffmpeg and ffprobe, it should be compiled with at least the following flags enabled:

--enable-gpl --enable-nonfree --enable-libx264 --enable-libx265 --enable-libvpx --enable-libwebp --enable-libopus

Some operating systems may provide these FFMPEG via a package manager. Some may not include ffprobe when installing ffmpeg.

If you can't find a way to get ffmpeg with all requirements for your system, you can always compile it on your own:

How to link your custom binaries to this plugin

  • Provide the path to ffmpeg && ffprobe via GatsbyJS plugin configuration
  • Or set an environment variable ->
  • Or add the static binaries to any folder in your $PATH


Linux/Debian users might be able to: sudo apt-get install ffmpeg

Make sure you have ffprobe installed as well.


If you got brew installed, you can get FFMPEG including FFPROBE via:

brew tap homebrew-ffmpeg/ffmpeg
brew install homebrew-ffmpeg/ffmpeg/ffmpeg --with-fdk-aac --with-webp




const { resolve } = require(`path`)
const { platform } = require(`os`)
module.exports = {
  plugins: [
      resolve: `gatsby-transformer-video`,
      options: {
         * Set if FFMPEG & FFPROBE should be downloaded if they are not found locally.
         * Downloaded binaries are stored in `node_modules/.cache/gatsby-transformer-video-bins/`
         * Default: true
        downloadBinaries: false,
         * Optional: Pass your own binaries
         * Assumes you store your binaries in the following pattern:
         * ./bin/darwin/ffmpeg
         * ./bin/darwin/ffprobe
         * ./bin/linux/ffmpeg
         * ./bin/linux/ffprobe
         * ...
         * Default: null
        ffmpegPath: resolve(__dirname, "bin", platform(), "ffmpeg"),
        ffprobePath: resolve(__dirname, "bin", platform(), "ffprobe"),

        // Optional profiles for full fluent-ffmpeg access
        profiles: {
          sepia: {
            extension: `mp4`,
            converter: function({ ffmpegSession, videoStreamMetadata }) {
              // Example:
query {
  allFile {
    edges {
      node {
        videoGif(duration: 2, fps: 3, maxWidth: 300) {
          overlay: "gatsby.png"
          overlayX: "end"
          overlayY: "start"
          overlayPadding: 25
          screenshots: "0,50%" (See:
        ) {
          path #String
          absolutePath #String
          name #String
          ext #String
          codec #String
          formatName #String
          formatLongName #String
          startTime #Float
          duration #Float
          size #Int
          bitRate #Int
          screenshots #String
        videoProfile(profile: "yourProfileName") {
  allContentfulAsset {
    edges {
      node {
        # Same fields available as above


Generating videos take time. A lot. You should cache your results. Otherwise, you might not even be able to publish on your hosting platform.

This plugin stores all converted files in node_modules/.cache/gatsby-transformer-video/

Here is a list of plugins that can help you:

  • Netlify:
  • Via SFTP:
  • Gatsby Cloud should work well to store the generated files
  • We could write a caching plugin using a node p2p network like to eventually eliminate the need of a server for caching generated files
RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free