# Introduction
This program is a lightweight MIDI player for Windows that uses the Timidity software synthesizer. It can play and convert standard MIDI files to WAV, as well as synthesize MIDI events from a live input source such as a controller keyboard.

## Disclosure
The source code for this application was mostly generated by a large language model. Before publication, the code was thoroughly reviewed and checked for errors. If any significant bugs are found, please report them to the author of this application so they can be investigated and fixed in future revisions.

# System Requirements
The minimum supported Windows version is 2000, and the default synthesizer configuration performs realtime synthesis reasonably well on a 266 MHz Pentium II processor. The minimum RAM recommendation is 128 MB, however 256 MB is recommended for large sample banks.

# Getting Started
When the application is launched for the first time, an error will pop up if the synthesizer fails to load its instrument configuration. To resolve this, open the Timidity configuration dialog, and browse to a previously downloaded configuration file. If a file named timidity.cfg exists in the application's working directory, the synthesizer will attempt to load this file if the configuration file path hasn't already been set.

## The Main Window
By default, the main window shows a status bar, seek bar, and playlist view. When the playlist view is enabled, pressing tab shifts focus to the list, and pressing tab again shifts focus back to the main window. When the list view is in focus, navigation keys are intercepted by the list view control. Pressing enter on a selected list item plays it, and pressing delete removes it from the playlist. The application can also be moved to the top of the z-order by enabling the Always On Top option in the system menu.
A context menu is available as well, and the available options depend on the control that was right-clicked, or the control that currently has keyboard focus. When the control is the playlist view, the menu options are relevant to the selected item. In all other cases, the menu options are relevant to the currently loaded file.

## Converting to WAV
To render the currently loaded MIDI file to a WAV file, Select Convert to WAV from the file menu. While the conversion is in progress, the status bar is updated with the current percentage. When the conversion is done, a message box will pop up and display the full path to the output file.
You can also use the batch converter to convert multiple files to WAV. If there is more than one item in the playlist and you open the batch converter, you are asked if you want to add the files to the converter's file list.

# Configuration
## Timidity
The Timidity Configuration dialog is for configuring the synthesizer itself. Note: the Timidity configuration is stored in a shared location in the registry. As a consequence, importing, exporting, or restoring settings in the application won't have an effect on the behavior of the synthesizer. The reason for this architecture is so that other projects that use the same engine (such as the Timidity Windows MIDI Driver) share a common synthesizer configuration. If you have configured Timidity to run well on your particular machine, having that configuration persist across multiple programs is a convenience feature.
If you tend to listen to more complex MIDI sequences, it is recommended to increase the Voices setting to help prevent lost or cut notes during complex passages. The control rate setting determines how accurately envelopes and tremolo are rendered, and higher values tend to use more processor time. If you are on a really slow machine, it is recommended to leave this setting at its default value. If you frequently encounter audible clipping, reducing the amplification setting can help resolve this issue.
By default, the synthesizer attempts to load all instruments into memory when loading the configuration file. If you are on a system that doesn't have a lot of RAM, it is recommended to enable dynamic instrument loading, as this causes the engine to only load instruments as they are needed. If you are rendering at a lower sample rate, anti aliasing can help reduce audible artifacts that may occur as a result of sample rate reduction. Fixed pitch instruments can be resampled at load time to reduce CPU load during synthesis, however this has a side-effect of pitch bend and modulation messages not having an effect on samples that have been processed in this way.
Environmental reverb and chorus can be enabled to add spacial depth to the audio. however, this can result in significant CPU load on slower machines, as these effects heavily use floating point arithmetic. To randomize quantization distortion, dithering can be applied to the final output.

## Audio Output
The buffer and chunk size settings control how audio is delivered to the selected device. The defaults should be fine for most situations, however if you are getting choppy playback, it is recommended to increase these settings. The buffer size determines the maximum amount of audio that is queued, while the chunk size determines how much of the buffer is sent to the audio driver at once.
If you have a computer keyboard that has the ability to adjust audio volume, you can configure the application to intercept the volume up and down keys. If volume key interception is enabled, the volume keys won't be able to adjust the system volume while the application is running.

