video utilities

Various utilities for video editing and manipulation.

Install

Requires Janet (>= 1.41) and ffmpeg installed somewhere on $PATH

The scripts can be run from the command line using janet

janet script.janet

or

./script.janet

compiled binaries can be created using jpm and installed somewhere on $PATH

jpm build
# optionally move binaries from build/ folder to $PATH
mv build/colourgrade build/colourstrip build/scenesplit build/slitscan /usr/local/bin/.

The scripts are written as wrappers around specific ffmpeg or ffprobe commands, and can be extended if required by directly editing the calls to ffmpeg and adding any required args (e.g. to change output quality or format).

scenesplit

Split video files into individual scenes and generate an HTML overview.

Uses ffmpeg scene detection to find cut points in video files, extracts a JPEG thumbnail for each scene, and optionally cuts each scene into a separate video file. Outputs an HTML overview. Accepts either a single video file or a directory of videos.

Usage

scenesplit [OPTIONS]

Options

Flag	Description	Default
--input FILE	Single video file or directory containing videos	.
--output DIR	Output directory for thumbnails, clips, and the HTML	scenes_output
--cut	Also cut each scene into a separate video file	off
--ext EXT	File extension for cut scene clips	.mp4
--threshold NUM	Scene detection threshold 0.0–1.0, lower = more splits	0.3
--light	Use light theme for HTML report	off
--dark	Use dark theme for HTML report	on

Examples

Process all videos in the current directory, generate thumbnails only

scenesplit

Process a single video file

scenesplit --input clip.mp4

Process a single file with a custom output directory

scenesplit --input vacation.mp4 --output ~/output/inferno

Process a specific folder with a custom output directory

scenesplit --input ~/Videos/raw --output ~/Videos/scenes

Cut scenes into separate files and lower the detection threshold

scenesplit --input ./footage --cut --threshold 0.2

Output cut scenes with a different container format

scenesplit --cut --ext .mkv --input ./footage

Without --cut, only the .jpg thumbnails and scenes.html are generated

Scene detection

The --threshold flag controls ffmpeg’s scene detection sensitivity. It maps to the select filter’s scene value.

• 0.1 – very sensitive, many small scenes
• 0.3 – generally balanced default
• 0.5 – conservative, only large transitions
• 1.0 – disables scene detection

colourgrade

Automated colour grading using HaldCLUT (Color Lookup Table) with ffmpeg.

Generates a HaldCLUT identity image with a reference frame from the video. The image can be edited in any image editor to apply colour grading. The modified CLUT can then be applied to the entire video.

Further reading: https://rawpedia.rawtherapee.com/Film_Simulation

Usage

Generate a HaldCLUT identity image (outputs VIDEO_clut.png)

colourgrade footage.mp4

Generate CLUT from a frame at a specific timestamp

colourgrade --frame-time 0:01:30 footage.mp4

Apply an edited CLUT to a video

colourgrade --lut footage.mp4_clut.png footage.mp4 graded.mp4

Options

Flag	Description	Default
--lut FILE	HaldCLUT PNG file (if provided, applies grading)
--frame-time TIME	Timestamp for reference frame (generate only)	0:00:04

Workflow

The utility applies a CLUT to an entire video file. If there is more than one grading required in a video, cut into scenes and repeat the process for each scene.

Generate the HaldCLUT identity image

colourgrade footage.mp4

Open clut.png in an image editor (GIMP, Photoshop, etc.)

Adjust the levels and/or curves for the entire image to create the desired look. The left side of the image is the CLUT and right side a reference frame from the video. Adjusting the image until the reference frame looks correct will also adjust the CLUT.

Save the edited PNG and apply to the video

colourgrade --lut footage.mp4_clut.png footage.mp4 graded.mp4

colourstrip

Create a colour strip visualization from a video.

Extracts a single pixel column from averaged frames and combines them into a horizontal strip showing the colour progression of the video. Useful for visualizing overall colour palette and transitions in a video.

Usage

colourstrip VIDEO [OPTIONS]

Options

Flag	Description	Default
--output FILE	Output PNG file	strip.png
--frame-skip NUM	Number of frames to average per pixel column	15
--blur NUM	Horizontal blur size for the final strip	3

Examples

Create a strip with default settings

colourstrip footage.mp4

Create a strip with custom frame skip

colourstrip footage.mp4 --output the_strip.png --frame-skip 30

Create a strip with more blur

colourstrip footage.mp4 --blur 5

slitscan

Create temporal smear videos from a video file.

Generates horizontal and vertical “slitscan” effects by extracting individual pixel slices from each frame and tiling them together.

Based on https://github.com/zzkt/slitscan

Usage

slitscan VIDEO [OPTIONS]

Options

Flag	Description	Default
--output FILE	Output file prefix (prepended to horizontal/vertical suffix)	slitscan
--width NUM	Resize width for processing	160
--height NUM	Resize height for processing	90
--cleanup	Remove temporary files after completion	off
--verbose	Show frame extraction progress	off
--loglevel LEVEL	ffmpeg log level (quiet/error/warning/info)	error

Examples

Create slitscan videos with default settings

slitscan footage.mp4

Create with custom dimensions

slitscan footage.mp4 --width 320 --height 180

Clean up temporary files after completion

slitscan footage.mp4 --output slitscan_atemporal --cleanup

Output

The script produces two MKV files:

• <output>_horizontal-smear.mkv — horizontal frame smearing effect
• <output>_vertical-smear.mkv — vertical frame smearing effect