Visualization


The default visualization comes as a plugin of QMidiPlayer. So before using it you have to enable it first in the plugin manager.
To use the visualization, click the Visualization button in the main window.
The visualization plugin adds two new option tabs.

Controls

Options

The options listed here are applied after closing and reopening the visualization.

Visualization Renderer

The visualization plugin comes with a standalone application that generates high quality rendering of a midi file.

Command line usage

Usage: ./qmpvisrender [options] file
Renderer a visualization of a midi file.

Options:
  -h, --help                       Displays help on commandline options.
  --help-all                       Displays help including Qt specific options.
  -v, --version                    Displays version information.
  -f, --output-file <filename>     File name of the output file.
  --receiver <command>             Specify a program and its arguments to
                                   process the rendered frames. Supports
                                   parameter substitution. See documentation for
                                   details.
  -e, --receiver-execution <mode>  Execution mode of the receiver command.
                                   Valid options are 'one-shot' and 'per-frame'
  -s, --show-window                Do not hide the visualization window.
  -c, --config <qmprc file>        Load options from the configuration file.
  -o, --option <key-value pair>    Set option for the visualization module.
  --list-options                   Show a list of recognized options.

Arguments:
  file                             MIDI file to render
		

Basic usage

You will most likely to load your QMidiPlayer configuration file so that you can get the exact same results as viewed in QMidiPlayer. You should also make sure ffmpeg is ready to use. Then you can run qmpvisrender -c <path-to-configuration-file> <MIDI file to render> and wait for the results. The output file is named output.mp4 and will be found in the current work directory.

Supplementary materials for commandline options

When specifying a value for an option under the "Visualization" category, the category part in the key may be omitted, so "-o Visualization/wwidth=1920" would become "-o wwidth=1920".

The renderer performs parameter substitution before invoking the receiver command line.

PlaceholderSubstituted withRemarks
%wwidth of an output frame in pixels
%hheight of an output frame in pixels
%rframerate which the output frames should be played at
%iinput format specification for ffmpegshorthand for "-f rawvideo -pixel_format rgba -video_size %wx%h -framerate %r -i pipe:"
%ooutput file name specified by the --output-file optionIf the receiver execution mode is "per-frame", "%f" in the output file name will also be replaced.
%fa six-digit frame numberonly works if the receiver execution mode is "per-frame".

To add a literal space in the receiver command, put a single backslash before the space. To add a percent sign, either put two consecutive percent signs or use a backslash followed by a percent sign.

The default receiver command is ffmpeg %i -vf vflip -pix_fmt yuv420p -c:v libx264 -preset slow -crf 22 %o. In case the output quality doesn't satisfy your needs, consider lowering the number after '-crf' or selecting a even slower profile ('slower' or 'veryslow').

How it works

Notice: you don't have to understand anything under this section to use this tool. You may try out the examples below or simply adhere to the basic usage shown above even this section makes zero sense to you.

The renderer feeds a sequence of images into one command or a series of commands that process the images through a pipe. That's it!

The data is an stream of raw RGBA values, where each color takes one byte in every pixel. The frame size is the same as used by the visualization module, and the frames should be played back at a fixed frame rate. The pixel data starts from the bottom-left of a frame and follows row-major ordering (so you may want to flip the frame when using the frame with some applications).

The renderer supports two modes of receiver program operation. If the mode is set to 'one-shot', the receiver is only started once and gets all rendered frames. If it is set to 'per-frame', the receiver will be started every time a frame is rendered, and will only get one frame to process.

Examples

If you wish to try these examples, make sure you have the required receiver program ready to run.

  1. Render to a vp9 encoded webm video.
  2. qmpvisrender -c ~/.config/qmprc --output-file test.webm --receiver 'ffmpeg %i -vf vflip -c:v libvpx-vp9 -crf 30 -b:v 0 %o' <midi file>
    		
  3. Render to a h264 encoded mp4 video with hardware encoding acceleration using VA-API.
  4. qmpvisrender -c ~/.config/qmprc --output-file test.mp4 --receiver 'ffmpeg -vaapi_device /dev/dri/renderD128 %i -vf vflip,format=nv12,hwupload -c:v h264_vaapi -b:v 5M %o' <midi file>
    		
  5. Render the frames into png files using imagemagick.
  6. qmpvisrender -c ~/.config/qmprc --receiver-execution per-frame --receiver 'convert -size %wx%h -depth 8 RGBA:- -flip pngout/%f.png' <midi file>
    		
  7. Show the visualization window. Discard all rendered frames.
  8. qmpvisrender -c ~/.config/qmprc -s --receiver 'dd of=/dev/null bs=24M' <midi file>
    		
  9. Save the raw frame data.
  10. qmpvisrender -c ~/.config/qmprc --receiver-execution per-frame --receiver 'tee rawoutput/%f.raw' <midi file>
    		

Useful stuff to refer to

ffmpeg documentation and ffmpeg codecs documentation, if you want to tweak the ffmpeg encoder.