videoshow

Simple utility for node.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:

Requirements

• 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

Installation

1npm install videoshow

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

1npm install -g videoshow

Usage

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.

1var videoshow = require('videoshow')
2
3var images = [
4  'step1.jpg',
5  'step2.jpg',
6  'step3.jpg',
7  'step4.jpg'
8]
9
10var videoOptions = {
11  fps: 25,
12  loop: 5, // seconds
13  transition: true,
14  transitionDuration: 1, // seconds
15  videoBitrate: 1024,
16  videoCodec: 'libx264',
17  size: '640x?',
18  audioBitrate: '128k',
19  audioChannels: 2,
20  format: 'mp4',
21  pixelFormat: 'yuv420p'
22}
23
24videoshow(images, videoOptions)
25  .audio('song.mp3')
26  .save('video.mp4')
27  .on('start', function (command) {
28    console.log('ffmpeg process started:', command)
29  })
30  .on('error', function (err, stdout, stderr) {
31    console.error('Error:', err)
32    console.error('ffmpeg stderr:', stderr)
33  })
34  .on('end', function (output) {
35    console.error('Video created in:', output)
36  })

Command-line interface

1$ videoshow --help

1Create video slideshow easily from images
2Usage: bin/videoshow [options]
3
4Options:
5  --help, -h       Show help
6  --config, -c     File path to JSON config file [required]
7  --audio, -a      Optional audio file path
8  --subtitles, -s  Path to .srt subtitles file
9  --input, -i      Add additional input to video
10  --output, -o     Output video file path
11  --size, -x       Video size resolution
12  --logo, -l       Path to logo image
13  --debug, -d      Enable debug mode in error case
14
15Examples:
16  bin/videoshow -c config.json video.mp4
17  bin/videoshow -c config.json --audio song.mp3 video.mp4
18  bin/videoshow -c config.json --audio song.mp3 --logo logo.png video.mp4

Example config.json file:

1{
2  "output": "video.mp4",
3  "options": {
4    "fps": 25,
5    "loop": 5,
6    "transition": true,
7    "transitionDuration": 1,
8    "videoBitrate": 1024,
9    "videoCodec": "libx264",
10    "size": "640x?",
11    "audioBitrate": "128k",
12    "audioChannels": 2,
13    "format": "mp4",
14    "subtitleStyles": {
15      "Fontname": "Verdana",
16      "Fontsize": "26",
17      "PrimaryColour": "11861244",
18      "SecondaryColour": "11861244",
19      "TertiaryColour": "11861244",
20      "BackColour": "-2147483640",
21      "Bold": "2",
22      "Italic": "0",
23      "BorderStyle": "2",
24      "Outline": "2",
25      "Shadow": "3",
26      "Alignment": "1",
27      "MarginL": "40",
28      "MarginR": "60",
29      "MarginV": "40"
30    }
31  },
32  "images": [
33    "./test/fixtures/step_1.png",
34    "./test/fixtures/step_2.png",
35    "./test/fixtures/step_3.png",
36    "./test/fixtures/step_4.png",
37    "./test/fixtures/step_5.png"
38  ]
39}

API

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.

1videoshow([ 'image1.jpg', 'image2.jpg', 'image3.jpg'])
2  .save('video.mp4')
3  .on('error', function () {})
4  .on('end', function () {})

images param could be a collection as well:

1videoshow([{
2    path: 'image1.jpg',
3    caption: 'Hello world as video subtitle'
4  }, {
5    path: 'image2.jpg',
6    caption: 'This is a sample subtitle',
7    loop: 10 // long caption
8  }])
9  .save('video.mp4')
10  .on('error', function () {})
11  .on('end', function () {})

Video options

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

Default options are:

1{
2  fps: 25,
3  loop: 5, // seconds
4  transition: true,
5  transitionDuration: 1,
6  captionDelay: 1000,
7  useSubRipSubtitles: false,
8  subtitleStyle: null,
9  videoBitrate: 1024,
10  videoCodec: 'libx264',
11  size: '640x?',
12  audioBitrate: '128k',
13  audioChannels: 2,
14  format: 'mp4'
15}

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

videoshow#image(image)

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

videoshow#subtitles(path)

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

videoshow#save(path)

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

videoshow#input(input)

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

videoshow#filter(filter)

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

videoshow#complexFilter(filter)

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

videoshow#loop(seconds)

Default image loop time in seconds. Default to 5

videoshow#size(resolution)

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

videoshow#aspect(aspect)

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

videoshow#options(options)

Alias: flags

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

videoshow#option(argument)

Alias: flag

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

videoshow#options(arguments)

Alias: flags

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

videoshow.VERSION

Type: string

Current package semantic version

videoshow.ffmpeg

Type: function

fluent-ffmpeg API constructor

License

MIT © Tomas Aparicio