Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    grunt-responsive-videospublic

    grunt-responsive-videos

    Generate multiple video encodes at varying sizes for responsive, HTML5 video applications.

    Getting Started

    This plugin requires Grunt ~0.4.1

    If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

    npm install grunt-responsive-videos --save-dev

    Additionally, this plugin requries FFMpeg with libx264 and libvpx to encode .mp4 and .webm, which are common HTML5 codecs, and required for the unit tests.

    brew install ffmpeg --with-libvorbis --with-nonfree --with-gpl --with-libvpx --with-pthreads --with-libx264 --with-libfaac --with-theora --with-libogg

    Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

    grunt.loadNpmTasks('grunt-responsive-videos');

    The "responsive_videos" task

    Overview

    The responsive_videos task will take source video and generate any number of output resolutions in any codec supported by FFMPEG.

    In your project's Gruntfile, add a section named responsive_videos to the data object passed into grunt.initConfig().

    grunt.initConfig({
      responsive_videos: {
        myTask:{
          options: {
            // Task-specific options go here. 
          },
          files[
          ]
        }
      },
    })

    Options

    options.sizes

    Type: Array

    Default value:

    [{
      name: "small",
      width: 320,
      filter: '',
      poster: true
    },{
      name: "large",
      width: 1024,
      filter: '',
      poster: false
    }]

    An array of objects containing the sizes we want to resize our video to.

    If a name is specified, then the file will be suffixed with this name. e.g. my-video-small.mp4

    If a name is not specified, then the file will be suffixed with the width. e.g. my-video-320.jpg

    filter is used when custom filtergraphs are needed, like for cropping. The width propety will only be used for naming purpose if a filter is specified.

    If poster is true, create an image from the first frame of the video at this output size. e.g. my-video-320.jpg.

    The poster option may also be used to seek to a particular time, using FFMPEG's fastseek or accurateseek options

    fastseek like:

    {
      name: "large",
      width: 1024,
      poster: '00:00:02'
    }

    or

    {
      name: "large",
      width: 1024,
      poster: {
        fastseek: '00:00:02'
      }
    }

    accurateseek like:

    {
      name: "large",
      width: 1024,
      poster: {
        accurateseek: '00:00:02'
      }

    Poster seek time can be in "HH:MM:SS" format (example: "00:00:05" for 5 seconds) or "S" (example: "5", for 5 seconds);

    options.encodes

    Type: Array

    Default value:

    [{
      webm: [
          {'-vcodec': 'libvpx'},
          {'-acodec': 'libvorbis'},
          {'-q:a': '100'},
          {'-quality': 'good'},
          {'-cpu-used': '0'},
          {'-b:v': '500k'},
          {'-qmax': '42'},
          {'-maxrate': '500k'},
          {'-bufsize': '1000k'},
          {'-threads': '0'}
      ],
      mp4: [
          {'-vcodec':'libx264'},
          {'-acodec': 'libfaac'},
          {'-pix_fmt': 'yuv420p'},
          {'-q:v': '4'},
          {'-q:a': '100'},
          {'-threads': '0'}
      ]
      }]

    An array of objects containing the codecs you'd like to produce. The keys are used as the extension, and the array of objects will be converted to flags passed into FFMpeg.

    The above are the defaults for an encode job and should give reasonable results for HTML5 video.

    Encode Resources

    options.separator

    Type: String Default value: -

    The character used to separate the video filename from the size name.

    options.additionalFlags

    Type: Array

    Default value:

    [] 

    An array of of objects, where the objects will be converted to flags passed into FFMpeg for all encodes. This is an easy way to globally add settings to the default encode settings, or to add settings to custom encodes without re-specifying duplicate settings per encode.

    In this example, two custom video sizes will be generated using the default encodes and settings, with the addition of -g 3 flag passed to FFMpeg.

    options: {
        sizes: [{
            width: 640,
            poster: true
        },{
            width: 320,
            poster: true
        }],
        additionalFlags: [
            {'-g': '3'}
        ]
    }

    Usage Examples

    Default Options

    The default options will produce a .mp4 and a .webm with an poster image at 320px and 640px wide. They will be named my-video-small.ext and my-video-large.ext.

    grunt.initConfig({
      responsive_videos: {
        myTask{
          options: {},
          files: {
            ...
          }
        }
      },
    })

    Custom Option Examples

    Customized encode and size settings

    In this example, we specify custom sizes and a source path. We'll only generate .webm files and poster images at 320px wide, and we'll not using custom naming, falling back to -320.web names instead of -small.webm, etc.

    grunt.initConfig({
      responsive_videos: {
        myTask: {
          options: {
            sizes: [{
              width: 320,
              poster: true
            }],
            encodes:[{
              webm: [
                {'-vcodec': 'libvpx'},
                {'-acodec': 'libvorbis'},
                {'-crf': '12'},
                {'-b:v': '1.5M',},
                {'-q:a': '100'}
              ]
            }]
          },
          files: [{
            expand: true,
            src: ['video/**.{mov,mp4}'],
            cwd: 'assets/',
            dest: 'tmp/'
          }]
        }
      },
    })
    Custom size with filter

    In this example, we specify a custom filtergraph to crop the video to a square.

    grunt.initConfig({
      responsive_videos: {
        myTask: {
          options: {
            sizes: [{
              width: 360,
              filter: 'scale=640:trunc(ow/a/2)*2,crop=360:360:140:0',
              poster: true
            }]
          },
          files: [{
            expand: true,
            src: ['*.{mov,mp4}'],
            cwd: srcVideos,
            dest: tmpFolder
          }]
        }
      },
    })

    Known Issues

    • Generated .webm files in unit tests are returning different checksums on every run, making reliable test impossible. FFMpeg settings issue?

    Contributing

    In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

    Release History

    0.1.3

    • Bug Fix issue 12: ffmpeg-node missing from NPM.

    0.1.2

    • Enhancement issue 11: NPM ignores the massive test videos.

    0.1.1

    • Enhancement issue 7: Added the ability to pass custom filtergraphs and globally apply additional encode flags. Thanks to @albertsun.
    • Fixed: Test encoded media was no longer valid.

    0.1.0

    • Better default WebM settings

    0.0.4

    • Enhancement issue 3: More robust poster options. Thanks to @johncmckim.
    • Enhancement: --debug logs
    • Fixed issue 5: Occasional zero byte h.246 encodes.
    • Fixed issue 4: Freezing on some task re-run.

    0.0.3

    • Much smaller test media

    0.0.2

    • Dependency fix

    0.0.1

    • Initial Release

    Additional Credit

    This plugin is heavily inspired by andismith's grunt-responsive-images

    Big Buck Bunny trailer in test assets is (c) copyright 2008, Blender Foundation. It is released under the Creative Commons Attribution 3.0 license.

    Hot air ballon ride over Cappadocia, Turkey in test assets is (c) copyright 2012, Josh Williams. It is released under the Creative Commons Attribution 3.0 license.

    install

    npm i grunt-responsive-videos

    Downloadsweekly downloads

    35

    version

    0.1.3

    license

    none

    repository

    github.com

    last publish

    collaborators

    • avatar