Movie.js

Movie.js is a library built on top of fluent-ffmpeg designed to create templates for generating standardized videos with data—which can be static or dynamic. It simplifies the process of sequencing video, image, and audio clips into a final composition.

📦 Installation

Installation is straightforward; just use your preferred package manager. Here is an example using NPM:

npm i @marcuth/movie.js

Note: You must have FFMPEG installed on your system for this library to work.

🚀 Usage

Template

The foundation for creating videos in Movie.js is the Template. This is where you define your clips and configuration.

import movie from "@marcuth/movie.js"

type RenderData = {
    heroImage: string
    backgroundVideo: string
} 

const template = movie.template<RenderData>({
    config: {
        format: "mp4",
        fps: 30,
        outputOptions: ["-preset ultrafast"] // optional ffmpeg output options
    },
    clips: [
        // ... your clips here
    ]
})

// Render the template with data
const result = await template.render({
    heroImage: "/path/to/image.png",
    backgroundVideo: "/path/to/video.mp4"
})

// Save the result
await result.toFile("output.mp4")

---

Clips

Clips are the building blocks of your video. They represent individual media segments like videos, images, or audio tracks.

Most file paths in clips support dynamic resolution:

path: ({ data, index }) => data.myPath

VideoClip

To insert a video segment:

movie.video({
    path: "assets/intro.mp4",
    fadeIn: 1, // seconds
    fadeOut: 1, // seconds
    subClip: [0, 5] // [start, duration] - Clip from 0s to 5s
})

ImageClip

To insert an image with optional scrolling/Ken Burns effect:

movie.image({
    path: ({ data }) => data.heroImage,
    duration: 5, // seconds
    width: 1920, // force resize width
    height: 1080, // force resize height
    scroll: {
        axis: "y", // "x", "y", or "auto"
        direction: "forward",
        easing: "easeInOut"
    },
    fadeIn: 0.5
})

AudioClip

To add audio (background music, sound effects):

movie.audio({
    path: "assets/music.mp3",
    volume: 0.5,
    fadeIn: 2,
    fadeOut: 2
})

TextClip

To create a simple text-on-color clip:

movie.text({
    text: ({ data }) => data.title,
    duration: 3,
    backgroundColor: "#000000",
    fontColor: "white",
    fontSize: 72,
    // x and y accept ffmpeg expressions
    x: "(w-text_w)/2", // default: centered
    y: "(h-text_h)/2", // default: centered
    fadeIn: 0.5,
    fadeOut: 0.5
})

---

Structural Clips

RepeatClip

If you need to loop over an array of data to generate clips:

movie.repeat({
    each: ({ data }) => data.items, // Array of items
    clip: (item, index) => movie.video({
        path: item.videoPath
    })
})

CompositionClip

Group multiple clips together. Useful for organizing sequences:

movie.composition({
    clips: [
        movie.video({ ... }),
        movie.video({ ... })
    ]
})

ConcatenationClip

Explicitly concatenate a list of clips:

movie.concatenation({
    clips: [ ... ]
})

---

🤝 Contributing

Want to contribute? Follow these steps:

1. Fork the repository.
2. Create a new branch (git checkout -b feature-new).
3. Commit your changes (git commit -m 'Add new feature').
4. Push to the branch (git push origin feature-new).
5. Open a Pull Request.

📝 License

This project is licensed under the MIT License.