From 43cf2f2fd637732e4862f0793e5f632db0aa8575 Mon Sep 17 00:00:00 2001 From: Tom Yaxley Date: Sat, 18 May 2019 20:43:35 +1000 Subject: [PATCH] Updated README --- README.md | 93 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 62 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index c7cef27bc..9df87d1a5 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,19 @@ A VST wrapper around the SameBoy GameBoy emulator, with Arduinoboy support ## Features -- Wraps [SameBoy](https://github.com/LIJI32/SameBoy) 0.1.2 +- Wraps [SameBoy](https://github.com/LIJI32/SameBoy) v0.1.2 - Full MIDI support for [mGB](https://github.com/trash80/mGB) - Syncs [LSDj](https://www.littlesounddj.com) to your DAW - Emulates various [Arduinoboy](https://github.com/trash80/Arduinoboy) modes -## Download -Visit the [releases](https://github.com/tommitytom/RetroPlug/releases) page to download the latest version. - ## Current limitations (subject to change) - VST2 only - Windows only - 64bit only +## Download +Visit the [releases](https://github.com/tommitytom/RetroPlug/releases) page to download the latest version. + ## Usage - Load it as you would any normal VST - Double click to open file browser, or drag a rom on to the UI to load @@ -25,31 +25,21 @@ Visit the [releases](https://github.com/tommitytom/RetroPlug/releases) page to d - For mGB, the usual Arduinoboy rules apply: https://github.com/trash80/mGB - no additional config needed, just throw notes at it! - For LSDj, an additional menu will appear in the settings menu, allowing you to set sync modes (Arduinoboy emulation) -## LSDj sync modes -- **Off**: no sync with your DAW at all. If you hit play in LSDj it will play regardless of what else is happening. - -- **MIDI Sync**: Receives MIDI clock from your DAW when the transport is running. If you hit play in LSDj, it will not play until you hit play in your DAW. LSDj should be set to "MIDI" mode on the project page. In this mode LSDj knows nothing about the song position in your DAW, all it knows is that it is receiving a MIDI clock, and that it should play. - -- **MIDI Sync (Arduinoboy mode)**: Receives MIDI clock from your DAW, but only plays once a C-2 note is received. Additional Arduinoboy options are emulated, full list can be found here: https://github.com/trash80/Arduinoboy/#mode-1---lsdj-as-midi-slave-sync - -- **MIDI Map**: Receives MIDI clock from your DAW, and plays the row number relative to MIDI notes that you send it. C-0 is row 0, C#-0 is row 1, etc. Rows are stopped when note offs are received, or when you hit stop in your DAW. Requires the Arduinboy build of LSDj. - ## Button mapping -On first run a config file is written to `C:\Users\USERNAME\AppData\Roaming\RetroPlug` containing the following default button map: -``` -{ - "A": "Z", - "B": "X", - "Down": "DownArrow", - "Left": "LeftArrow", - "Right": "RightArrow", - "Select": "C", - "Start": "Enter", - "Up": "UpArrow" -} -``` - -## Supported keys for buttons.json: +Keyboard button mapping is currently only configurable with JSON configuration files. On first run a config file is written to `C:\Users\USERNAME\AppData\Roaming\RetroPlug` containing the following default button map: + +|Button|Default key| +|------|-----------| +|A|Z| +|B|X| +|Up|UpArrow| +|Down|DownArrow| +|Left|LeftArrow| +|Right|RightArrow| +|Select|Ctrl| +|Start|Enter| + +### Supported keys for buttons.json: Keys `0 - 9` and `A - Z` can be used for alpha numeric keys, as well as the following keys: ``` @@ -57,6 +47,47 @@ Backspace, Tab, Clear, Enter, Shift, Ctrl, Alt, Pause, Caps, Esc, Space, PageUp, ``` All key names are CASE SENSITIVE! +## LSDj specific settings +### Sync modes +- **Off**: No sync with your DAW at all. If you hit play in LSDj it will play regardless of what else is happening. + +- **MIDI Sync**: + * Receives MIDI clock from your DAW when the transport is running. + * If you hit play in LSDj, it will not play until you hit play in your DAW. LSDj should be set to "MIDI" mode on the project page. + * In this mode LSDj knows nothing about the song position in your DAW, all it knows is that it is receiving a MIDI clock, and that it should play. + +- **MIDI Sync (Arduinoboy mode)**: + * Receives MIDI clock from your DAW, but only plays once a C-2 note is received. + * Additional Arduinoboy options are emulated, full list can be found [here](https://github.com/trash80/Arduinoboy/#mode-1---lsdj-as-midi-slave-sync). + +- **MIDI Map**: + * Receives MIDI clock from your DAW, and plays the row number relative to MIDI notes that you send it. C-0 is row 0, C#-0 is row 1, etc. + * Notes sent on channel 2 map to rows 128 and above. Ohter channels are ignored. + * Rows are stopped when note offs are received, or when you hit stop in your DAW. + * Requires the Arduinboy build of LSDj. + +- **Auto Play**: + * When this option is enabled, RetroPlug will simulate a press of the start button whenever the transport in your DAW is started or stopped. + * Works in combination with the other sync modes. + * This option is pretty dumb (it doesnt know if LSDj is playing or not), so it's possible to make it think it is in the wrong state if you manually press `Start`. If this happens just press `Start` again. + +### Additional options +- **Keyboard Shortcuts**: Enables a set of common shortcuts that allows you to use LSDj with a keyboard in a more intuitive manner. Many of the hotkeys for these settings can be modified in the button config file (see [Button mapping](#button-mapping)), although a few can't: + +| Action | Default key(s) | Configurable| +|--------|----------------|-------------| +|ScreenUp|W|Yes| +|ScreenLeft|A|Yes| +|ScreenDown|S|Yes| +|ScreenRight|D|Yes| +|DownTenRows|PageDown|Yes| +|UpTenRows|PageUp|Yes| +|CancelSelection|Esc|Yes| +|StartSelection|Shift (Hold)|No| +|CopySelection|Ctrl + C|No| +|CutSelection|Ctrl + X|No| +|PasteSelection|Ctrl + V|No| + ## Dependencies - [SameBoy](https://github.com/LIJI32/SameBoy) - The emulator itself - [iPlug2](https://github.com/iPlug2/iPlug2) - Audio plugin framework @@ -76,8 +107,7 @@ Coming soon! ## What to expect in the future - 32bit builds - Mac builds -- Standalone version with support for multiple emulator instances in the same window, for optimum 2x LSDj composing -- Smart keyboard mapping so you can use LSDj with a keyboard in the same way you would use any other keyboard based tracker. +- Support for multiple emulator instances in the same window, for optimum 2x LSDj composing - LSDj keyboard mode, if anyone has a use for it (convince me!) ## Troubleshooting @@ -89,7 +119,8 @@ Please refrain from asking usage questions in GitHub issues, and use them purely **A**: All hosts are different, and some have restrictions on routing keyboard input in to VST instruments. First, click the center of the window to try and force the host to give focus to the correct control. If that doesn't work, make sure your host is allowing the plugin to receive keyboard input (Renoise has an "Enable keyboard" option, etc). If it still doesn't work, try editing default keyboard mapping in `buttons.json` (written to `C:\Users\USERNAME\AppData\Roaming\RetroPlug` on first run). There are some quirks with certain DAWs... - **Reaper** does not send the ctrl key to VST's, so you'll need to remap that to something different. -- **Ableton** doesn't seem to support sending keystrokes to a VST! So for the time being RetroPlug won't be of much use in Ableton beyond using mGB. I will further investigate this. + +If you find you have issues with a particular DAW, please feel free to submit a bug report. **Q**: OMG! LSDj does not start when I hit play in my DAW :o