Function createSlideshow

Brains of the operation, entrypoint to this whole package.

Takes in images, audio, and options from which it automatically creates a slideshow video.

If images are provided as an InputImage array, per image options can be specified. Per image options override options specified in the 3rd parameter.
For example:

const images: InputImage[] = [
    {
        buffer: Buffer.from(myImage),
        duration: 5000
    },
    {
        filePath: 'image2.jpg',
        transition: 'dissolve',
        transitionDuration: 200
    },
    {
        filePath: '../../../documents/image3.png'
    }
];

const options: SlideshowOptions = {
    imageOptions: {
        imageDuration: 3500
    },
    transitionOptions: {
        transitionDuration: 500
    }
};

const response = await createSlideshow(images, './music/audio.mp3', options);
Copy

The three input images broken down:

First image, buffer input, overrides duration

• Has a duration of 5000ms
• 500ms transition (specified in options object) to the next image with the default transition (slideleft)

Second image, file path input, overrides transition and transition duration

• Has a duration of 3500ms, specified in the options object
• 200 ms transition to the next image with the dissolve transition

Third image, file path input, uses default options

• Has a duration of 3500ms, specified in the options object
• Will have no normal transition as it's the last image
• Might have a 500ms loop transition (by default pixelize), if image and audio durations permit it
• See remarks section for more about durations and looping

Remarks

Duration and looping

Possible total duration for one loop of images consist of the following:

• Image duration (set globally in ImageOptions.imageDuration or per image in InputImage.duration)
• Transition duration (set globally in TransitionOptions.transitionDuration or per image in InputImage.transitionDuration)
• Loop transition duration (also set in TransitionOptions.transitionDuration)
• Last image extra duration (set in ImageOptions.lastImageExtraDuration)
• End of input threshold (set in LoopingOptions.endOfInputThreshold)

Audio duration is simply just the duration of the audio.

Image Looping

Image looping is enabled by setting LoopingOptions.loopImages to "auto".
It is set to "never" by default. "auto" means that the images will start looping if duration and threshold conditions are met.

For example:

	Image 1	Image 2	Image 3	Audio
Duration	3.5 s	4 sec	3.5 sec	21 sec
Transition	500 ms	300 ms	250 ms (if loop)	-

So we have a total image duration of 11.8 sec + 250 ms loop transition (if a loop occurs)
And a total audio duration of 21 sec.

We have no last image extra duration, and a default end of input threshold of 3.5 sec (last image's duration).
And LoopingOptions.imageLoopThreshold is at its default value "all".

After the images have played once, 21 - 11.8 = 9.2 sec of audio is left.

Our imageLoopThreshold is set to "all", so all images will need to fit inside a loop for a loop to occur. We only have 9.2 sec of audio left, and full loop of images will take 12.05 sec, so no loop will be created? No, actually a loop will be created due to our end of input threshold being 3.5 sec. This means we are allowed 9.2 + 3.5 = 12.7 secs for a new loop.

Ok, new lets say our end of input threshold is set to 2000 (2 sec) instead. Now we only have 9.2 + 2 = 11.2 secs for a new loop. And a full loop of images will take 12.05 sec, so no loop will be created.

But let's also change our image loop threshold from "all" to 1. This means that only one image needs to fit inside a loop for a loop to occur. And our first image is 3.5 sec long, so a loop will be created.
After the first image has been added to the loop looped, we have 11.2 - (3.5 + 0.25) = 7.45 secs left. The second image is 4 sec long, so it will also be inserted into the loop. Now we have 7.45 - (4 + 0.5) = 2.95 secs left. Inserting the third image would require 3.75 secs, so it will not be inserted into the second loop and the second loop, and whole slideshow, ends.

Now lets say we have a last image extra duration of 3 sec. This means that the last image of a full loop will be extended by 3 sec. And now we wouldn't again have space for the second image, so the second loop would only contain one image.

You can run this example as code from the examples folder.

npx ts-node examples/duration-looping.ts
Copy

Audio Looping

Audio looping works in a similar way to image looping, but it's a bit simpler. And of course, the logic is inverted in the sense that we are checking how much video duration time we have left for a new loop of the audio track. The end of input threshold is also considered, just as it was for image looping.

For audio looping, LoopingOptions.audioLoopThreshold, which defaults to 0, exists. It specifies the amount of milliseconds that need to fit inside a loop for an audio loop to occur. Alternatively it can be set to "all", which means that the whole audio track needs to fit into a loop for a loop to occur.

See

SlideshowOptions for more information about the options object
InputImage for more information about per image options