Nautical Poseidon Mythology


    1.0.0 • Public • Published

    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


    npm i @teammanch/videoshow

    DownloadsWeekly Downloads






    Unpacked Size

    33.1 kB

    Total Files


    Last publish


    • teammanch