search

marchingband / wvr

Home of WVR, an open source, Arduino compatible, ESP32-based Sample Player and Audio Framework.
GNU General Public License v3.0
65 stars 9 forks source link

readme

License: GPL v3

welcome to wvr

wvr pinout diagram

Purchase a WVR:
      https://www.sparkfun.com/products/21307
      https://www.tindie.com/products/ultrapalace/wvr

Join us on the WVR Forum :
      https://discord.gg/ZfXuBkzec8 (Discord)
      https://groups.google.com/g/wvr-audio (Google Groups, now retired)

Find the Pinouts and Wiring Diagram, and download the schematics for WVR : https://github.com/marchingband/wvr_hardware
Binaries for all the WVR boards are here : https://github.com/marchingband/wvr_binaries
Code for the Web UI is here : https://github.com/marchingband/wvr_ui
Code for the WVR USB Backpack is here : https://github.com/marchingband/wvr_usb_backpack
If you have Thames : WVR in a Pedal, go here : https://github.com/marchingband/wvr_thames

note that starting with firmware version 3.9.0, the IP address of WVR has changed to 192.168.4.1

getting started

wvr gui

powering wvr

updating firmware

Congratulations! You now have the most up-to-date firmware loaded onto your WVR

wvr gui

playing sounds

wvr gui

midi control

WVR will respond to the following midi events:
Note on
Note off
Program Change
Pitch Bend CC 7 (volume)
CC 10 (panning)
CC 11 (expression)
CC 64 (sustain, like the pedal on a piano)
CC 72 (release time (up to ~30ms fade out))
CC 73 (attack time (up to ~30ms fade out))
CC 120 (all sound off)
CC 121 (reset all controllers)
Note that volume, panning and expression, like velocity, will respond acording to a particular sounds response curve. A sound with Inverse Square Root response curve selected will pan with that same algorythm applied.

You can also send some 1-byte SYSEX commands for global controls, currently:
0x01 = WiFi on
0x02 = WiFi off.

So a sysex file to turn off wifi would look like "F0 02 F7". (F0 and F7 are the SYSEX start and end bytes)

web midi

The WVR Web UI can act as a MIDI destination for your DAW or other MIDI applications, and in turn send MIDI data over Wifi to WVR. Using this technique you can play your WVR wirelessly.
On macos, open Audio MIDI Setup, open the MIDI Studio panel, double click the IAC Driver to open its preferences, and check the Device is online box.
In your DAW's preferences, make the IAC Driver a midi output. Select the IAC Driver as the MIDI destination for your midi track.
Google Chrome currently considers Web MIDI to be a "powerful feature" and so access is limited to HTTPS websites. Since ESP32 cannot serve over HTTPS, we need to ask Google Chrome to make an exception and trust the WVR.
In Google Chrome, enter chrome://flags/#unsafely-treat-insecure-origin-as-secure into the url bar, add http://192.168.5.18 to the list, click enable, and then restart Google Chrome.

note that starting with firmware version 3.9.0, the IP address of WVR has changed to 192.168.4.1

Now in the WVR Web UI, in the Global Screen (click the WVR button top and center), click the Refresh button at the bottom of the screen, under Web MIDI, and make sure the IAC Driver is listed to the right.
Your DAW should now stream MIDI data wirelessly to WVR.

wvr gui

understanding priority

WVR can playback up to 18 stereo sounds at once. It mixes all the sounds into a stereo output. If you play very fast, or play dense chords, or have very long sounds, it's possible to ask the WVR to play back more then 18 sounds. When this happens, WVR runs an algorithm to figure out what to do. It will try to find an old, or an unimportant sound, stop playing that sound, and play the newly triggered sound instead. You can help it make this decision by giving some sounds higher priority. A lower priority sound will never stop a higher priority sound, only equal or lower priority. In the case where all 18 voices are busy playing high priority sounds, and a lower priority sound is triggered, WVR will not play the sound.

understanding exclusive group

Exclusive Group allows you to tell WVR that only one member out of a group of notes can be playing at one time. If you want your open hihat sample to stop when a closed hihat sample starts, or if you want one bass note to stop when another starts, you can achieve this by setting the exclusive group value of all the notes in that group to the same number ie. add them all to the same exclusive group. These groups work across voices and channels. When a note-on is received on a memeber of an exclusive group, any other note in that group that is playing will be immidiately stopped. You can also use this functionality to stop notes in the exclusive group without triggering a new sound, just use a note with no sound in the slot. In the case of pause/resume (and related) modes, this will allow you to restart a sample from the beginning. As with all the note settings, you can select multiple notes using shift-click or command-click, and change the exclusive group for all selected notes.

