Github page · Examples

mod2vid

This bash script turns tracker modules into music videos.

Features

• pattern visualization (via openmpt123)
• headless capturing: run it in batches and turn all your mod/med/it/xm/mptm/etc files into videos in one go. Only thing you'll notice currently is the music playing in the background during the video capturing. You can turn this off with the -S switch, downside here is that you will not see the VU meters at the top.
• support for .ass subtitle files (via ffmpeg, which is the workhorse here in general)
• custom themes
• normalization of the input audio (-n)
• you can also create custom themes where you can define the general look of the video.

Prerequisites

I've been developing this script on Ubuntu Linux, I know it works on Mint, but I can't tell you if it runs on any system other than Linux.

Any recent version of bash (4.4?; 5.0?) should do the job, which should be included with most up-to-date Linux systems.

Installation Guide

Run build.sh in the main folder. This will create dist/mod2vid. Just copy or link the mod2vid file into a PATH (e.g. ~/.local/bin) and execute it from anywhere.

ln dist/mod2vid ~/bin

You will also need the following packages (Debian/Ubuntu-based distributions):

sudo apt install openmpt123 ffmpeg sox imagemagick xterm xvfb x11-utils

How to Use It

The easiest way to invoke the program and create a video is by typing (The extension .mptm is for demostration purposes. Any of the module formats supported by OpenMPT will do):

mod2vid <modname>.mptm

Test it with a short track (one pattern) because you might have to calibrate the DELAY value. The default is 1.0 seconds, which means: Wait one second between starting xterm and starting openmpt123. Depending on the speed of your machine you will notice a delay either in the pattern display or the music. You can set the delay value either by environment variable or by argument:

DELAY=0.8 mod2vid music.xm

mod2vid music.xm --delay 0.8

This basic invocation will do the following

• The module will be rendered as wav by openmpt123
• A virtual X server session is initiated (Xvfb) with an xterm on it
  • Here, the program starts openmpt123 --pattern
  • As soon as the session runs, ffmpeg will capture the content
  • You will hear the progress, and you will see ffmpeg's progress indication
• A background image is generated by convert (ImageMagick) containing the essential information from openmpt --info
• ffmpeg is started again, now rendering our final video with the input from our previous ffmpeg session and the background image generated with convert

And that's it! Now the situation in the creation directory should look like this:

• <modname>.mptm: The original music file
• <modname>_info.png: The background image containing our openmpt --info data
• <modname>_term.mp4: The recording of the terminal session with openmpt123 --pattern running.
• <modname>.mp4: The generated final video

You can keep the <modname>_term.mp4 in case you want to make some changes to the video. If the file is present and the -s ("skip screen capture") is set, the program will directly skip to the final render.

Creating a New Template

Redirecting the output of mod2vid -p to a new file will write the variables with their default values into that file. The first line must start with "# mod2vid template", otherwise the program will not execute it.

Open the file in a text editor and modify the values. If you want to have some randomness for batch processing you can create an array of images and/or videos with the variable BACKGROUND_IMAGE_POOL:

BACKGROUND_IMAGE_POOL=(
    image1.jpg
    video1.mp4
)

This array needs at least two values, otherwise it will be ignored. spaces around = are not allowed in Bash.

If this array is set contains of at least two filenames, one is chosen randomly and the program checks if the file exists. If there are no absolute path names, it will first look relative to the location of the settings file, and if not found relative to the directory where the program is executed.

In case you only have one background image use the BACKGROUND_IMAGE variable. If you don't want to have any background use the BACKGROUND_COLOR variable and do not define the BACKGROUND_IMAGE_POOL or BACKGROUND_IMAGE variables (comment them out if necessary.

The BACKGROUND_COLOR has a command for ImageMagick’s convert tool, like gradient:#RRGGBB-#RRGGBB for a color gradient or xc:#RRGGBB for a single color background. You can also use words for colors.

Command Line Options

Title Templates

If you want to batch process multiple module files it's best to have the video generator know about the module data. There are some template placeholders that you can set. These values are extracted from openmpt123 --info output.

Subtitle File

Subtitle files are in .ass (Substation Alpha v4.00) format. They are natively supported by ffmpeg. There is an example file in the settings/ directory.

Usage Output

mod2vid v0.2.3 -- 2025 by Christian Czinzoll
Usage: mod2vid [OPTIONS] <module file>

Create music videos from tracker modules with pattern visualization

Arguments:
  <module.it>         Path to a .it/.mod/.xm file for openmpt123

Options:
  -l, --load-settings <file> Load settings from a file
  -b, --background <file>    Background image/video
  -i, --input-audio <file>   Use custom audio file instead of rendering module
                             (Useful for tracks with VST plugins that need
                             to be rendered in OpenMPT first)
  -o, --output-file <file>   Save the final video to this file
  -t, --title "text"         Text overlay displayed at top of video
  -S, --subtitle-file <file> Play a subtitle file (.ass)
  -g, --gain <db>            Amplify output by <db> (0-10, default: 0)
  -n, --normalize            Amplify to 0dbFS
  -c, --columns <width>      Terminal width in characters (default: 80)
  -r, --rows <height>        Terminal height in characters (default: 24)
  -d, --delay <seconds>      Delay before recording starts (0.1-5, default: 1.0)
  -s, --skip-term            Skip terminal recording if _term.mp4 exists
  -N, --no-metadata          Strip all metadata from output video
  -Q, --no-trackinfo         If no background was specified, the video will
                             show some track info.
                             You can turn off this behavior with this switch.
  -p, --print-settings       Print current settings, including from template file
  -h, --help                 Show this help message

Examples:
  mod2vid song.it -t "Epic Track" -n
  mod2vid -i final.wav -b background.jpg song.mptm
  mod2vid --title "{artist} - {title}" module.mod
  mod2vid -t "Retro" -c 100 -r 30 song.it