{"id":13515373,"url":"https://github.com/h2non/videoshow","last_synced_at":"2025-04-14T08:17:05.700Z","repository":{"id":26975174,"uuid":"30438752","full_name":"h2non/videoshow","owner":"h2non","description":"Simple node.js utility to create video slideshows from images with optional audio and visual effects using ffmpeg","archived":false,"fork":false,"pushed_at":"2023-12-17T15:53:00.000Z","size":9173,"stargazers_count":887,"open_issues_count":54,"forks_count":162,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-04-14T08:16:58.812Z","etag":null,"topics":["ffmpeg","images","mp3","music","presentation","rendering","slideshow","subtitle","video"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/h2non.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-02-07T00:02:36.000Z","updated_at":"2025-04-07T12:51:56.000Z","dependencies_parsed_at":"2023-12-17T16:47:09.386Z","dependency_job_id":null,"html_url":"https://github.com/h2non/videoshow","commit_stats":{"total_commits":129,"total_committers":12,"mean_commits":10.75,"dds":"0.13178294573643412","last_synced_commit":"84b16f9b00f3a1eda1c1bb31b2778844c679e6b3"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h2non%2Fvideoshow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h2non%2Fvideoshow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h2non%2Fvideoshow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h2non%2Fvideoshow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/h2non","download_url":"https://codeload.github.com/h2non/videoshow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248843999,"owners_count":21170499,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ffmpeg","images","mp3","music","presentation","rendering","slideshow","subtitle","video"],"created_at":"2024-08-01T05:01:10.326Z","updated_at":"2025-04-14T08:17:05.670Z","avatar_url":"https://github.com/h2non.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"# videoshow [![Code Climate](https://codeclimate.com/github/h2non/videoshow/badges/gpa.svg)](https://codeclimate.com/github/h2non/videoshow) [![NPM](https://img.shields.io/npm/v/videoshow.svg)][npm]\n\n\u003cimg src=\"https://github.com/h2non/videoshow/blob/master/test/fixtures/norris.gif\" width=\"180\" align=\"right\" /\u003e\n\nSimple utility for **node.js** to **create straightforward video slideshows based on images** using [ffmpeg](http://ffmpeg.org), with additional features such as **audio**, **subtitles** and **fade in/out transitions** between slides.\n\nTo getting started you can take a look to the [examples](https://github.com/h2non/videoshow/tree/master/examples), [programmatic API](#api) and [command-line](#command-line-interface) interface\n\nvideoshow is used in production rendering thousands of videos per month. \n\nClick on the image to see an example video generated by `videoshow`:\n\n\u003ca href=\"https://www.youtube.com/watch?v=CSXHNHSaLbc\"\u003e\n\u003cimg src=\"https://github.com/h2non/videoshow/raw/master/test/fixtures/video.jpg\" width=\"100%\" align=\"center\" /\u003e\n\u003c/a\u003e\n\n## Requirements\n\n- **[ffmpeg](http://ffmpeg.org)** with additional compilation flags `--enable-libass --enable-libmp3lame`\n\nYou can download static builds of ffmpeg from [here](http://johnvansickle.com/ffmpeg/).\n\nIf you want to use videoshow in Heroku, you could use the [ffmpeg2](https://github.com/h2non/heroku-buildpack-ffmpeg2) buildpack\n\n## Installation\n\n```bash\nnpm install videoshow\n```\n\nFor command-line usage, install it as global package:\n```bash\nnpm install -g videoshow\n```\n\n## Usage\n\n**NOTE**: images must all have the same dimensions.\n\nBelow you have an example script generating a video based on images and audio.\n\nTake a look to the [programmatic API](#api) and [examples](examples/) for more usage details.\n\n```js\nvar videoshow = require('videoshow')\n\nvar images = [\n  'step1.jpg',\n  'step2.jpg',\n  'step3.jpg',\n  'step4.jpg'\n]\n\nvar videoOptions = {\n  fps: 25,\n  loop: 5, // seconds\n  transition: true,\n  transitionDuration: 1, // seconds\n  videoBitrate: 1024,\n  videoCodec: 'libx264',\n  size: '640x?',\n  audioBitrate: '128k',\n  audioChannels: 2,\n  format: 'mp4',\n  pixelFormat: 'yuv420p'\n}\n\nvideoshow(images, videoOptions)\n  .audio('song.mp3')\n  .save('video.mp4')\n  .on('start', function (command) {\n    console.log('ffmpeg process started:', command)\n  })\n  .on('error', function (err, stdout, stderr) {\n    console.error('Error:', err)\n    console.error('ffmpeg stderr:', stderr)\n  })\n  .on('end', function (output) {\n    console.error('Video created in:', output)\n  })\n```\n\n## Command-line interface\n\n```bash\n$ videoshow --help\n```\n\n```bash\nCreate video slideshow easily from images\nUsage: bin/videoshow [options]\n\nOptions:\n  --help, -h       Show help\n  --config, -c     File path to JSON config file [required]\n  --audio, -a      Optional audio file path\n  --subtitles, -s  Path to .srt subtitles file\n  --input, -i      Add additional input to video\n  --output, -o     Output video file path\n  --size, -x       Video size resolution\n  --logo, -l       Path to logo image\n  --debug, -d      Enable debug mode in error case\n\nExamples:\n  bin/videoshow -c config.json video.mp4\n  bin/videoshow -c config.json --audio song.mp3 video.mp4\n  bin/videoshow -c config.json --audio song.mp3 --logo logo.png video.mp4\n```\n\nExample `config.json` file:\n\n```json\n{\n  \"output\": \"video.mp4\",\n  \"options\": {\n    \"fps\": 25,\n    \"loop\": 5,\n    \"transition\": true,\n    \"transitionDuration\": 1,\n    \"videoBitrate\": 1024,\n    \"videoCodec\": \"libx264\",\n    \"size\": \"640x?\",\n    \"audioBitrate\": \"128k\",\n    \"audioChannels\": 2,\n    \"format\": \"mp4\",\n    \"subtitleStyles\": {\n      \"Fontname\": \"Verdana\",\n      \"Fontsize\": \"26\",\n      \"PrimaryColour\": \"11861244\",\n      \"SecondaryColour\": \"11861244\",\n      \"TertiaryColour\": \"11861244\",\n      \"BackColour\": \"-2147483640\",\n      \"Bold\": \"2\",\n      \"Italic\": \"0\",\n      \"BorderStyle\": \"2\",\n      \"Outline\": \"2\",\n      \"Shadow\": \"3\",\n      \"Alignment\": \"1\",\n      \"MarginL\": \"40\",\n      \"MarginR\": \"60\",\n      \"MarginV\": \"40\"\n    }\n  },\n  \"images\": [\n    \"./test/fixtures/step_1.png\",\n    \"./test/fixtures/step_2.png\",\n    \"./test/fixtures/step_3.png\",\n    \"./test/fixtures/step_4.png\",\n    \"./test/fixtures/step_5.png\"\n  ]\n}\n```\n\n## API\n\n### `videoshow(images, [ options ])`\nReturn: `Videoshow`\n\nVideoshow constructor. You should pass an `array\u003cstring\u003e` or `array\u003cobject\u003e` or `array\u003cReadableStream\u003e` with the desired images,\nand optionally passing the video render `options` object per each image.\n\nImage formats supported are: `jpg`, `png` or `bmp`.\n\n```js\nvideoshow([ 'image1.jpg', 'image2.jpg', 'image3.jpg'])\n  .save('video.mp4')\n  .on('error', function () {})\n  .on('end', function () {})\n```\n\n`images` param could be a collection as well:\n```js\nvideoshow([{\n    path: 'image1.jpg',\n    caption: 'Hello world as video subtitle'\n  }, {\n    path: 'image2.jpg',\n    caption: 'This is a sample subtitle',\n    loop: 10 // long caption\n  }])\n  .save('video.mp4')\n  .on('error', function () {})\n  .on('end', function () {})\n```\n\n#### Video options\n\nYou can define as option any method name allowed by [fluent-ffmpeg][ffmpeg-api]\n\nDefault options are:\n```js\n{\n  fps: 25,\n  loop: 5, // seconds\n  transition: true,\n  transitionDuration: 1,\n  captionDelay: 1000,\n  useSubRipSubtitles: false,\n  subtitleStyle: null,\n  videoBitrate: 1024,\n  videoCodec: 'libx264',\n  size: '640x?',\n  audioBitrate: '128k',\n  audioChannels: 2,\n  format: 'mp4'\n}\n```\n\nOptions details:\n\n- **captionDelay** `number` - Miliseconds to delay the show/hide of the caption. Default to `1000`\n- **useSubRipSubtitles** `boolean` - Use SubRip subtitles format. It uses by default [SSA/ASS](http://en.wikipedia.org/wiki/SubStation_Alpha). Default `false`\n- **subtitleStyle** `object` - SSA/ASS subtitles style. See [substation.js](https://github.com/h2non/videoshow/blob/master/lib/substation.js#L49) and [fixture file](https://github.com/h2non/videoshow/blob/master/test/fixtures/subtitles.ass) for allowed params\n\n#### Image options\n\n- **path** `string` - File path to image\n- **loop** `number` - Image slide duration in **seconds**. Default to `5`\n- **transition** `boolean` - Enable fade in/out transition for the current image\n- **transitionDuration** `number` - Fade in/out transition duration in **seconds**. Default to `1`\n- **transitionColor** `string` - Fade in/out transition background color. Default to `black`. See [supported colors][ffmpeg-colors]\n- **filters** `array\u003cstring|object\u003e` - Add custom ffmpeg video filters to the image slide.\n- **disableFadeOut** `boolean` - If transition is enable, disable the fade out. Default `false`\n- **disableFadeIn** `boolean` - If transition is enable, disable the fade in. Default `false`\n- **caption** `string` - Caption text as subtitle. It allows a limited set of HTML tags. See [Subrip][subrip]\n- **captionDelay** `number` - Miliseconds to delay the show/hide of the caption. Default to `1000`\n- **captionStart** `number` - Miliseconds to start the caption. Default to `1000`\n- **captionEnd** `number` - Miliseconds to remove the caption. Default to `loop - 1000`\n- **logo** `string` - Path to logo image. See `logo()` method\n\n#### `videoshow#image(image)`\n\nPush an image to the video. You can pass an `string` as path to the image,\nor a plain `object` with [image options](#supported-image-options)\n\n#### `videoshow#audio(path [, params ])`\n\nDefine the audio file path to use.\nIt supports multiple formats and codecs such as `acc`, `mp3` or `ogg`\n\n**Supported params**:\n\n- **delay** `number` - Delay audio start in seconds. Default to `0` seconds\n- **fade** `boolean` - Enable audio fade in/out effect. Default `true`\n\n#### `videoshow#logo(path [, params ])`\n\nAdd a custom image as logo in the left-upper corner by default. You can customize the position by `x/y` axis.\nIt must be a `png` or `jpeg` image\n\n**Supported params**:\n\n- **start** `number` - Video second to show the logo. Default `5` seconds\n- **end** `number` - Video second to remove  the logo. Default `totalLength - 5` seconds\n- **xAxis** `number` - Logo `x` axis position. Default `10`\n- **yAxis** `number` - Logo `y` axis position. Default `10`\n\n#### `videoshow#subtitles(path)`\n\nDefine the [SubRip subtitles][subrip] or [SubStation Alpha](http://en.wikipedia.org/wiki/SubStation_Alpha) (SSA/ASS)\nfile path to load. It should be a `.str` or `.ass` file respectively\n\nSee [fixtures](https://github.com/h2non/videoshow/blob/master/test/fixtures/subtitles.srt) for examples\n\n#### `videoshow#save(path)`\nReturn: `EventEmitter` Alias: `render`\n\nRender and write in disk the resultant video in the given path\n\nSupported events for subscription:\n\n- **start** `cmd` - Fired when ffmpeg process started\n- **error** `error, stdout, stderr` - Fired when transcoding error happens\n- **progress** `data` - Fired with transcoding progress information\n- **codecData** `codec` - Fired when input codec data is available\n- **end** `videoPath` - Fired when the process finish successfully\n\nFor more information, see the [ffmpeg docs](https://github.com/fluent-ffmpeg/node-fluent-ffmpeg#setting-event-handlers)\n\n#### `videoshow#input(input)`\n\nAdd input file to video. By default you don't need to call this method\n\n#### `videoshow#filter(filter)`\n\nAdd a custom video filter to the video. See the [docs](https://github.com/fluent-ffmpeg/node-fluent-ffmpeg#videofiltersfilter-add-custom-video-filters)\n\n#### `videoshow#complexFilter(filter)`\n\nAdd a custom complex filter to the video. See the [docs](https://github.com/fluent-ffmpeg/node-fluent-ffmpeg#complexfilterfilters-map-set-complex-filtergraph)\n\n#### `videoshow#loop(seconds)`\n\nDefault image loop time in seconds. Default to `5`\n\n#### `videoshow#size(resolution)`\n\nVideo size resolution. Default to `640x?`.\nSee the [docs](https://github.com/fluent-ffmpeg/node-fluent-ffmpeg#sizesize-set-output-frame-size)\n\n#### `videoshow#aspect(aspect)`\n\nVideo aspect ration. Default autocalculated from video `size` param.\nSee the [docs](https://github.com/fluent-ffmpeg/node-fluent-ffmpeg#aspectaspect-set-output-frame-aspect-ratio)\n\n#### `videoshow#options(options)`\nAlias: `flags`\n\nAdd a set of video output options as command-line flag.\n`options` argument should be an array.\nSee the [docs](https://github.com/fluent-ffmpeg/node-fluent-ffmpeg#outputoptionsoption-add-custom-output-options)\n\n#### `videoshow#option(argument)`\nAlias: `flag`\n\nAdd a custom output option as command-line flag to pass to `ffmpeg`\n\n#### `videoshow#options(arguments)`\nAlias: `flags`\n\nAdd multiple output options as command-line flags to pass to `ffmpeg`.\nThe argument must be an `array`\n\n### `videoshow.VERSION`\nType: `string`\n\nCurrent package semantic version\n\n### `videoshow.ffmpeg`\nType: `function`\n\n[fluent-ffmpeg](https://github.com/fluent-ffmpeg/node-fluent-ffmpeg) API constructor\n\n## License\n\n[MIT](http://opensource.org/licenses/MIT) © Tomas Aparicio\n\n[travis]: http://travis-ci.org/h2non/videoshow\n[gemnasium]: https://gemnasium.com/h2non/videoshow\n[npm]: http://npmjs.org/package/videoshow\n[subrip]: http://en.wikipedia.org/wiki/SubRip#SubRip_text_file_format\n[ffmpeg-api]: https://github.com/fluent-ffmpeg/node-fluent-ffmpeg#creating-an-ffmpeg-command\n[ffmpeg-colors]: https://www.ffmpeg.org/ffmpeg-utils.html#Color\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh2non%2Fvideoshow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fh2non%2Fvideoshow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh2non%2Fvideoshow/lists"}