understanding playback mode

understanding response curve

Every MIDI note has a velocity (or volume) attached to it. This is a value from 0 to 127. Imagine a graph with these 127 velocities on the y axis, and the playback volume that each actually triggers on the x axis. If this is a straight line, we have a linear response curve. Many people find other curves to be more human, or more musical. The default response curve for WVR is the Square Root algorithm, but you can also choose linear or logarithmic.

understanding retrigger mode

If a sound is triggered a second time, at a time when it is already in playback, this is a "retrigger". WVR can respond to this event in a number of ways. It can respond by stopping the sound (note-off), restarting the sound from the beginning (restart), ignoring the second trigger (ignore) or by starting a new playback of the same sound without stopping the first (retrigger). In the case of note-off, WVR will respect this event even if note-off is set to ignore, which creates a way to use note-on events to toggle playback. The first note-on will start a sample, the next will stop it (or in the case of pasue/resume mode, they will pause and resume the note).

understanding note off

When a key is lifted on a piano, and likewise, when a pin on the WVR moves from a LOW back to a HIGH state, a "note-off" event is triggered. You can opt to ignore these events by choosing the "ignore" setting, or you can choose to observe them by selecting the "halt" setting, in which case the sound will fade out very fast, and stop, when the note-off event for that sound occurs. In the case of ASR-LOOP mode, you have the additional release option. Selecting release means that the sample will play-out to the end, whereas the halt option will cause the sample to immidiately stop.

using racks

The term "rack" is our word for multi-sample functionality. With a traditional midi instrument, the sound engine responds to velocity data by modulating the volume of the sounds it produces. In a multi-sampled instrument, instead, the engine responds to velocity by playing a different sample, presumably a sample that reflects a lighter or heavier touch. In the case of a drum sample, the engine should have samples of the same drum being struck with various amounts of force, for example. To create a rack for a given note, click create rack in the UI. Next it's a good idea to name this rack, so hit name rack and enter a name. You should have all your samples prepared in advance, so next, hit number of layers and let WVR know how many samples you have for this rack. Be careful because changing this number in the future clears the data. The UI will automatically set "break points" evenly for each sample, but you can click any layer, and modify the break point if you like. The formula "< 50" you see in the UI indicates that this is the sample that will be triggered if the velocity is below 50, but above the break point for the previous layer. In other words this number sets the upper bound for this layer. You can still use FX while in Rack mode, but the same FX will be applied to all the layers.

bulk uploading files

You can use shift-click and command-click to select regions of notes (and regions of racks), or ctrl+a to select all notes. If you click select files while a range is selected, then the file dialog that comes up will allow you to select multiple files. The files you select will be sorted alphanumerically, and placed in order into the notes you have selected.

bulk uploading racks

If you shift-click on select files while a region of notes are selected, a special file upload dialog will appear, which allows you to select a directory. This function allows you to bulk upload some racks. The structure of the folder that you select must be organized in a very specific way. It must be a folder of sub-folders. Each subfolder represents a rack, and contains all the files for that rack. It will use the name of the subfolder for the name of the rack, and it will create as many slots as there are files. It will then sort all the folders, and all the files in all the folders alphanumerically, and place them into racks in the notes that you have selected. If any of these directories contain only one file, then a rack will not be created, it will load as a normal single sample, and if the directory contains only a single file called empty.txt, then this note will remain empty.

save and load voice configuration

If you shift-click on a voice button (numbered 1-16 at the top on the home screen) a dialog will open that will let you download a .json file, this file represents all the config settings for that voice. You can rename it as you like with the .json suffix, and save it to your computer. If you shift-alt-click on the voice button, a dialog will open, where you can select a previously saved .json file to now load up all those config settings into that voice.

pitch interpolation

If you select a range of notes, and then shift-alt-click a note, the note will turn red, and it becomes the pitch interpolation target. Click select file and select one file from the dialog. The selected file will be pitch interpolated across the range you have selected. The pitch interpolation target will maintain its pitch, and all the other notes you selected will be pitched up or down in relation to it. You can look at the FX tab to see how the algorithm has decided to pitch your notes.

pitch interpolating a rack

If you follow the steps above for pitch interpolation, but instead of selecting a single file, you instead select multiple files in the dialog, then the selected files will be sorted alphanumerically, and made into a rack, that rack will then be copied to all selected notes, and pitch shifted just like in pitch interpolation.

pitch interpolating an ASR loop

