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.

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