extract-keyframes/README.md

A module for extract keyframes from video files with FFMPEG

# Extract Keyframes

A Node.js module that identifies and extracts the keyframes in videos for processing/storage elsewhere.

*NB:* _This module is still under development. Breaking changes in the interface are to be expected often, but will be versioned._

## Usage

The module uses FFProbe to identify keyframes in a video file (a path to the video file must be passed for processing. Streams and Buffers are not supported at this time). These frames are then extracted with FFMPEG.

```JavaScript
const extractKeyframes = require('extract-keyframes');

extractKeyframes('/path/to/validFile.mp4')
	.then(extractionProcess => {

		// Event fired when extraction process has begun.
		extractionProcess.on('start', function(){
			debug('Started');
		}, false);

		// Event fired when a keyframe is extracted
		extractionProcess.on('keyframe', function(data){
			debug('KEYFRAME:', data);
		});

		// Event fired when all keyframes have been extracted from the video
		extractionProcess.on('finish', function(data){
			debug('Finish:', data);
		});

	})
	.catch(err => {
		debug('Error extracting keyframes:', err);
	})
;
```

By default, the frames are extracted to the `/tmp` folder. To change it, set a `WORKING_DIRECTORY` process environment variable to the path where you want the frames to be extracted when running your app. Example:
```WORKING_DIRECTORY=/Users/you/Documents/frames node index.js```

## Function Options

`extractKeyframes(<FILEPATH | BUFFER>, <DIMENSIONS>)`

### FILEPATH

A relative or absolute path to the media file you wish to analyse, or a Node.js buffer containing the video file that you wish to extract keyframes from.

### DIMENSIONS

An object with the desired height/width of the extracted keyframes. If not passed, the keyframes will be extracted at the same resolution as the source media. If only one dimension is passed (either height or width) then the image will be extracted with that dimension, and the scale maintained along the other dimension.
```
	{
		width : <INT>,
		height : <INT>
	}
```

## Events

### 'start'

Fired _once_ when the extraction process has begun (when FFProbe is spawned and starts looking for keyframes).

#### event data
*This event returns no data.*

### 'keyframe'

Fired every time a key frame has been identified and extracted from the passed video file. Keyframes are extracted in the order that the frames are identified, but they are not guarenteed to be emitted to the user of the module in that order. 

For example, a keyframe at a time index of 00:03:36 will be extracted before a keyframe identified at 00:04:59, but the order in which these keyframes are emitted from the `extract-keyframe` module is not guarenteed.

If you require sequential keyframes, you will need to store and sort the events by the `keyframeTimeOffset` as they are emitted.

#### event data

```
{
	keyframeTimeOffset : <NUMBER>,
	image : <BUFFER>,
	analysisUUID : <STRING>
}
```

### 'finish'

Fired _once_ when the identification process has completed (when FFProbe has identifed all of the keyframes in the video). 

This does not necessarrily mean that every keyframe has been extracted from the video file and corresponding `keyframe` event has been triggered. These processes happen independently of one another, and are not guarenteed to complete at the same time. 

To check that all of the keyframes have been identified _and_ have been returned, you must check that the number of `keyframe` events that have been emitted match the `totalFrames` property of the object passed to the `finish` event listener

#### event data

```
{
	analysisUUID : <STRING>,
	totalFrames : <NUMBER>
}
```

## You may also be interested in...

[The Node-red module for keyframe extraction](https://github.com/seanmtracey/node-red-contrib-extract-keyframes)