Geek Funk Labs SquishBox User manual

SquishBox User Guide
27. Mar. 2021
Contents
Overview....................................................................................................................................................1
Hardware....................................................................................................................................................2
Usage..........................................................................................................................................................3
Navigating Patches/Menus....................................................................................................................3
Main (Right Button) Menu....................................................................................................................
System (Left Button) Menu...................................................................................................................
Wireless Connection..................................................................................................................................5
Editing Files...............................................................................................................................................6
Bank Files..............................................................................................................................................6
Config File.............................................................................................................................................9
Updating Software.....................................................................................................................................9
Technical Notes........................................................................................................................................10
Troubleshooting.......................................................................................................................................10
Credits......................................................................................................................................................10
License.....................................................................................................................................................10
Overview
The SquishBox is a synthesizer running on a Raspberry Pi built into a stompbox. It will take MIDI
input from controllers plugged into its USB ports and output instrument sounds on its 1/ ” outputs. The
sounds come from soundfonts, a widely-available sample-based sound file format that can contain
multiple instruments (referred to as presets).
The buttons on the SquishBox allow you to switch between patches, which activate one or more
instruments and can also specify how the keys, buttons, knobs, and pads on your controller should be
routed to the instruments, turn on effects, send CC and SYSEX messages, and more. Patches are stored
in bank files, and the number of patches and banks you can have is more or less unlimited. A selection
of soundfonts and bank files are included, and you can write your own bank files and add soundfonts to
suit your specific performance needs.
SquishBox User Manual page 1

Hardware
Diagram
1. 16x2 character LCD
2. Stomp switches
3. DC jack
. USB ports
5. SD card slot
6. Left/Stereo headphone output
7. Right/Mono output
Adjusting Contrast
If you need to change the contrast of
the LCD, the potentiometer is
behind the USB ports as shown, and
can be reached for adjustment with a
long, thin cross-head screwdriver.
USB Connections
You can plug up to four MIDI controllers into the SquishBox’s USB ports. Controllers should be auto-
detected when plugged in, even after the unit is running. If not, they can be connected using the “MIDI
Devices” option in the System menu, described below. A powered USB hub can be used to connect
even more devices. MIDI controllers that only have 5-pin DIN connectors require a MIDI-USB
converter cable or interface.
SquishBox User Manual page 2

Audio Connections
The audio outputs can function several ways, depending on which ones have cables plugged in. If
cables are plugged into both outputs they will provide separate left and right stereo signals. If only the
right output is plugged in, it will provide a mono (combined right and left) signal. If only the left jack is
used and a TRS cable is plugged in, it will output left and right signals on the tip and ring contacts,
respectively, allowing headphones to be used.
SD Card
The SD card can be removed from its slot removed using tweezers or needlenose pliers (power down
the SquishBox first). A complete image of the latest SquishBox software, including the default
soundfonts and banks, can be obtained at geekfunklabs.com/products/squishbox. You can write this
image to the SD card using Win32DiskImager on Windows, or the dd command on MacOS or Linux,
but this will erase any other data you have on the SD card. You cannot copy soundfonts or bank files
directly onto the SD card and use them on the SquishBox – only the /boot partition is visible to other
operating systems.
Usage
Navigating Patches Menus
•Tap the buttons to switch between patches. Long-press (hold >2sec) the right button for the
main menu, long-press the right for system-related tasks.
•In menus, tap the buttons to switch options. Long-pressing right will select an option, long-
pressing left will go back/cancel.
•Some menus allow you to change a numerical setting. Tapping buttons increases/decreases the
value, holding buttons changes the value quickly. If you don’t press any buttons >5sec you’ll be
asked whether to set the current value – long-press right to confirm, left to cancel.
•Some menus allow you to enter text. Tap the buttons to change the current character. Long-hold
the buttons to move the cursor right or left. If you move the cursor to the end of the text, it will
change to an accept ( ) symbol, at which point you can long-press right to accept your text.
Tapping left will select the delete ( ) character, which allows you to delete characters by long-
pressing left. Pressing no buttons for >5sec cancels your entry.
•Refresh Bank: Holding the right button for >5sec will re-load the current bank file.
•Panic Restart: Holding the left button for >5sec will stop all sound and restart the software.
SquishBox User Manual page 3

