The UMP Manual

14th edition for 1.6

Match 27, 2023

Basics, tips, and answers for recently asked questions. You can now find right section by purpose. Suggestions will be appreciated at UMP Discord server! My English sucks. Really. Please correct.

What is UMP?

UMP (Ultralight MIDIPlayer, 超軽量MIDIプレイヤー, [tʃoːkeirjoː.midi.pureijaː]*1) is literally ultra lightweight (hopefully) and versatile MIDI player to help making MIDI videos, featuring no-lag video rendering, note counter, clean GUI and more.

Quick Start

1. Get a Decent PC

UMP should run smoothly on a PC with:

2. Install Java

Download the installer from Java download page and run it.

Install Java that works best for your computer. Some examples: for 64-bit Windows, choose the one that is clearly marked 64-bit; for Apple Silicon Macs, choose the aarch64 version. Chosing wrong Java may impact performance.

Links for Windows installers.

3. Get MIDI Synth Working

You'll need a MIDI synth and a soundfont to hear MIDIs.

For synth we recommend OmniMIDI, a high performance synth for professionals. You might want to avoid using synths bundled with Java such as Gervill, as those are not suitable for Black MIDIs.

You can find a ton of soundfonts on internet. Grab some and configure your synth. (Not covered in this manual, see your synth's documentation)

4. Start UMP!

Download UMP from the main page and unzip it to empty folder.

The UMP Folder. Some folders will be automatically created when starting UMP.

On Windows, open MIDIPlayer.bat and enjoy.

On other OS, type this command in terminal:

Terminal
$ java -jar MIDIPlayer.jar

Select the synth you've installed and you're good to go!

5. Play a MIDI

Select [File] -> [Open] in the menu bar or drop a .mid file.

You can also drop a .zip archive or a folder. In that case, UMP will load the first .mid file in it.

6. Next Steps

9. Uninstall

Delete UMP folder. Easy!

In case you're wondering: UMP doesn't alter system settings nor registry, so deleting UMP folder is really it.

The UMP Launcher

The UMP Launcher is a simple batch file (MIDIPlayer.bat) to start UMP on Windows. The UMP Launcher can be edited in text editor for customization.

Options

Options starts at line 5. Option name and value is separated by = with no spaces around.

MIDIPlayer.bat
set INITIAL_MEMORY=2G
set MAX_MEMORY=2G
set JVM_ARGS=-XX:+UseG1GC
set UMP_OPTIONS=
set PAUSE_AFTER_EXIT=false
set CRASH_ON_OUT_OF_MEMORY=true

INITIAL_MEMORY

MAX_MEMORY

JVM_ARGS

UMP_OPTIONS

PAUSE_AFTER_EXIT

CRASH_ON_OUT_OF_MEMORY

Command Line Usage

This section is for people who don't use the Launcher.

Syntax

java [JVM options] -jar MIDIPlayer.jar [UMP options] [[--] <MIDI file>]

JVM Options

JVM options are not part of UMP and we'll only cover the most commonly used options. Run java -help for more information.

-Xms<size>, -Xmx<size>

Example: -Xms1560M -Xmx8G (1.5GB initial, 8GB max)

Initial and maximum amount of memory that program (UMP) can use. Size can have letter M or G at the end for megabytes or gigabytes. Increase this to open larger MIDI files.

-XX:+UseG1GC

Example: -XX:+UseG1GC

Use Garbage first garbage collector (G1GC), which is probably the fastest. For more info about GC, ask Wikipedia Senpai.

UMP Options

--no-april
Prevent special features from being enabled during April 1st and April 3rd JST.
-h, --help
Display command line usage and exit.
--version
Display UMP version and exit.
[--] <MIDI file>
Play MIDI file when UMP is ready. Path can be prefixed with -- to separate it from options when necessary.

Renderers

DefaultMIDIRenderer

It's default...

TickBasedDefaultMIDIRenderer

It's default... but render interval changes according to tempo. 120 BPM makes 1x note speed.

Notes are moving faster according to 2x tempo at the end

KeyMIDIRenderer

Only displays keys pressed for each MIDI channel in single color. It doesn't use textures but color information from resource pack.

HorizontalMIDIRenderer

Displays notes in single color and moves from right to left. Pressed notes glows. It doesn't use textures but color information from resource pack.

HexMIDIRenderer

Simulates and displays the MIDI file content with all notes and tempo events in original MIDI merged into one track. Text color is automatically set to white in video render or if background is dark. It doesn't use resource packs at all. Monospace font required.

Render to Video

Render to Video dialog.

FFmpeg

You need FFmpeg executable to create a video. Go to FFmpeg website and download the package (not source code).

If you place ffmpeg.exe in the UMP folder, UMP will automatically selcet it for you.

Video Types and Codecs

VideoPrograms
TypeCodecTransparencyWindowsOSXAfter Effects CC
Movie & TVMedia PlayerAVIUtlQuickTime Player
mp4x264
x265
movpng
qtrle
avipng

Presets

  1. ultrafast
  2. superfast
  3. veryfast
  4. faster
  5. fast
  6. medium
  7. slow
  8. slower
  9. veryslow
  10. placebo

The upper in the list, the faster the encoding and the larger the video file. placebo seems to be not so much effective.

Increase mp4 Quality

Without changing any options, bitrate of the video is set automatically (200kbps?). If the video looks strange, try setting bitrate in advanced options. My recommendation is VBR with CRF of 20 or smaller.

Left: Extremely low bitrate (CBR 250kbps). Right: Good bitrate (CRF 18).

Diagnose MIDI

Diagnosing MIDI file.

"Count notes & MIDI diagnosis" allows you to count notes and find problems of MIDI files in less memory. If UMP can't play some MIDIs, use this to diagnose the file before contacting, as 99% is problem in file, not UMP.

NameNotes
File SizeBinary prefix (1KiB is 1024B not 1000B, 1MiB is 1024KiB)
ResolutionPPQN
Tracks
Notes
Memory to OpenValue will change even on same MIDI depending on config midi.loaderThreads
Length
TempoCan show range ("minimum tempo~maximum tempo")
Moment Max NPSMay not be correct :(
Overlapped Notes

YAML

YAML is a data serialization language used in UMP for saving some data to files. YAML is basically a collection of colon-separated key-value set.

Fun fact: YAML is a recursive acronym standing for "YAML Ain't Markup Language".

Data Type Legend

String

Example: "Hello, World!"

A text. Recommended to surround with " or ', but not always necessary.

Integer

Example: 77, 0x4d

A number with no decimals.

Float

A number. Decimals can be used.

Color

Example: 0xffb900(yellow), 0xffffff(white)

A string or an integer representing hexadecimal RGB Color.

Boolean

Only true (Yes) or false (No).

Remarks

Config

Some UMP settings can be changed by editing config.yml in UMP folder.

Close UMP before editing config!

Sample

config.yml
version: 2
language: ja
midi:
  loaderThreads: 0
  loadNotesOnly: false
  usePlayThread: true
render:
  width: 1280
  height: 720
  fpsLimit: 120
  renderInterval: 5.0
  background: 0xc0c0c0
  usePFAColors: false
  resourcePack: null
  font: Monospaced
  overlay:
    opaque: false
    info:
      scale: 1.0
      type: DEFAULT
      position: TOP_RIGHT
      showDuration: false
    fps:
      type: SHOW_ALL
    desync:
      type: SHOW_NUMBERS
    loading:
      showMemoryUsage: false
ui:
  font: Yu Gothic UI
files:
  midi: null
  ffmpeg: null
  resourcePacks: null
updateChecker:
  checkOnStartup: true
  branch: development

version

Config version. Do not change!

language

UI language. Can be Japanese(ja), English(en), or name of language files in the UMP folder.

See also: Translation

midi.loaderThreads

Number of threads to use for loading MIDI. When set to 0 or less, UMP will use as many threads as possible.

midi.loadNotesOnly

When set to true, Only notes in MIDI files will be loaded and played. Anything else such as instrumental change and pitch bend are ignored. UMP 1.5.1 and earlier worked this way.

When set to false, some of MIDI events other than notes will also be loaded and played. Although not perfect, some MIDI files will sound better.

midi.usePlayThread

When set to true, rendering and MIDI will be processed in its own thread. Those threads don't wait for each other to mentain high framerate; audio may lag behind in extreme conditions.

When set to false, rendering and MIDI will be processed alternately in the same thread. This negatively affects the framerate, but audio will never lag behind.

render.width

Screen width.

render.height

Screen height.

render.fpsLimit

Limits the framerate while playing. 0 or less means unlimited.

render.renderInterval

The renderer's interval parameter. The smaller this value, the faster the notes move.

render.background

Background color.

render.usePFAColors

When set to true, UMP will load PFA settings file and render notes in same colors as PFA. If failed, all colors will be random.

render.resourcePack

Name of resourcepack's file or folder to automatically load on startup. When set to null or any non-existing file name, default resourcepack will be used.

Also see: Resourcepack

render.font

Name of the font to use in overlays (not UI). Since Java is not that good on loading fonts, some might not work.

render.overlay.opaque

When set to true, background color of all overlays will be opaque.

When set to false, background color of all overlays will be semi-transparent.

render.overlay.info.type

What to display in the info overlay. Only the following values are allowed, otherwise it will be reverted to the default value.

render.overlay.info.position

Position of the info overlay. Only the following values are allowed, otherwise it will be reverted to the default value.

render.overlay.info.scale

Scale of the info overlay.

render.overlay.info.showDuration

When set to true, the time portion of the playback info overlay will also display the length of the MIDI currently playing (e.g. 27.427.4/02:41.2).

render.overlay.fps.type

What to display in the FPS counter overlay. Only the following values are allowed, otherwise it will be reverted to the default value.

render.overlay.desync.type

What to display in the MIDI desync overlay. Only the following values are allowed, otherwise it will be reverted to the default value.

ui.font

Name of font to use in UI(not overlay).

files.midi

Location of last opened MIDI file.

files.ffmpeg

Location of last opened ffmpeg executable.

files.resourcePacks

Resourcepacks folder.

The folder where you put your resource packs. null means resourcepacks/ folder inside the UMP folder. Changing this allows you to share resourcepacks between multiple instances of UMP.

updateChecker.checkOnStartup

When set to true, UMP will check for new version of UMP automatically.

updateChecker.branch

Type of version to check for.

Resourcepack

Resourcepack (or "Pack") is folder or zip file containing following PNG images and pack.yml file. Some images should be grayscale for better coloring results.

The UMP Assets. Resourcepacks can overwrite all of these.
Real resourcepack folder.

note and noteEdge should be 1 pixel high. Others can be any size. Images are resized without anti-aliasing for maximum performance.

pack.yml

Sample

format: 0
name: "Synthesia Note Colors"
version: 1.1.0
author: "PipiraMine"
description: "No random colors."
note:
  loopColors: true
  colors:
    - 0x85f202
    - 0x71aceb
    - 0xf94b3b
    - 0xe18de6
    - 0xffec00
    - 0xffa300
signature: null

format

Pack format. Packs with this value not 0 will be displayed as incompatible.

name

Name of the pack to show in pack list.

version

Version of the pack to show in pack list. There's no rules for writing version.

author

Name of author of the pack to show in pack list.

description

Description of the pack to show in pack list.

note.loopColors

Whether note colors should be looped. If false, Colors after using all will be random.

true:
false:
Looping 6 note colors. Default resourcepack has 16 colors.

note.colors

Note color for each tracks. Use map to change specific track color(Note that track number starts from 0).

colors:
  - 0xff0000
  - 0x00ff00
  - 0x0000ff
Using list(with loopColors true)
colors:
  1: 0xffffff
  3: 0x000000
Using map. Note that random color (track 0 and 2 in this case) is always different in each color loop, even if loopColors is true.

signature

Translation

UMP supports Japanese, English and Simplified Chinese by default. You can easily add translations by simply placing language files in UMP folder.

de.lang
_lang=Deutsch
welcome.synth=Wählen Sie einen Synthesizer
welcome.synth.none=(Keinen benutzen)
welcome.next=Weiter
UMP loading language file placed in UMP folder.

Language Format

# Syntax:
key=value
# Examples:
_lang=English
converter.speedLimit=Slow down render to %s%%
converter.speedLimit.unlimited=No render speed limit
converter.done=Finished rendering to:\n%s

Language Metadata

Metadata has key starting with _ to distinguish from UI translations.

_lang

Name of this language. Used in [Languages] dialog and welcome window.

_lang.xx

Name of this language in other language. Used in [Languages] dialog, next to language with file name same as xx part.

ja.lang
_lang=日本語
_lang.en=Japanese
en.lang
_lang=English
zh.lang
_lang=簡体中文
_lang.en=Chinese Simplified
Selecting language with filename of en.lang to display _lang.en in other languages.

_font

Name of suitable font to display this language. Multiple fonts can be specified using comma to support more OSes (don't put spaces around comma). First installed fonts in this list or default sans serif (if no fonts were installed) will be used.

ja.lang
_font=Yu Gothic UI,Meiryo UI,メイリオ
Font displayed in language dialog. In Windows 8 Yu Gothic UI doesn't exist, so next font in the list, Meiryo UI, will be displayed.

_createdBy

Name of translators. Not yet used in UMP, but reserved for future use.

Tutorials

Index

Memory Allocation

UMP runs on top of a program called JVM, which limits how much memory UMP can use. To open bigger MIDIs, you might need to change this limit, called Memory Allocation.

Limitations

Before you begin, check how much memory is available on your PC. Allocations larger than that have no benefit, and may prevent UMP from even starting.

If your PC is 32-bit, UMP will not start if you try to allocate more than 2GB. This is a physical limitation of 32-bit PCs, and we recommend that you get a new PC to allocate more.

If you have 32-bit Java, UMP will also not start if you attempt to allocate more than 2GB. However, unless your PC is 32-bit, you can remove this limitation by installing 64-bit Java (also see Quick Start).

How to check the amount of memory in your PC and whether your PC is 32-bit or not depends on the OS. We'll not cover them here; search online for more information.

Changing Memory Allocation in Launcher

  1. Open MIDIPlayer.bat in your favorite text editor.
    One of ways you can open the file in Notepad.
  2. Update values of launcher options INITIAL_MEMORY and MAX_MEMORY to the new allocation.
    MIDIPlayer.bat (before)
    set INITIAL_MEMORY=2G
    set MAX_MEMORY=2G
    MIDIPlayer.bat (after)
    set INITIAL_MEMORY=6G
    set MAX_MEMORY=6G
    Changing Launcher options to use 6GB memory
    How it looks after changing options in Notepad.
  3. Save file and restart UMP.

Changing Memory Allocation in Command Line

For those who don't use the Launcher, add the -Xms and -Xmx arguments between java and -jar as shown in the following example.

Terminal
# before
$ java -jar MIDIPlayer.jar

# after
$ java -Xms6G -Xmx6G -jar MIDIPlayer.jar
Command to start UMP with memory allocation of 6GB.

Getting Out of Memory

If you use the Launcher, UMP will immediately close itself when allocated memory is exausted. You can disable this behavior by changing Launcher option CRASH_ON_OUT_OF_MEMORY to false. However, since running out of memory is an unrecoverable error to any programs in general, UMP may be very unstable.

An out of memory message displayed in the Launcher when UMP ran out of memory

Apply WinMM Patch

MIDI performance on Windows 10 is terrible. Let's improve that drastically with WinMM patch.

Since UMP runs on a program called JVM, you need to patch JVM instead of UMP.

It's recommended to patch JVM every time you update Java, just to be sure.
If you've patched anything using OmniMIDI 7.1 or older, you really should patch them again using latest version of OmniMIDI! Old patch contains serious security issue!

Find JVM

  1. Have UMP running.
  2. Open Task Manager.
    • If you see [More details] at bottom-left of the window, click it.
  3. In [Processes] tab, find a JVM process that is called "Java(TM) Platform SE binary" and shows UMP when expanded. Right click on it and select [Open file location].
    JVM process running UMP.
  4. File explorer will open. Copy the path.
    Path can be copied by right clicking on the address bar and selecting [Copy address as text].

Patch with OmniMIDI

  1. Open OmniMIDI Configurator as administrator and go [Tools] -> [Windows Multimedia Wrapper].
    Windows Multimedia Wrapper.
  2. Click [Patch an application].
  3. In [Select an application to patch] dialog, go to the JVM folder and select java.exe.
    Path can be pasted by clicking on empty space of the address bar (or right click and select [Edit address]).
  4. Restart UMP.
  5. Done!

Patch Manually

  1. Download winmm32wrp.dll (for 32-bit) or winmm64wrp.dll (for 64-bit) depending on architecture of your JVM.
  2. Place the patch file into JVM folder. Administrator privilege may be required.
  3. Restart UMP.
  4. Done!

Change Note Colors

Resourcepacks allows you to change color of notes.

  1. Check what track has the notes you want to change color. Skip all tracks with no notes, count from 0 and remember the number of that track.
  2. Open resourcepacks folder (create if it doesn't exist) in UMP folder, create new folder with any name, create new file named pack.yml in that folder.
    Folder structure after this step
  3. Open pack.yml in text editor and write:
    format: 0
    name: (Any name)
    version: 1.0
    author: (Your name)
    description: (Short description)
    note:
      colors:
        (Track number): (Color you want)
    Not to mention you don't need to use your real name.
    You can also use list if you want to change many colors from track 0:
    note:
      colors:
      - (Color 0)
      - (Color 1)
      - (Color 2)
  4. Save the file, return to UMP and go [Options] -> [Resourcepacks].
  5. Select your pack you just made, click [Done].
  6. Done!

Sync Sound to Screen

  1. Close UMP.
  2. Open config.yml file in any text editor.
  3. Look for usePlayThread: true, change it to usePlayThread: false.
  4. Save the file.
  5. Restart UMP.
This will improve audio timings but also lowers framerate.

Open AVI in AVIUtl

Japanese free video editing software AVIUtl can open UMP's AVI file by installing input plugin. This section in the manual is made for Japanese people and translated with no reason.

  1. Install L-SMASH Works to AVIUtl.
  2. Open Settings([ファイル] -> [環境設定] -> [入力プラグインの設定] -> [L-SMASH Works File Readerの設定]).
  3. Check [Libav+L-SMASH] and [LW-Libav] at the top.
  4. Restart AVIUtl or reopen project file.
  5. Make sure to check [アルファチャンネルを読み込む] for videos with transparent background.
It is impossible to use L-SMASH Works outside Japan, due to region restriction of download link.
If dropping video files on timeline isn't adding that video, right click -> [メディアオブジェクトの追加] -> [動画ファイル] to create empty video object, then drop video file on options dialog or open from [参照ファイル].
Successfully opening AVI with transparent background, adding image and texts. Don't put text like this, as it may make notes hard to see.

April Features

UMP has special features that are only available during April 1st and April 3rd JST. UMP checks for current date when starting.

Spoilers warning!

2019 (Version 1.5 and later)
2020 (Version 1.6 β2 and later)
2021 (Version 1.6 β3 and later)
2022 (Version 1.6 β4 and later)
2023 (Version 1.6 and later)

Frequently Asked Questions & Troubleshooting

Setting UMP Up

What do you mean by "for advanced users"?

UMP is designed to be familiar for Black MIDI experts or people who know how to use advanced programs.

UMP is not recommended if you:

Also see the next question for alternative MIDI players.

Actually UMP should be easy to use as long as you read this manual though...

I've seen many newbies screaming around when UMP crash, while the log literally says it's just out of memory... Please don't do that.

What are alternatives?

Recommended MIDI players (Alternatives to UMP):

Player Ease of use Notes
MIDITrail Easy Has 3D notes and note count.
Piano From Above (PFA) Easy King of MIDI player before UMP.
Kiva Intermediate Best pick if you care performance the most. Sometimes faster than UMP. Doesn't need WinMM patch.

Recommended MIDI renderers (Alternatives to UMP's Video Render):

Renderer Ease of use Notes
Zenith Expert A renderer from developer of Kiva. Has many options and customizations, thus slightly complex. Can also play MIDIs but don't expect performance.

Recommended Synths (Alternatives to UMP's recommended synth OmniMIDI):

Synth Ease of use Notes
VirtualMIDISynth Easy Simple setup.
Does it work on my phone/tablet?

No. Just buy a PC!!!

Does it work on Apple Silicon Mac?

Yes. Make sure to install Java for Apple Sillicon, or else UMP may run slower.

Does it work on Linux?

Yes. UMP should work on any desktop OS if Java 8 works.

Does it work on Java 9/10/11/12/13/14/15/16/17/18?

Probably. But remember that UMP is made on Java 8. If you encounter any issues, try Java 8 before reporting!

Does it work on Java 7?

No.

Using UMP

I can't hear anything

You're not using the synth correctly. Double-check the following:

If you have no idea what a synth or soundfont is, open your eyes and read Quick Start again.

Audio lags behind

It's a feature that allows audio to lag behind in order to mentain high framerate. You might want to do the following to maximize MIDI performance:

If audio still lags after all that, the MIDI you're playing could be too powerful for your PC. Upgrade your PC or wait for technology to advance.

You can also turn this feature off in exchange for lower framerate.

But it doesn't lag on other players...

Some MIDI players has a feature that completely skips notes to recover from audio lag. There are no plans to add that feature to UMP.

UMP sounds differently from other players

This is the best UMP can do without increasing memory usage. When making videos, audio should be generated separately using other programs such as KMC.

I can't open large MIDIs / It suddenly closes / It says 'out of memory'

UMP runs under a memory limit, and when the limit is reached, UMP will either close itself or start to glitch out. If you believe your PC has enough physical memory to load larger MIDI files, follow the Memory Allocation Tutorial to increase this limit.

It lags

Few ways to boost your FPS:

If none helps you, the MIDI you're playing is too powerful, or maybe UMP isn't good enough to run on your PC. I'm sorry. (try video render!)

I see random lag spikes

It's caused by Java cleaning memory (GC). Really hard to get rid of it completely. Video render are not affected by this.

If you're used to tune GC things, you can change JVM arguments by editing the Launcher yourself.

Rendering is not smooth when FPS limit is set

This is because UMP doesn't support VSync. Few workarounds I came up with:

UMP Features

Why doesn't UMP support some MIDI files other players can play?

Because those files are actually broken. There is no plan for supporting broken MIDI files. Ask MIDI authors for a fix.

Will you add PFA's red bar?

No. I'm leaving this difference so you can see it's not PFA in glance. I also hope you never add this.

Can notes be transparent? / Rounded corners?

No. Notes can't be transparent, even partially (like corners). UMP technology only works when notes are complete opaque.

Will you support 88/256 keys?

Not planned for now, since it'll make keys look not so good. Also you can't hear all 256 keys can you?

Will you add audio render?

Not planned as it is not the main focus of UMP. There are already a good tools for rendering audio, and even if I embed one of them in UMP, it probably won't save much time for video editing.

Others

Do I have to write credit?

No. But it'd be appreciated! Using credit overlay in video render is also a good way to credit.

Credit overlay.
Player: UMP
Video rendered with UMP 1.5
https://pipiraworld.web.fc2.com/ump/
Examples of writing credit. Link for UMP should be https://pipiraworld.web.fc2.com/ump/.
Why Java?

Because it was my primary/only language at the time I started making UMP. Actually I recently did make prototype player in C++... so... maybe? (not sure if I can even finish it though)

How many notes can UMP load?

Up to 23,455,889,992,365 notes. A MIDI file with this much notes will be 127.9TiB in size, and UMP will use around 1PiB of memory to load!

Source code?

No. Code is private as long as I continue making updates (...or maybe private forever, me in future decides that). You are not allowed to decompile.

How can I donate?

I currently don't have any way to accept direct $$$. Also who on earth would ever donate to UMP?

If you're serious and in UMP Discord server you can throw me Nitro in DM

Extra: Some History Stuff

bruh ump is so dead

2019

1.5.1

Apr 29 2019

1.5

April 1 2019

1 Year

November 17th 2018

1.4.1

September 2018

1.4

July 2018

1.3

April 2018

The make good videos guys update.

Discord server

February 11th 2018

1.2.2

December 2017

1.2.1

December 2017

1.2

December 2017

The color boost update.

1.1

November 2017

1.0.1

November 2017

1

November 17th 2017

First public version. Release announcement video acquired 620 views in first 7 days, which was incredible for tiny YT channel like me.

UMP 0

November 8th 2017

First reveal. The beginning of my busy life.

MIDIPlayerTest

??? ~ July 2017

First project to generate PFA-like image was started.

First MIDI Project

December 28th 2015

Creation date of oldest file produced from my MIDI-related project.

Menu
inserted by FC2 system