Generate multiple video encodes at varying sizes for responsive, HTML5 video applications.
This plugin requires Grunt
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
The "responsive_videos" task
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
name: "small"width: 320filter: ''poster: truename: "large"width: 1024filter: ''poster: false
An array of objects containing the sizes we want to resize our video to.
name is specified, then the file will be suffixed with this name. e.g. my-video-small.mp4
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.
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
name: "large"width: 1024poster: '00:00:02'
name: "large"width: 1024poster:fastseek: '00:00:02'
name: "large"width: 1024poster: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);
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.
- x264 encoding guide from FFMPEG
- VBR settings guide explains many of the important flags.
- MP4 examples
- WebM examples
The character used to separate the video filename from the size name.
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: 640poster: truewidth: 320poster: trueadditionalFlags:'-g': '3'
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.
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.
Custom size with filter
In this example, we specify a custom filtergraph to crop the video to a square.
- Generated .webm files in unit tests are returning different checksums on every run, making reliable test impossible. FFMpeg settings issue?
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.
- Bug Fix issue 12: ffmpeg-node missing from NPM.
- Enhancement issue 11: NPM ignores the massive test videos.
- 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.
- Better default WebM settings
- 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.
- Much smaller test media
- Dependency fix
- Initial Release
This plugin is heavily inspired by andismith's grunt-responsive-images