Main (Right Button) Menu
•Save Patch – Saves the current settings to the patch. Modify the name to create a new patch.
•Delete Patch – Erase the current patch from the bank (unless it’s the only one)
•Load Bank – Load a different bank
•Save Bank – Save the current bank. Changing the name saves as a new bank.
•Load Soundfont – Open a single soundfont and switch between/play its presets. Choosing “Save
Patch” while in this state will create a new patch in your bank that uses the current preset,
allowing you to manually add sounds to your banks. To go back to your bank, choose “Load
Bank”.
•Effects – Allows you to modify the settings of the chorus and reverb effects units, and the gain
(volume) of the SquishBox. Changes affect all patches in the bank – save the bank to make
them permanent.
System (Left Button) Menu
•Power Down – To protect the memory card of the SquishBox, this option should be used before
unplugging. Allow 30 seconds for complete shutdown.
•MIDI Devices – This allows you to see the names of the MIDI devices currently plugged in to
the SquishBox, and attempt to reconnect any that are not responding.
•WIFI Settings – Displays the current IP Address of the SquishBox. Tapping either button selects
options to scan for and connect to WIFI networks. You can also enable/disable the Remote
Link, which allows you to remotely control the SquishBox and edit its patches from another
computer using the FluidPatcher software.
•Add From USB – If you have a USB flash drive connected, the SquishBox will search for any
soundfont files stored on it and copy them to its memory card. If you have soundfonts in
different folders on the flash drive the folder hierarchy will be copied as well.
SquishBox User Manual page

Wireless Connection
The SquishBox has onboard wifi you can use to connect to it with a computer to configure it. Using the
methods described below you can edit your bank files, upload more soundfonts, and even modify your
patches while playing. To connect to a wireless network, use the “WIFI Settings” in the System menu,
described above. Alternatively, you can remove the SD card and create a file on it called
wpa_supplicant.conf containing the text below. When you reinsert the SD card and power up
the SquishBox it will connect to your network. Note that this will overwrite any other wireless
networks you’ve added to the SquishBox, unless you include network items for them below.
country=US # change to your country code
ctrl_interface=DIR=/var/run/wpa_supplicant ROUP=netdev
update_config=1
network={
ssid="your-network-name"
psk="your-password"
}
File Manager
When connected to a wifi network, the Squishbox provides a browser-based file manager that can be
used to view, edit, and upload files. Obtain the IP address of the SquishBox using the “Wifi Settings”
menu option, open a web browser on your computer and enter the IP address in the address bar. The file
manager login is squishbox and the password is geekfunklabs. You can use the file manager to
upload new soundfonts or banks, or edit your bank and config files.
A useful trick is to create an ad-hoc or “hotspot” network on your phone or mobile device and add it to
the SquishBox. The SquishBox will then connect to your device wherever you are, so you can access
the file manager to make changes to it if necessary.
Remote Link
The FluidPatcher software that runs on the SquishBox also has a cross-platform GUI version that can
be used to play and edit patches on your computer, and can connect to the SquishBox over wifi so you
can create, edit, and test banks directly.
Download FluidPatcher from GitHub or SourceForge, and install it by following the directions in the
README. Open the “WIFI settings” menu on the SquishBox, note down the IP address, and make
sure “Allow Remote Link” has been selected.
Start FluidPatcher on your computer. The program has a text editor interface, allowing you to create
and edit bank files, and also allows you to play the patches in the edited bank using any connected
MIDI controller. The toolbar buttons and drop-down menu select the current patch, and the “Refresh”
SquishBox User Manual page 5

