1% Help Index 2 3## Introduction 4 5This application is a multiplatform MIDI file player for Linux, Windows and 6macOS. It reads .MID (Standard MIDI Files), .KAR (Karaoke), and .WRK (Cakewalk) 7file formats, and outputs MIDI events to hardware MIDI ports and also software 8synths. 9 10[Drumstick](https://drumstick.sourceforge.io) is a set of GPLv3 11licensed C++/Qt libraries for MIDI applications. The project includes several 12tools as examples, and among them is the drumstick-guiplayer utility that 13leverages the Drumstick::ALSA library, so it is available only for Linux 14(because the ALSA sequencer is a Linux only technology). Some people have 15requested a program with the same functionalities on Windows and macOS, and 16here it is. But this program is much more than that, and it also works on 17Linux... 18 19Some key features: 20 21* MIDI Output to hardware MIDI ports, or any other Drumstick backend like soft 22 synths 23* [Transpose](https://en.wikipedia.org/wiki/Transposition_(music)) song tonality 24 between -12 and +12 semitones 25* Change MIDI volume level (using MIDI CC7) 26* Scale song speed between half and double 27 [tempo](https://en.wikipedia.org/wiki/Tempo) 28* Lyrics, Piano Player and MIDI Channels views 29* Supports MID/KAR (Standard MIDI Files) and WRK (Cakewalk) file formats 30 31## MIDI Output 32 33Any MIDI Player outputs MIDI events only, but no sound. To produce sound, a MIDI 34Synthesizer is needed to render the events into digital audio that can be 35reproduced by the computer's (or external) audio speakers. The events can also 36be rendered by an external musical MIDI instrument connected to the computer, 37for instance a MIDI organ, piano, or synthesizer with an USB interface. If that 38option is not available, another usual alternative is a software synthesizer 39(a program). 40 41There are software synthesizers included in the computer's operating systems, 42for instance Microsoft Windows includes the "Microsoft GS Wavetable Synth", and 43Apple macOS includes the "Apple DLS Synthesizer". To use them, you need to open 44the "MIDI Setup" dialog and then: 45 46* In **Windows**, select the "Windows MM" option in the first list box, and 47 "Microsoft GS Wavetable Synth" in the second list box. Instead of this synth, 48 which is very basic and limited, you may prefer a better/free alternative like 49 [Virtual MIDI Synth](https://coolsoft.altervista.org/en/virtualmidisynth) 50 that will show as "VirtualMIDISynth #n" in the second list box when running. 51 If you have an external MIDI instrument attached to the computer, its name 52 should appear in the second list box as well. 53* In **macOS**, select "DLS Synth" in both the first and second list boxes. 54 This synth has a configuration option for using DLS or SF2 soundfont files if 55 you want. To use another connected MIDI device or software synth, 56 you need to select "CoreMIDI" in the first list box, and the name of your 57 synth in the second one. 58* In **Linux** and other **Unix** Operating Systems, "SonivoxEAS" is a soft 59 synth ready to be used. It is a very basic GM synth which doesn't use files 60 and depends only on the PulseAudio sound system. For external devices attached 61 to the computer or arbitrary soft synths, you need to select "ALSA" (or "OSS") 62 in the first list box. 63* **FluidSynth** is another included open software synth that is multiplatform 64 and available on all operating systems. It is very configurable, accepting 65 soundfont files and many digital audio sound systems. Select 66 [FluidSynth](https://github.com/FluidSynth/fluidsynth) on both list boxes 67 to use it. 68* **Network** is a multiplatform UDP Multicast output, that may be used to send 69 MIDI events as network packets to other computers and devices in the same 70 local area network. It is compatible with 71 [ipMIDI](https://www.nerds.de/en/ipmidi.html), 72 [QmidiNet](https://qmidinet.sourceforge.io/), and 73 [multimidicast](https://llg.cubic.org/tools/multimidicast/) 74 among other software. 75 76## Playback Controls 77 78The following standard actions are available in the `File` menu and also the 79tool bar, with the conventional functionalities on any media player: 80 81* `Play` 82* `Pause` (and continue) 83* `Stop` 84* `Fast Forward` (by 1 bar) 85* `Rewind` (by 1 bar) 86 87By default, `Play` is activated automatically upon loading a MIDI file except 88when this feature is disabled in the configuration dialog. 89 90The `status bar`, optionally located at the bottom of the main window, shows 91the current playback status as "Playing", "Stopped", "Paused", etc. 92 93### Transpose 94 95The `Pitch control` is located in the main window. It is a spin box initialized 96to zero, with a valid range from -12 to +12 semitones. The limits are equivalent 97to one octave up or down the original tone. This should be enough for singers 98or instrumentalists needing to adjust the tonality for their comfort. 99 100All MIDI channels are chromatically transposed, except the percussion channel 101(GM channel 10 by default). 102 103### Volume Level 104 105The `Volume control` is located in the main window. It is a slider, initialized 106to 100%, with a valid range from 0% to 200%. The upper limit effect may be lower 107because the MIDI CC 7 has a valid range from 0 to 127. There is also a button to 108`Reset Volume`. 109 110### Tempo 111 112The `Tempo control` is located in the main window. It is a slider initialized 113to 100% with a valid range from 50% to 200%. There is a button to `Reset Tempo` 114and also a tempo display, showing the effective tempo in beats per minute with 115an initial value of 120 bpm. This is the default tempo for a MIDI file if it 116does not contain a tempo change. This value is updated when changing the 117tempo control, and also while a MIDI file containing tempo changes is playing. 118 119### Jump, Loop and Positioning 120 121`Jump` action (located in the `File` menu and the default tool bar), asks for 122a bar number, between 1 and the last bar of the loaded song, to change the 123current position of the song to the given bar. 124 125`Loop` action (located in the `File` menu and the default tool bar), asks for 126two bar numbers. The song will be played between the two given bars when it is 127activated. You can switch off the loop any moment selecting the action again. 128 129The `Positioning control` is located in the main window. It is a slider that 130moves while the current played position changes, and can be moved by hand to 131change the position to any arbitrary point within the song. 132 133## Views 134 135The following options are enable in the `View` menu: 136 137Three views are independent windows that you may open and close at your 138convenience: Channels, Lyrics and Piano Player. 139 140On the other hand, you also can hide or show three more views that are embedded 141on the main window: Tool bar, Status bar, and Rhythm. 142 143### Channels 144 145This window shows up to 16 rows, one for each MIDI channel used by the current 146MIDI file. The columns are: 147 148* MIDI channel number and text (editable). Usually the instrument name, or a 149 brief description taken from the file metadata. 150* Mute button. With this option the current channel may be muted. 151* Solo button. Raises the volume of the current channel, while lowering the 152 other channels. 153* Level. Indicator of the activity on the current channel. 154* Lock. This button fixes the Patch on the current channel, preventing changes 155 stored on the file. 156* Patch. Corresponds to the MIDI Program Change events according to the General 157 MIDI list of instrument names. 158 159### Piano Player 160 161This window shows up to 16 rows, one for each MIDI channel used by the current 162MIDI file. Each row contains: 163 164* A channel number and text (the same data as the Channels window) 165* A piano keyboard. The keys will be highlighted with a color, that can be fully 166 customized, by the MIDI note events played by the current MIDI file. It may 167 also optionally show the note names as well. The keys may be activated 168 manually using the computer keyboard and the mouse 169 170There is a window menu, with the following options: 171 172* View Full Screen. Enlarges the window filling the current monitor 173* Show all channels 174* Hide all channels 175* Tighten the number of keys. By default, each keyboard shows 88 keys, from A0 176 to C8. Using this option, the keyboards use only the number of octaves really 177 used by the MIDI file, which is usually a smaller number 178* Up to 16 Channel options, to hide or show each channel individually. By 179 default all MIDI channels used in the current MIDI file are selected 180 181### Lyrics 182 183This window shows the text metadata from the loaded MIDI file, filtering the 184data with a series of controls located on the window tool bar: 185 186* Track: a list box to choose among "All tracks", or one item Corresponding to 187 each used track in the loaded MIDI file. This track number replaces the 188 concept of MIDI channel in this window, because the text metadata doesn't have 189 a channel attribute, but it always belongs to some track. By default, the 190 track containing more data is automatically selected 191* Type: a list box to choose one of the metadata text types or all of them. The 192 `Lyric Events` type is the most probable choice 193* Encoding: the text encoding is automatically detected, but in some cases the 194 detection may be incorrect, so the correct one can be selected manually 195 196There is a window menu, with the following options: 197 198* Copy to clipboard: copies the metadata currently shown by the window 199* Save to file... After opening a Save File dialog, this option creates a text 200 file on disk, with the text shown by the window and the selected encoding 201* Print... After opening a Print Dialog, this option prints the text shown by 202 the window on the selected printer 203* Full Screen: Enlarges the window filling the current monitor 204* Font... Opens a Font Selection window to choose the typography and size for 205 the window texts 206 207## Playlists 208 209Playlists are collections of file names, that can be used to play a series 210of MIDI pieces, like a musical "repertoire". 211 212The `File`->`Play List...` action manages the creation, modification, ordering, 213opening, and saving Play list files. This window shows the current playlist 214file name in the window title. 215 216The `File`->`Next` and `File`->`Prev` actions are used to navigate the playlist 217manually forward and backward. There are configuration options to start playback 218automatically after loading MIDI files, and advance automatically to the next 219playlist item when finished playing the current item. Both configuration options 220are enabled by default. 221 222The initial default playlist contains a collection of example MIDI files. If 223you prefer to start with an empty list, you should use the `Clear` button and 224then saving the empty playlist with a meaningful name. This will be the new 225initial playlist in the future. 226 227The last opened or saved playlist file shall be remembered the next time the 228program is started, but playlists are not saved automatically. 229 230Playlists are simple text files, with a file name on each text line. The file 231names can be relative to the location of the playlist file itself (so they do 232not have an absolute path prepended) or each file can have an absolute path on 233its own. 234 235You may have several playlists that can be created easily outside of the 236program, for instance in the Linux command line this command creates a playlist 237file named "my_playlist.lst" with all the MIDI files located at the working 238directory: 239 240~~~ 241$ ls -1 *.mid > my_playlist.lst 242~~~ 243 244## Opening MIDI Files 245 246You can open individual files... 247 248* Using the `File`->`Open` standard action 249* Using the `File`->`Open Recent Files` menu, which remembers up to ten files 250 recently opened. 251* Providing the file name(s) in the command line. The set of files becomes a 252 temporary play list. This allows easy integration of the program with file 253 managers using "Open With..." actions. 254* Dragging and dropping file(s) from a file manager into the main window. The 255 set of files becomes a temporary play list. 256 257## Customization 258 259### Preferences 260 261There is a `Restore Defaults` button to initialize all options in this dialog 262to their default values. 263 264There are three tabs, grouping the configuration settings 265 266#### General 267 268* Percussion MIDI Channel: Number from 1 to 16. Default 10, corresponding to the 269 General MIDI standard percussion channel 270* Start Playback Automatically After Loading. Enabled by default 271* Advance Automatically to the Next PlayList Item. Enabled by default 272* Force Dark Mode. May be useful on Windows. On Linux and macOS the dark mode is 273 automatically applied when configured in the Operating System 274* Use Internal Icon Theme. This setting is needed on Windows and macOS. 275* Qt Widgets Style. Depending on the operating system, affects the visual 276 integration with other programs 277* MIDI System Exclusive Reset. The player sends this message just before start 278 playing each MIDI file 279 280#### Lyrics 281 282* Text Font. Opens a Font Selection window to choose the typography and size for 283 the window texts. This setting is also available on the Lyrics window menu 284* Future Text Color. This setting applies to the text that has not been played 285* Past Text Color. This setting applies to the text that has been already played 286 287#### Player Piano 288 289* Note highlighting. There are a few highlighting palettes available 290* Single highlight color. When the single color highlight palette is selected, 291 this setting is the note highlighting color 292* Note velocity to color tint. With this option, MIDI note events velocity 293 attribute is used to give the highlighting color a lighter or darker tone 294* Note names font. Opens a Font Selection window to choose the typography and 295 size of the note names 296* Show note names: available choices are Never, Minimal, When activated, always. 297 The Minimal option shows only the names of the C keys. 298 299### Toolbar Customization 300 301The tool bar is located on the main window, which has typically very small 302available space, and can be moved to the top or the bottom of the window, and 303also outside of it. The actions available as tool buttons can be configured in 304this dialog window. All actions are also main menu items. 305 306* Available actions: shows the list of actions not currently being displayed as 307 tool buttons 308* Selected actions: is the list of currently selected tool buttons 309 310To select one action from the Available list, first select it with the mouse and 311then press the "add" button. The action is removed from the Available list and 312placed at the end of the selected list. 313 314To remove one button from the tool bar, select it with the mouse in the Selected 315list and then press the "remove" button. 316 317To reorganize the order of buttons in the tool bar, use the "up" and "down" 318buttons after selecting an item in the Selected list. 319 320Style of the Tool Buttons: contains the following options that apply to all 321the buttons in the tool bar 322 323* Icon Only 324* Text Only 325* Text Beside Icon 326* Text Under Icon 327* Follow Style: The setting is determined by the "Qt Widgets Style" setting 328 in the Preferences dialog. 329