When using pitch interpolation with an ASR Loop sample, the Start and End values also need to be interpolated, because the file size, and all the samples in the sound, will scale according to the pitch, so the sample position of the loop points will also need to be scaled. If you use shift-click and shift-alt-click to select a range and an interpolation target, you are able to intepolate the loopStart and loopEnd configuration values. Enter the Start and End values for the target sample, and the other notes in the selected range will automatically receive interpolated values based on their relationship to the interpolation target.

using fx

WVR uses the web browsers built-in audio engine to do a lot of work preparing samples before it sends audio data to the WVR. It converts any sample that you choose to a standard audio format of 44.1k 16bit stereo PCM. It also adds FX. Currently the WVR UI implements Distortion, Reverb, Pitch Shift, Panning, Reverse and Volume. These FX are rendered before being sent to WVR, so the processor on WVR doesn't need to do any extra signal processing. This does mean that the reverb and it's tail are hard coded into the sample. If you have a sample with reverb, you must set up the note to ignore note-off events, otherwise there will not be a reverb tail if the note off event occurs before the sound is finished playing. You cannot return to the UI later and modify the FX settings, after you have SYNC'd the data to WVR. To change the FX you would need to select the original sound file again from your computer, apply the FX in a new way, and hit SYNC again. Click audition to hear how the FX sound. Depending on your computer and web browser, this rendering process is sometimes buggy, it may freeze for a moment (or a few seconds) before playback begins.

global settings

In the UI, click the blue WVR button top and center of the screen. This is the Global Settings menu.

firmware manager

WVR can store up to 10 different firmwares, and the UI allows you to boot from any of them. Click select binary for the slot you want to use, and find the compiled binary on your computer. Click on the filename (at the left) and rename your firmware so you know what it is. Click upload and wait for it to complete. After refreshing the browser, click boot and wait for the firmware to boot. It's a good idea to reset the WVR after this process, then refresh the browser. You are now in your new firmware! Note that some firmwares are not compatible. If the partition scheme on the eMMC is different between firmwares, the WVR will notice, and will have to reformat the eMMC, this means you will loose all stored configuration and sounds, and all your firmwares, etc. Releases of WVR firmware are versioned to make this clear. 1.0.1 -> 1.0.2 or 1.1.1 is safe, but 1.0.1 -> 2.0.1 would not be safe. We will aim to only VERY RARELY make a major version bump, but there may be times when it is necessary. Other developers who may release their own WVR firmwares in the future SHOULD CERTAINLY follow this tradition, and indicate which version of WVR firmware they are targeting :) <3

setting up for Arduino IDE programming

!!!WARNING!!!
Do not upload your own custom code to WVR without a working USB-FTDI module setup (see below). If your binary has a bug, it will prevent WiFi from launching, and you will be unable to upload a working binary. Your WVR will be bricked until you obtain a USB-FTDI module.

Once you have your FTDI working, here are the steps to setup Arduino for WVR programming!

Congratulations! You have flashed a custom firmware to your WVR!

using Arduino CLI

using platformIO

setup your platformio.ini file like this:

[env:esp-wrover-kit]
platform = espressif32@6.2.0
framework = arduino
board = esp-wrover-kit
lib_deps =
    https://github.com/marchingband/wvr.git
    # https://github.com/me-no-dev/ESPAsyncWebServer.git
    # https://github.com/me-no-dev/AsyncTCP.git
build_flags = -DBOARD_HAS_PSRAM -mfix-esp32-psram-cache-issue
monitor_speed = 115200
# upload_port = /dev/cu.usbserial-A50285BI

Create a main.cpp and copy one of the example files into it. Remember to add #include <Arduino.h> at the top of main.cpp.

using FTDI

You will need something like this: https://www.adafruit.com/product/3309
To connect a usb->fdti module to your WVR, connect D0 to RX, D1 to TX, and GND to GND. Open the sketch examples/wvr_ftdi, where you will see wvr->useFTDI = true. The ESP32 on the WVR needs to be booted into a special FTDI boot mode, to do this, ground D6 and ground the small copper pad on the top of the WVR labeled "boot" (it's right next to the eMMC), and hit reset. You can release D6 and the boot pad now. The ESP32 is now in FTDI boot mode, and if you have a serial monitor attached the WVR, it should print waiting for download. Now you can use the UPLOAD button in the Arduin IDE, at the end of flashing it will print "hard resetting", now restart the WVR. If you open the Arduino Serial Console, you will see some logs form the WVR boot process. With FTDI, you can also use ./wvr.sh ftdi to flash, and Arduino Serial Monitor (or any Serial monitor app you like) to get logs from WVR

hardware considerations