From f93980b28db76c7e50cc355330f6c82164c0e18c Mon Sep 17 00:00:00 2001 From: Christopher Arndt Date: Sun, 7 Apr 2024 12:51:52 +0200 Subject: [PATCH] Attempt to improve README.md - Spelling fixes - Grammar fixes - Consistent capitalization (headings and text) - Some re-wording and sentence restructuring for better readability, clarity and style - Some added/changed Markdown formatting - Keyboard shortcuts table - Install commands as pre-formatted shell session sections - Various minor changes, such as using backticks. - Moved section "Build with localization support" under the previous section --- README.md | 211 +++++++++++++++++++++++++++++------------------------- 1 file changed, 114 insertions(+), 97 deletions(-) diff --git a/README.md b/README.md index 826fb93..6d4c5b7 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,130 @@ # Mamba -Virtual MIDI Keyboard and MIDI file player/recorder for Jack Audio Connection Kit -![Mamba](https://github.com/brummer10/Mamba/raw/master/Mamba.png) +Virtual MIDI keyboard and MIDI file player/recorder for the JACK Audio Connection Kit +![Mamba](https://github.com/brummer10/Mamba/raw/master/Mamba.png) ## Description ### Virtual MIDI Keyboard -Mamba comes with some predefined key-maps, qwertz, qwerty, azerty(fr) and azerty(be), but you could define your own -with the included Key-map Editor as well. Beside the computer keyboard and mouse, Mamba supports jack-interconnect-ALSA MIDI in and -out. Every channel use it's own Colour to display the played Notes per channel. -Jack and ALSA connections could be mannaged within the connection menu. +Mamba comes with some predefined key-maps: QWERTZ, QWERTY, AZERTY (fr) and AZERTY (be), but you can +also define your own key-maps with the included key-map editor. In addition to computer keyboard +and mouse input, Mamba also supports JACK and ALSA MIDI In and Out connections. Incoming MIDI notes +are displayed on the keyboard, each with their own colour according to their MIDI channels. JACK +and ALSA connections can be managed within the connection menu. -Mamba implements full [Scala](https://www.huygens-fokker.org/scala/) tuning support, means it could load Scala tuning files (*.scl) and Scala Keymap files (*.kbm) -to support microtonal tunings. Those could be loaded by simply drag n' drop or over the File menu. -The Keyboard layout "tries" to reflect the loaded tuning ratio scala. -MIDI Keyboard mapping works for jack as for alsa MIDI input. +Mamba implements full [Scala](https://www.huygens-fokker.org/scala/) tuning support, which means it +can load Scala tuning files (`*.scl`) and Scala MIDI keymap files (`*.kbm`) to support micro-tonal +tunings. These can be loaded simply via drag and drop or via the "File" -> "Load Scala" menu. The +keyboard layout "tries" to reflect the loaded tuning ratio scala. MIDI keyboard mapping works for +both JACK and ALSA MIDI input. -The MIDI-CC controllers on GUI could be controlled by the mouse or the keyboard. With the mouse you could use the mouse-wheel, -or, press the left mouse button and move the mouse up/down. A special case is the Pitch-wheel control, to use it with the -mouse-wheel, you must press the mouse-wheel while moving it. This is because of the spring back to default value behave of -the Pitch-wheel. So, when you release the mouse-wheel press, the Pitch-wheel controller will spring back to default value '64'. +The MIDI-CC control dials on the GUI can be used via the mouse or the keyboard. Using the mouse you +can hover over a dial and turn the mouse-wheel, or left-click and drag the mouse up/down. The +pitch-wheel control is a special case: to use it with the mouse-wheel, you need to press the +mouse-wheel while moving it. This is because of the auto-return-to-default value behaviour of the +pitch-wheel. This means, when you release the mouse-wheel press, the pitch-wheel control will +spring back to its default value `64`. -To use the keyboard to controll the MIDI-CC controllers on GUI you could use the up/down key's on your PC-keeyboard. -To select a controller it must be under the mouse pointer. When using the PC-keyboard to control the Pich-wheel, it wouldn't -spring back to default. +To change the MIDI-CC control dials on the GUI via the PC keyboard, use the up/down arrow keys. For +a control to receive keyboard input, it must be under the mouse pointer. When using the PC keyboard +to control the pitch-wheel, it does not spring back to the default value. -### 16 Channel Live MIDI Looper/Recorder: +### 16 Channel Live MIDI Looper/Recorder -To record a loop, press "Play" and then to start recording press "Record". -To stop recording press record again. Playback will start immediately. +To record a loop, press "Play" and then, to start recording, press "Record". To stop recording +press "Record" again. Playback will start immediately. -The first recorded channel will become the Master channel. This one set the time frame for all later recorded loops. -For the Master Channel the recording time will be stretched/clipped to match the next full beat time point. +The first recorded channel will become the Master Channel loop. This loop sets the length for all +loops recorded afterwards. The loop length of the Master Channel will be adjusted (i.e. extended or +cut) to the nearest full beat according to the tempo . -To record a new loop, switch to a other channel, select your instrument and press "Record" again to start recording. +To record a new loop, switch to another MIDI channel, select your instrument and press "Record" +again to start recording. -The later recorded loops will be synced to the master loop. When the recording time extend the absolute Master loop time -record will be switched off. Absolute time is not bound to the loop point, so you could record loops crossing it. -You could as well stop recording by press "Record" again before the time expires. +The loops recorded after the Master Channel loop will be synced to it. When the recording time +exceeds the absolute Master Channel loop time, recording will be turned off, but the playback +continues and loops back. Absolute time is not bound to the loop point, so you can record loops +crossing it. You can also stop recording by pressing "Record" again before the time expires. -Each Channel could be cleared and re-recorded separate at any time. -even when you press "Record" on a already recorded channel, it will be cleared before recording starts. +Each Channel can be cleared and re-recorded separately at any time. When you press "Record" on an +already recorded channel, it will be cleared automatically before recording starts. -You could record the connected input device or play the Keyboard itself. +You can record events from the connected MIDI input device or use the the keyboard to play and +record. -### MIDI File player +### MIDI File Player -You could select a MIDI file with the File Selector, or just drag'n drop it from your Filemanager on the Keyboard. -It will be loaded in the play buffer of the first channel, regardless how much channels it use. -You could use then channel 2 - 16 to record your own playing into it. To play along with it you could use any channel. -A loaded file will become the Master channel for the looper. +You can select a MIDI file via the menu "File" -> "Load MIDI", or just drag and drop a MIDI file +from your file manager onto the keyboard. It will be loaded into the play buffer of the first +channel, regardless of how many MIDI channels it uses. You can then use channels 2 - 16 to record +your own playing on top of it. To play along with it you can use any channel. A loaded MIDI file +will become the Master Channel loop of the looper. -To save your work just go to Menu -> "File" -> "Save MIDI file as", select the path and enter a file name. -If you don't give the usual file extension Mamba will add the extension .midi befor save it. +To save your work, just go to menu "File" -> "Save MIDI file as", select a path and enter a file +name. If the filename doesn't have one of the common MIDI file name extensions, Mamba will add the +extension `.midi` before saving the file. -### Fluidsynth +### FluidSynth -![Fluidsynth-settings](https://github.com/brummer10/Mamba/raw/master/Fluidsynth-settings.png) - -You could load a Sound-font via the Menu -> "Fluidsynth" -> "Load Sound-font", or drag'n drop it from your Filemanager on the Keyboard. -Mamba will start the Fluidsynth engine and do the needed connections so that you could just play along. -Menu -> "Fluidsynth" -> "Settings" will pop-up a new Window were you could select the Instrument for the channel and do settings for Fluisynth Reverb and Chorus. -As well you could select there your tuning scale to use, available options been Just Intonation, 12-edo or Scala. -All your Settings will be saved on exit, so on next start you could just play along. +![FluidSynth settings](https://github.com/brummer10/Mamba/raw/master/Fluidsynth-settings.png) +You can load an SF2 SoundFont via the menu "Fluidsynth" -> "Load SoundFont", or drag and drop it +from your file manager onto the keyboard. Mamba will start the FluidSynth engine and create the +necessary connections so that you can just start playing the SoundFont. The menu "Fluidsynth" -> +"Settings" will open a new window were you can select the instrument for the currently selected +MIDI channel and change the settings for the FluidSynth reverb and chorus. Also, you can select the +tuning scale to use there; the available options are *Just Intonation*, *12-edo* or *Scala*. All +your Settings will be saved on exit, so when you next open the application you can just start +playing. ## Features -- Virtual MIDI Keyboard for [Jack Audio Connection Kit](https://jackaudio.org/) -- Including [ALSA](https://www.alsa-project.org/wiki/Main_Page) MIDI support -- Including [NSM](https://linuxaudio.github.io/new-session-manager/) support -- Including [gettext](https://www.gnu.org/software/gettext/) localization support -- Including [fluidsynth](https://github.com/FluidSynth/fluidsynth) support -- Sound-font loader for fluidsynth -- Controls for fluidsynth reverb, chorus and channel pressure -- Instrument selector for fluidsynth -- Microtonal tuning for fluidsynth -- Channel selector -- Bank and Program selector -- Keyboard mapping for qwertz, qwerty, azerty(fr) and azerty(be) selectable from menu -- Key-map Editor to setup a custom Key-map -- PC Keyboard mapping selector from C0 to C4 -- Pitch-bend, Balance, Mod-wheel, Detune, Expression, Attack, Release, Volume and Velocity controllers -- Sustain and Sostenuto switches -- Connection management Menu -- Support MIDI-file load, save, record and play in loop +- Virtual MIDI keyboard for [JACK Audio Connection Kit](https://jackaudio.org/) +- Includes [ALSA](https://www.alsa-project.org/wiki/Main_Page) MIDI support +- Includes [NSM](https://linuxaudio.github.io/new-session-manager/) support +- Includes [gettext](https://www.gnu.org/software/gettext/) localization support +- Includes [FluidSynth](https://github.com/FluidSynth/fluidsynth) support +- SoundFont loader for FluidSynth +- Controls for FluidSynth reverb, chorus and channel pressure +- Instrument selector for FluidSynth +- Micro-tonal tuning for FluidSynth +- MIDI Channel selector +- MIDI Bank and Program selector +- Keyboard mapping for QWERZ, QWERTY, AZERTY (fr) and AZERTY (be) selectable from the menu +- Key-map editor to set up a custom key-map +- PC keyboard mapping selector from C0 to C4 +- Control dials for sending MIDI Pitch-bend, and MIDI Control Changes (Balance, ModWheel (Modulation), Detune, Expression, Attack, Release and Volume) and setting the Note On velocity +- MIDI Sustain and Sostenuto controller switches +- Connection management menu +- Supports MIDI file loading, saving, recording and loop-playing - BPM controller for playback speed -- Support MIDI Beat Clock for playback speed -- MIDI Through: forward ALSA MIDI in to jack -- MIDI Through: forward MIDI input to output -- MIDI input highlighting -- Resizeable to a full range 127 key view -- Load MIDI-files on command-line -- Support jack_transport to start/stop MIDI-Loops -- Support loading (*.scl) tuning files -- Support loading (*.kbm) Midi Keyboard mapping files -- Keyboard Shortcuts - - `ctrl + 0-4` change octave - - `ctrl + t` toggle MIDI Through - - `ctrl + g` toggle Grab Keyboard - - `ctrl + r` toggle Record Button - - `ctrl + p` toggle Play Button - - `ctrl + l` open load file dialogue - - `ctrl + s` open save file dialogue - - `ctrl + a` show info box - - `ctrl + k` show Key-map Editor - - `ctrl + q` quit - - `ctrl + c` quit - +- Supports MIDI Timing Clock for playback speed +- MIDI Through: forwarding ALSA MIDI in to JACK +- MIDI Through: forwarding MIDI input to output +- MIDI input notes highlighting on keyboard +- Resizable up to a full-range 127 keys view +- Load MIDI files from the command-line +- Supports JACK transport to start and stop MIDI-Loops +- Supports loading Scala tuning (`*.scl`) files +- Supports loading Scala MIDI keyboard mapping (`*.kbm`) files + +## Keyboard Shortcuts + +| Shortcut | Function | +| ------------- | ------------------------ | +| `ctrl + 0-4` | change octave | +| `ctrl + t` | toggle MIDI Through | +| `ctrl + g` | toggle Grab Keyboard | +| `ctrl + r` | toggle Record Button | +| `ctrl + p` | toggle Play Button | +| `ctrl + l` | open load file dialogue | +| `ctrl + s` | open save file dialogue | +| `ctrl + a` | show info box | +| `ctrl + k` | show Key-map Editor | +| `ctrl + q` | quit | +| `ctrl + c` | quit | ## Dependencies @@ -129,16 +144,18 @@ All your Settings will be saved on exit, so on next start you could just play al ## Build -- git submodule init -- git submodule update -- make -- sudo make install # will install into /usr/bin - - -## Build with localization support - -- git submodule init -- git submodule update -- make nls -- sudo make install # will install into /usr/bin - +```con +git submodule init +git submodule update +make +sudo make install # will install into /usr/bin +``` + +### With Localization Support + +```con +git submodule init +git submodule update +make nls +sudo make install # will install into /usr/bin +```