button re-parses any changes you’ve made in the editor window, refreshing the patch list. The “Choose
Preset” option in the “Tools” menu allows you to open a soundfont and browse its presets.
To connect to the SquishBox, choose “Remote Link” from the “Tools” menu, and enter its IP address.
Now you can load and save banks directly on the SquishBox, and changes you make to the bank file
can be sent to the SquishBox and tested by pressing the Refresh button.
Secure Shell
The Raspberry Pi computer inside the SquishBox runs the Raspberry Pi OS. You can access its
command line directly using a secure shell program (e.g. ssh or PuTTY), or secure file transfer (e.g.
FileZilla). Log in as the user pi with password raspberrypi. From the command line you have the
ability to make any changes you want to the system. It may be wise to change the default password
using the passwd command.
Editing Files
Bank Files
Patches are stored in banks, which are described in plain-text bank files. A patch consists of a batch of
settings that are sent to Fluidsynth when the patch is selected. This includes soundfont, bank, and
program settings for any number of MIDI channels, and can also include MIDI routing rules, effects
settings, control change (CC) messages, MIDI Sysex messages or files, etc.
Bank files are formatted in YAML. Very briefly, YAML stores data, either as lists or as mappings (sets
of <key>: <value> pairs). Lists and mappings can be nested within each other, and nesting level is
indicated by indenting. List elements are placed on separate lines and preceded by a dash, or can be
written in compact form as a comma-separated list enclosed in square brackets. Mappings can have
their key: value pairs on separate lines, or in a comma-separated list enclosed in curly braces.
Structure
Example bank file (explanation below):
patches:
FM Piano:
1: FM Piano.sf2:000:000
Synth Bass and Piano:
3: VintageDreamsWaves-v2.sf2:000:028
4: Fluid M_R3.sf2:000:000
router_rules:
- {type: note, chan: 1-1=3-3, par1: C0-Bb4*1-12}
- {type: note, chan: 1-1=4-4, par1: B4- 9*1+0}
cc: [3/91=127, 3/93=127]
Analog Synth:
SquishBox User Manual page 6

1: ModSynth.sf2:000:000
router_rules:
- clear
- {type: note, par1: 0-127*1+0, par2: 0-127*0+127}
- {type: cc}
- {type: pbend}
effects:
- lib: /usr/lib/ladspa/delay.so
audioports: mono
controls:
- {port: Delay, val: 0.3, link: 1/15, xfrm: 0-127=0-2.5}
router_rules:
- {type: note, chan: 1-16*1+0, par1: 0-127*1+0, par2: 0-127*1+0}
- {type: cc}
- {type: cc, chan: 1-1=2-16, par1: 7-7*1+0}
- {type: pbend}
- {type: kpress}
- {type: cpress}
cc: [3/91=80, 3/93=80]
fluidsettings:
synth.reverb.level: 0.9
synth.gain: 0.6
cclinks:
- {target: synth.reverb.room-size, link: 1/18, xfrm: 0-127=0-1}
init:
cc: [3/7=80, 1/73=0, 1/74=0]
Individual patches are denoted by the names in the patches item. Patches can contain instrument
settings for any number of MIDI channels, given as
<channel #>: <soundfont file>:<bank>:<preset>
MIDI channel numbers in bank files are numbered starting with channel 1, the way they are on
virtually all synthesizers, controllers, DAWs, etc. This is in contrast to FluidSynth, which numbers
channels beginning with 0. Patcher handles all of the translation between channel numbering schemes.
The keywords below are used to define various settings or messages to send, and can be used at bank-
level (i.e. no indentation), within individual patches, or in an optional init item. When a patch is
selected, bank-level keywords are applied first, then patch-level. Keywords in the init item are
applied once, when the bank is first loaded.
•router_rules - a list of rules for how FluidSynth should route MIDI messages. Each rule is
a mapping that must have a type key defining the type of MIDI message to route, and can also
include the keys chan, par1, and par2, which describe how to route/transform the messages.
These last three contain router specifications of the form <min>-<max>*<mul>+<add> or
SquishBox User Manual page 7

