Awesome Open Source
Awesome Open Source

videoshow Build Status Code Climate NPM

Simple utility for node/io.js to create straightforward video slideshows based on images using ffmpeg, with additional features such as audio, subtitles and fade in/out transitions between slides.

To getting started you can take a look to the examples, programmatic API and command-line interface

videoshow is used in production rendering thousands of videos per month.

Click on the image to see an example video generated by videoshow:


  • ffmpeg with additional compilation flags --enable-libass --enable-libmp3lame

You can download static builds of ffmpeg from here.

If you want to use videoshow in Heroku, you could use the ffmpeg2 buildpack


npm install videoshow

For command-line usage, install it as global package:

npm install -g videoshow


NOTE: images must all have the same dimensions.

Below you have an example script generating a video based on images and audio.

Take a look to the programmatic API and examples for more usage details.

var videoshow = require('videoshow')

var images = [

var videoOptions = {
  fps: 25,
  loop: 5, // seconds
  transition: true,
  transitionDuration: 1, // seconds
  videoBitrate: 1024,
  videoCodec: 'libx264',
  size: '640x?',
  audioBitrate: '128k',
  audioChannels: 2,
  format: 'mp4',
  pixelFormat: 'yuv420p'

videoshow(images, videoOptions)
  .on('start', function (command) {
    console.log('ffmpeg process started:', command)
  .on('error', function (err, stdout, stderr) {
    console.error('Error:', err)
    console.error('ffmpeg stderr:', stderr)
  .on('end', function (output) {
    console.error('Video created in:', output)

Command-line interface

$ videoshow --help
Create video slideshow easily from images
Usage: bin/videoshow [options]

  --help, -h       Show help
  --config, -c     File path to JSON config file [required]
  --audio, -a      Optional audio file path
  --subtitles, -s  Path to .srt subtitles file
  --input, -i      Add additional input to video
  --output, -o     Output video file path
  --size, -x       Video size resolution
  --logo, -l       Path to logo image
  --debug, -d      Enable debug mode in error case

  bin/videoshow -c config.json video.mp4
  bin/videoshow -c config.json --audio song.mp3 video.mp4
  bin/videoshow -c config.json --audio song.mp3 --logo logo.png video.mp4

Example config.json file:

  "output": "video.mp4",
  "options": {
    "fps": 25,
    "loop": 5,
    "transition": true,
    "transitionDuration": 1,
    "videoBitrate": 1024,
    "videoCodec": "libx264",
    "size": "640x?",
    "audioBitrate": "128k",
    "audioChannels": 2,
    "format": "mp4",
    "subtitleStyles": {
      "Fontname": "Verdana",
      "Fontsize": "26",
      "PrimaryColour": "11861244",
      "SecondaryColour": "11861244",
      "TertiaryColour": "11861244",
      "BackColour": "-2147483640",
      "Bold": "2",
      "Italic": "0",
      "BorderStyle": "2",
      "Outline": "2",
      "Shadow": "3",
      "Alignment": "1",
      "MarginL": "40",
      "MarginR": "60",
      "MarginV": "40"
  "images": [


videoshow(images, [ options ])

Return: Videoshow

Videoshow constructor. You should pass an array<string> or array<object> or array<ReadableStream> with the desired images, and optionally passing the video render options object per each image.

Image formats supported are: jpg, png or bmp.

videoshow([ 'image1.jpg', 'image2.jpg', 'image3.jpg'])
  .on('error', function () {})
  .on('end', function () {})

images param could be a collection as well:

    path: 'image1.jpg',
    caption: 'Hello world as video subtitle'
  }, {
    path: 'image2.jpg',
    caption: 'This is a sample subtitle',
    loop: 10 // long caption
  .on('error', function () {})
  .on('end', function () {})

Video options

You can define as option any method name allowed by fluent-ffmpeg

Default options are:

  fps: 25,
  loop: 5, // seconds
  transition: true,
  transitionDuration: 1,
  captionDelay: 1000,
  useSubRipSubtitles: false,
  subtitleStyle: null,
  videoBitrate: 1024,
  videoCodec: 'libx264',
  size: '640x?',
  audioBitrate: '128k',
  audioChannels: 2,
  format: 'mp4'

Options details:

  • captionDelay number - Miliseconds to delay the show/hide of the caption. Default to 1000
  • useSubRipSubtitles boolean - Use SubRip subtitles format. It uses by default SSA/ASS. Default false
  • subtitleStyle object - SSA/ASS subtitles style. See substation.js and fixture file for allowed params

Image options

  • path string - File path to image
  • loop number - Image slide duration in seconds. Default to 5
  • transition boolean - Enable fade in/out transition for the current image
  • transitionDuration number - Fade in/out transition duration in seconds. Default to 1
  • transitionColor string - Fade in/out transition background color. Default to black. See supported colors
  • filters array<string|object> - Add custom ffmpeg video filters to the image slide.
  • disableFadeOut boolean - If transition is enable, disable the fade out. Default false
  • disableFadeIn boolean - If transition is enable, disable the fade in. Default false
  • caption string - Caption text as subtitle. It allows a limited set of HTML tags. See Subrip
  • captionDelay number - Miliseconds to delay the show/hide of the caption. Default to 1000
  • captionStart number - Miliseconds to start the caption. Default to 1000
  • captionEnd number - Miliseconds to remove the caption. Default to loop - 1000
  • logo string - Path to logo image. See logo() method


Push an image to the video. You can pass an string as path to the image, or a plain object with image options

videoshow#audio(path [, params ])

Define the audio file path to use. It supports multiple formats and codecs such as acc, mp3 or ogg

Supported params:

  • delay number - Delay audio start in seconds. Default to 0 seconds
  • fade boolean - Enable audio fade in/out effect. Default true

videoshow#logo(path [, params ])

Add a custom image as logo in the left-upper corner by default. You can customize the position by x/y axis. It must be a png or jpeg image

Supported params:

  • start number - Video second to show the logo. Default 5 seconds
  • end number - Video second to remove the logo. Default totalLength - 5 seconds
  • xAxis number - Logo x axis position. Default 10
  • yAxis number - Logo y axis position. Default 10


Define the SubRip subtitles or SubStation Alpha (SSA/ASS) file path to load. It should be a .str or .ass file respectively

See fixtures for examples


Return: EventEmitter Alias: render

Render and write in disk the resultant video in the given path

Supported events for subscription:

  • start cmd - Fired when ffmpeg process started
  • error error, stdout, stderr - Fired when transcoding error happens
  • progress data - Fired with transcoding progress information
  • codecData codec - Fired when input codec data is available
  • end videoPath - Fired when the process finish successfully

For more information, see the ffmpeg docs


Add input file to video. By default you don't need to call this method


Add a custom video filter to the video. See the docs


Add a custom complex filter to the video. See the docs


Default image loop time in seconds. Default to 5


Video size resolution. Default to 640x?. See the docs


Video aspect ration. Default autocalculated from video size param. See the docs


Alias: flags

Add a set of video output options as command-line flag. options argument should be an array. See the docs


Alias: flag

Add a custom output option as command-line flag to pass to ffmpeg


Alias: flags

Add multiple output options as command-line flags to pass to ffmpeg. The argument must be an array


Type: string

Current package semantic version


Type: function

fluent-ffmpeg API constructor


MIT © Tomas Aparicio

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
javascript (61,895
video (633
music (448
ffmpeg (226
images (138
rendering (131
mp3 (92
presentation (71
slideshow (55
subtitle (31

Find Open Source By Browsing 7,000 Topics Across 59 Categories