From 86f10fa1bcdc25bf4a91e9b07322edcaa885fe49 Mon Sep 17 00:00:00 2001 From: Chris Xiong Date: Sat, 2 May 2020 10:42:01 +0800 Subject: New command line option "list-options" for visualization renderer. Add documentation for the visualization renderer. --- doc/visualization.html | 118 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 117 insertions(+), 1 deletion(-) (limited to 'doc/visualization.html') diff --git a/doc/visualization.html b/doc/visualization.html index 6ad44dd..207d3a5 100644 --- a/doc/visualization.html +++ b/doc/visualization.html @@ -69,7 +69,7 @@
  • Enable VSync: Enable vertical synchronization.
  • Save Viewport: Restore last camera configuration when the visualization is started.
  • Window Width/Height: Change the window size. If the size equals to your screen size, the visualization will start in fullscreen mode.
    • -
  • FPS: FPS limit of the visualization.
    • +
  • Target FPS: FPS limit of the visualization.
  • Supersampling: Supersample anti-aliasing for the 3D visualization scene. 1 means no SSAA.
  • Multisampling: Multisample anti-aliasing for the 3D visualization scene. 0 means no MSAA.
  • FOV: Field of view.
    • @@ -87,6 +87,122 @@ +

    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>
+
      +
    2. Render to a h264 encoded mp4 video with hardware encoding acceleration using VA-API.
      3. + 
      +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>
+
      +
    3. Render the frames into png files using imagemagick.
      4. + 
      +qmpvisrender -c ~/.config/qmprc --receiver-execution per-frame --receiver 'convert -size %wx%h -depth 8 RGBA:- -flip pngout/%f.png' <midi file>
+
      +
    4. Show the visualization window. Discard all rendered frames.
      5. + 
      +qmpvisrender -c ~/.config/qmprc -s --receiver 'dd of=/dev/null bs=24M' <midi file>
+
      +
    5. Save the raw frame data.
      6. + 
      +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. -- cgit v1.2.3