## MIDI Input
The MIDI input feature allows the synthesizer to be controlled from a MIDI input source, such as a controller keyboard or virtual MIDI cable. When the Enable MIDI Input checkbox is unchecked, the device selection combo box is disabled. You can also configure a custom channel map, which is useful if you want to control another MIDI channel while you are using a device that only sends MIDI data on a single channel.

# Tools
The options in the tools menu only have an effect while a file is playing, or while live MIDI input is active.

## Channel Mixer
The channel mixer allows you to adjust MIDI channel parameters in realtime. The controls are automatically refreshed every 200 milliseconds, unless one of the sliders is currently being dragged.

## Virtual Keyboard
The virtual keyboard allows you to send note data by clicking virtual piano keys. While one of the virtual keys has keyboard focus, the arrow keys can be used to move between virtual keys, and space can be pressed to activate the virtual key that is currently in focus. While the virtual keys are held down, the pressure slider can be dragged to send polyphonic aftertouch messages to the synthesizer. If focus to the virtual keys is lost, all held notes are released.

## Inject MIDI Message
This is a lower level tool that allows you to inject raw MIDI bytes into the synthesizer. The supported messages are note off, note on, polyphonic aftertouch, control change, program change, and pitch bend.

# Command-line operation
You can pass file and folder paths on the command-line to add them to the player. Wildcards are also supported. If the /add switch is added after the name of the executable, the files are added without discarding the current playlist. The /c switch opens the program straight into the batch converter, and besides file and folder paths, the following switches become available when this option is invoked.
* /o followed by a directory path: sets the output directory.
* /f followed by a number ranging from 0 to 6: sets the output PCM format. The supported formats are 8 through 32-bit integer, 32 and 64-bit floating point, and 8-bit uLlaw.
* /w: enables the overwriting of existing files.
* /p: preserves the folder structure of the input paths when generating the output paths.
* /a: automatically starts the conversion.
* /s: saves a CSV file of the conversion statistics in the output directory. The name of this file is the word conversion followed by the current date and time.

# Shortcut Key Reference
* Open MIDI Files: Ctrl+O
* Add MIDI Files: Ctrl+A
* Add Folder: Ctrl+Shift+A
* Paste Files: Ctrl+V
* Clear Recent Files: Ctrl+Shift+L
* Open Playlist: Ctrl+Shift+O
* Save Playlist: Ctrl+Shift+S
* Unload Current File: Ctrl+U
* Clear Playlist: Ctrl+Shift+C
* Convert currently loaded file to WAV: Ctrl+W
* Batch Converter: Ctrl+B
* Play: Space
* Stop: Esc
* Next Track: Ctrl+Right
* Previous Track: Ctrl+Left
* First Track: Ctrl+Shift+Left
* Last Track: Ctrl+Shift+Right
* Fast Forward: Right
* Rewind: Left
* Restart: Ctrl+R
* Jump to End: Ctrl+E
* Jump to Time: Ctrl+J
* Sleep Timer: Ctrl+T
* Shuffle Playlist: Ctrl+H
* Manage Playlist: Ctrl+M
* Playback Statistics: Ctrl+I
* Volume Up: Up
* Volume Down: Down
* Configure Timidity: Ctrl+G
* Configure Audio Output: Ctrl+Shift+D
* Player Options: Ctrl+P
* Configure MIDI Input: Ctrl+Shift+M
* Export Settings: Ctrl+X
* Import Settings: Ctrl+Shift+I
* Restore Default Settings: Ctrl+Shift+R
* Channel Mixer: Ctrl+C
* Virtual Keyboard: Ctrl+K
* Inject MIDI Message: Ctrl+Shift+J
* All Notes Off: Ctrl+N
* All Sounds Off: Ctrl+S
* Reset Controllers: Ctrl+Q
* MIDI Panic: F9
* MIDI Reset: F10
* Reload Timidity Configuration: Ctrl+Shift+G
* Reload Current MIDI File: Ctrl+Shift+F
* Force All Instruments to Load: Ctrl+F
* Free Default Instrument: Ctrl+D
* Unload Timidity Configuration: Ctrl+Shift+U
* Restore Default Engine Settings: Ctrl+Shift+E
* Show or Hide Status Bar: Ctrl+Y
* Show or Hide Seek Bar: Ctrl+L
* Show or Hide Playlist View: Ctrl+Z
* About: F1