<from_min>-<from_max>=<to_min>-<to_max>. Scientific note names such as C#4
or Eb7 can be used instead of note numbers when desired. A routing key that isn't specified is
assumed to be the default for that message e.g. 0-127*1+0. A rule can also be clear - which
clears all previous MIDI router rules, or default - which resets default routing rules for all
MIDI message types.
•type(required) - can be note, cc, prog, pbend, kpress, or cpress.
•chan - which channels the rule applies to, and what channels to forward the messages
to. If specified as <min>-<max>*<mul>+<add>, messages from channels in the
min-max range have their channel number multiplied by mul and added to add (- instead
of + subtracts). If the from-to form is used, all channels in the from range are routed to
those in the to range.
•par1 - routes the parameter number for that message type e.g. the note number or
continuous controller number. If the from-to form is used, numbers in the from range are
scaled proportionally to those in the to range. The exception is CC messages, for which
all CC messages in the from range are routed to those in the to range.
•par2 - controls how the parameter values are modified e.g. the note velocity or
continuous controller value.
•fluidsettings - a mapping of FluidSynth settings to values.
•cc - a list of control change messages to send when the patch is selected, specified as <MIDI
channel>/<CC number>=<value>
•sysex - a list of SYSEX messages to send. Each message is itself a list where the first element
is the port name of the MIDI controller to send the message to, and the remaining elements are
either a list of SYSEX bytes to send (as decimal or hex), or the name of a SYSEX file to dump
to the specified port.
•cclinks - a list of mappings, each of which describes a way to control some parameter using
a CC message
•target - the parameter to modify, e.g. the FluidSynth setting
•link - the CC message used to change the parameter, specified as <channel>/<CC
number>
•type - the type of parameter being linked. Currently fluidsetting is the default
(and only value allowed) in bank files.
•xfrm - a router specification for translating from the CC value to the parameter value.
•effects - a list of LADSPA effects to activate, along with settings. Still a beta feature -
effects must be installed separately.
•lib(required) - the path to the effect plugin file (.dll, .so, etc. depending on system)
SquishBox User Manual page 8

•plugin - the name of the plugin within the file, required if there's more than one
•audioports - stereo, mono, or a list of the audio input and output ports in the plugin.
tereo assumes ['Input L', 'Input R', 'Output L', 'Output R'],
and mono assumes ['Input', 'Output']. If the plugin author names their ports
differently you can give them explicitly. Default is stereo.
•controls - a list of mappings describing initial settings for effect parameters and/or
CC messages with which to control them dynamically
•port(required) - the name of the effect parameter
•val - the initial value to set
•link - a CC message that can be used to change the parameter, specified as
<channel>/<CC number>
•xfrm - a router specification for translating from the CC values to what the
effect parameter expects
Config File
The main configuration file for the SquishBox is /home/pi/squishboxconf.yaml. This file is also in
YAML format. It sets the root location of banks, soundfonts, and effects plugins, the current bank file,
and FluidSynth settings. The config file has the structure shown below.
soundfontdir: <root path where soundfonts are stored {sf2}>
bankdir: <root path where bank files are stored {banks}>
plugindir: <location of LADSPA effects {/usr/lib/ladspa}>
currentbank: <last bank loaded {''}>
fluidsettings:
audio.driver: alsa
audio.period-size: 64
audio.periods: 3
<name1>: <value1>
<name2>: <value2>
...
All items are optional – default values are shown in curly braces. The values in fluidsettings are
set when the SquishBox starts, so this is the place to specify audio and midi driver settings. Synth
settings can be specified here or in individual bank files. The audio.* settings shown above provide
the lowest audio latency for the SquishBox without producing audio glitches, but can be modified if
you desire.
Updating Software
Visit geekfunklabs.com/products/squishbox for information on updating your SquishBox when new
versions of the software are released.
SquishBox User Manual page 9

Technical Notes
•Because the SquishBox can connect to networks, it may be vulnerable to attack. Effort has been
made to make it secure, but you can make it more secure with the following actions:
◦Change the default login password for the pi user with the passwd command.
◦Change the login and password for the browser-based file manager. To do this, edit the file
/var/www/html/index.php and edit the auth_users array. You can disable the
file manager entirely by renaming index.php to something like index.php.block.
◦You can set your own unique password and port for the remote link feature. To do this, add
a remote_passkey item with a six-character password and/or remote_port with a
network port number to the SquishBox config file. Add these same items in FluidPatcher’s
settings on your computer to connect.
Troubleshooting
If any problems arise with your Squishbox unit, visit geekfunklabs.com for assistance.
Credits
SoundFont® is a registered trademark of E-mu Systems, Inc.
License
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike .0
International License, 2021 by Bill Peterson.
SquishBox User Manual page 10