Doc Home About Build Config More

characteristics

Starting point: an instrument is characterized by

Synthesizing using midi controller

:
A synthesizer generates it's sound via tone generators, mimicking instruments by via their characteristic envelopes.
ADSR midi

The lines are usually not straight, the AD-form actually characterizes the instrument. Also the S-form differs per instrument, on a piano it will decrease but an organ will have a horizontal line.

Sampler

Instead of generating the characteristic sound, a sampler uses pre-recorded samples to do (part of) the job described above.
Samplerbox reads these samples from WAV-files and plays them depending on note-on/note-off and force=velocity the key was hit. Playtime depends on the mode: in keyboard mode a note-off is processed when releasing the key (which can be delayed using the sustain pedal), in all other modes the WAV-file will be played till an explicit (non-MIDIstandard) note-off is sent.
For a straight forward WAV-file this means that if (in keyboard mode) you hold the key shorter than WAV-length, the built-in release/fadeout will start before the recorded release. Subsequently, if you hold the key longer than WAV-length, the built-in release/fadeout won't have any effect as the WAV-file is exhausted.
ADSR plain wave file

This gives good results for an instruments that fade out by nature like the grand piano or acoustic guitar, but won't work for a flute or organ.
By using loop markers (the red lines), you can you can fix that like this:

ADSR wave with loop markers

The WAV file processing actually ends at second loopmarker, the rest can be generated by samplerbox. Now the sustain can be as long as needed and release/fadeout is by default controlled by built-in release/fadeout, which can be configured on box level, per sample set and individual sample(s). When using this method, the files can be truncated after the last loop marker.
If the attack/decay is not applicable for this instrument/sound, loop markers can be at file start/end, making things very easy. The samplerbox default saw sample illustrates this.

Velocity level differentation in samples

Sampled release

The builtin release is not always sufficient. With a harpsichord you need the sound of the damper, with a church organ you need reverb/noise of the church etcera.
This can be achieved by sampling/recording the typical release sounds too. At playtime the sample will be played as described in previous paragraph, but when the note off is received the release recording will be mixed/played instead of the built-in synthesized release: Samplerbox supports two techniques for sampled release (%relsample): In order to do all this without clicks or other noise we have parameters to tune the behaviour: Church/pipe organ embedded release sample. The "M0" denotes the marker:
pipe/churchorgan
Harpsichord embedded release sample: a superficial loop is just before the damper sound, so we have the natural delay as long as possible.


Random samples per note

All the above is meant to get a "close to real" sound, for human touch or plain fun. However it does not take in account that for some instruments the way it's played can slightly differ during play as humans are no robots.
Think of the position where a drumhead is hit, the exact position of the fingers on a fretless instrument, the snare position where dulcimer family instruments are hit, etcetera, etcetera. Same drum, same snare, same velocity but still other sound - the human touch.

The %rnds=<number> parameter gives the possibility to assign multiple wav's to every note/velocity pair. The assigned wav's will be selected randomly during play. The numbers are in range 1-9 and don't have to be consecutive or sorted; they just have to be unique for the selected note/velocity.
Do make sure you supply the same velocity layers for every sample(wav), otherwise notefilling may surprise you with undesired effects.
This parameter is ignored on the separate release samples; they are united with the master sample. This means that every %relsample=S line needs a mirrored "%voice" line. If you have less release samples, you need to point to a shared wav for this. Don't worry: it will be loaded only once.

If these wav's are same note+velocity of the same instrument but differ in the "touch", this will introduce a human like element.
But ofcourse it's perfectly possible to make more creative / mind boggling options via assigning different instrument wav's this way.

Mutegroups

one note at a time per group

In samplerbox mutegroups are used to define groups of notes of which only the last played will sound.
Logic: if a note in in a mutegroup is playing and the next in that group is activated, the existing one will get a note-off.
This introduces a configurable "MIDI Mono Mode": if all notes in a voice are in the same mutegroup, you have the basic MIDI mode=mono.

This is for instance useful for the once and loop modes as you can make ongoing sounds that will be switched when playing a new one (or stopped if playing the same one).
Another usage could a be simplified drummer's Hi-hat.

The "note" is the note/key played by the musician. So if autochord is on, all notes in the chord wil be played. When the musician plays a new note, all the old chordnotes are stopped and we'll get the new chordnotes.

It's defined via the %mutegroup=<number> parameter.

Sustain and damper pedals (or knobs)

Sustain simulates keys being pressed (=suspended note-off) untill the pedal releases them all. In default operation, playing an already sustaining note will cause an artificial note-off while doing the new note-on to minimize noise / unwanted volume increase.
This is undesired when simulating the natural resonance of some acoustic instruments (it makes the grandpiano sound "thin"). Preserving resonance can be achieved by setting the %retrigger parameter to "Y".
Sustain shows another typical difference between instruments fading out by nature and those capable of holding tones as explained above: instruments having a loop are incompatible with "%retrigger=Y", hence the default...
The sustain pedal has no function when playing in mode=once; you can consider this mode as mode=keyb with a "locked" sustain pedal.

Damper does the opposite: it quickly damps the sounding note, even when the key is still pressed. New notes sound muffed / pizzicato like. You may have to experiment with the %damp parameter.
Three types of damping (pedals) are available via the CCmap:

Damper noise

This relates to previous two paragraphs.
When using damp you may want hear extra sounds (like the damper sound at noteoff for a harpsichord).
Think of pianists reaching in their piano to damp snares or above santoor player hand-damping the last played snares (the santoor is a mode=once type of instrument), both causing extra noises / rattling effects.
It can be set with %dampnoise=Y.

Fills and loops (phrase sampler)

In the "Once" modes, the samples will be played once till end of file. With "Onc2" you can force it to stop (with release=fadeout processing) by pressing the same note again. These modes are meant for special effects, background vocals, short rifs or fills etcetera.
"Loop" modes recognize loop markers. You can use this for a repeating riff, bass-loop, etcetera. Without loop markers, the sample will be played once obviously; you can use this when a mix of loop and once phrases is needed.
Note: as a loop needs a way of stopping, it will either operate in normal "stop on same key" mode or special "stop on 127-note".
A complex example to illustrate what is possible:

This shows an intro/fill followed by a backline loop. We use it in fact by starting it and subsequently stopping or restarting just before the loop starts to get some sort of countdown effect. When letting it go to the loop part "the music starts". This can be repeated several times. With this we emulate two extra musicians who will play their part on request (keypress or pad-hit).
By the way: using such an intro mechanism enables to sync with the loop without a click track.
Stopping the loop or phrase
In Loop and Onc2 modes the playing stops by hitting the key a second time. Mind that this second hit is always necessary: if a Onc2 phrase stopped by reaching it's end, it still needs the second press before it will play again. So this is really "press twice"
For loops, a special way of stopping is by hitting the midinote calculated by 127-note. Table at the right shows exact values, also highlighting standard keyboard areas (these do not exactly match the playable areas that can be defined with %%stopnotes).
"Loop" works only for notes in the "start-stop areas": the note=sample played to left of the keyboard area is stopped with it's mirrored values to the right of this area. See picture below for illustration of the usable areas using an 88-keyboard.
You can set the areas by defining the first stopnote (start of the stop=right range). Default is 109 = the first available note next to the 88 range. With this you can stop samples 0-18, leaving 2 slack. Within the "keyboard area" (between the start-stop areas) samples defined as "Loop" will be forced to "Keyb" to avoid infinite loops.

keyboard

Backing tracks

Backing tracks are a special type of loo2 meant for providing musical accompaniment. Main characteristics:

Controlling the volume

Mastering volume is not just turning the volume knob; we are connecting a series of (virtual) inputs and outputs and need to achieve optimal connections.

Midimode: polyphony, channels, devices

SamplerBox merges all input to one MIDI link. In plain words: it can "see" all devices connected to it no matter whether they are connected via (multiple) USB input or the optional DIY wiring on the serial interface on the GPIO pins. Regarding polyphony: the max concurrent sounds are defined in the configuration.txt.
Implementation is not exactly implemented as described in the midi standards: instead of refusing new notes exceeding MAX_POLYPHONY, the eldest triggered tones will be removed (playing backtracks will be preserved regardless their age).
When using autochord / chorus / layers, the extra needed notes needed for that are included in the polyphony count. For autochord this depends on the chord definition (usually it means 2 or 3 extra notes) and for chorus it's 2 extra notes.
On turn these values are multiplied with the layer count. So a 3 note chord played with chorus on a 1 extra layer voice results in 3*3*2=18 sounds to be played with one note-on. Be practical with your creativity..

With Mutegroups you can emulate the midi "poly off" by defining all notes in the same mutegroup.

Samplerbox supports the rarely used real time "reset" message with the more common "all notes off", also known as "panic button".

Keyboards with drumpads

Some keyboards have drumpads coming in different flavours, some having some restrictions: hardcoded on the channel (drumchannel=10), hardcoded on the notes per pad, etc.
Optionally samplerbox can "route" notes from the drumpadchannel to other notes in the master channel.

Note mapping, retuning, keyboard split

This is a technique to make keys playing notes other than the standard ones (transpose/retune per played note and/or switch voices).
This can be done predefined/sampleset via the notemap.csv or the webGUI screen - looking at those saves pages of explanation here.
It drills down to: per note you can define what actual note&retune should be played and which voice to use.
CCmap entry in /boot/samplerbox
C2FixedReverbToggle
or   CCmap entry in sample set
0C2FixedReverbToggle

Notemap entry (sample set only)
mapname0C2Ctrl
So you can use a key or pad as a switch for an effect by mapping it as Ctrl in the notemap and define it in the CCmap for the control you require.

That's a hard to read sentence, so on the right an example: use the leftmost key of a 61 keys midi keyboard to switch reverb on/off in a sample set.
Consult the README_CSV.txt in the configuration directory for more details.

If you want have this activated by default in this sampleset, include %%notemap=mapname in the definition.txt.

Multi-timbral channel map

SetChannelProgram ChangeVoice
0 or
file/device
0 is fallback
0-16
1-16 are input channels,
0 is fallback
0-128
1-128 are instruments,
0 is fallback
> 0
Voice to use

With this technique you can assign default instruments in the channels of the multitimbral input devices (for instance a sequencer) to the desired voice=sounds. This is defined per sampleset via the MTchannelmap.csv shown on the right (via the webGUI screen is on my wishlist).
Set is either:

If a note is received from a channel which has not sent a program change yet, the samplerbox assumes the channel# as active voice (channel5 -> voice5).
Channel# and program# are the "human counts", so channel range 1-16 makes GM-piano=1 and GM-drum=10, but your controller may be zero based (range 0-15 and 0-127), which may be confusing. SMF files are zero based by definition, an attention point when debugging.

Specifying value=0 gives the default/fallback for undefined channels/CC's in this set. If this results in a voice for which no wav's exist, samplerbox assumes the lowest voice present.

SMF player

Midi player (simple internal sequencer)

Wikipedia states in the "Composition" paragraph:

"MIDI events can be sequenced with computer software, or in specialized hardware music workstations. Many digital audio workstations (DAWs) are specifically designed to work with MIDI as an integral component. MIDI piano rolls have been developed in many DAWs so that the recorded MIDI messages can be easily modified."
      ....<snip>....
"The data composed via the sequenced MIDI recordings can be saved as a standard MIDI file (SMF), digitally distributed, and reproduced by any computer or electronic instrument that also adheres to the same MIDI, GM, and SMF standards. MIDI data files are much smaller than corresponding recorded audio files.
".

SMF's in the active sampleset can be played by samplerbox (one at a time!):

Note generation

Note generation, common 12-tone and 24-quartertone scale

By default (%fillnote=Y) missing samples will be mimicked/calculated from the nearest note. If this exceeds programming boundaries, the ultimate note will be used ("it sticks at the border...").
Theoretically this implies that one middle C sample can facilitate large keyboards, however in real life this will not sound nice.
The number of samples/octave depends on the instrument: the saw is OK with 1 sample/octave while a piano needs 4.
Note 1: Generation is actually done by varying the speed, so unusable if the tempo of samples/loops is important.
Note 2: Original samplerbox calculates from the lowest sample upwards. Biggest downside: notes below the lowest sample are dead.
Note 3: I've also increased the granularity of speed to enable pitchbend, 24-tone-scale, retuning and 48kHz support.

Default described above is done for the common 12-tone standard (7 tones plus 5 semitones per octave), see 88-keyboard frequencies and full layout.
By specifying %qnote, the note generation will also produce the in-between quarter tones, resulting in 24 tones per octave.
The standard midimapping of midi notes to music notes does not apply here anymore of course.
Basis of the mapping is middle-C = midi 60 = music C4 (unless changed in the script..), giving these values for 24-tone scale.
Straight filling the notes results in equal temperament, which does not always fit the Eastern music & instruments: they may need retuning.
Options for retuning these notes are

Effects & audio filters

Wiki description of samplers states "Often samplers offer filters, effects units, modulation via low frequency oscillation and other synthesizer-like processes that allow the original sound to be modified in many different ways."
Implementation on a Raspberry sets limitations to this, so it had to be done as performance friendly as possible which resulted in trade-offs in some areas. As the effects are applied at their most efficient stage in the sound generation process, there will be aggregation differences. In plain English: the scope where effects are effective may not always be logical/consistent from musicians point of view.
    The three scopes:
  1. Notes/tones in the keyboard area
  2. All 128 notes/tones except the effects track (voice=0)
  3. All notes/tones/sounds, thus also including backing tracks and multitimbrals.
    (principally effects should only affect the "main" device's sounds, but alas..)

Per effect the scope in which they operate as well as how they influence performance:
(the process stage is mentioned for the curious...)
EffectScopeProcess stageCPU impact
Sustain&damp;Notes in keyboard areaNote-on/off processingLow
PitchbendAll notes except effects track & MT inputTone generationLow
VibratoAll notes except effects track & MT inputTone generationLow
TremoloAll soundsOn mixed soundLow
PanningAll notes except effects track & MT inputTone generationLow
RotateThis is vibrato + tremolo + panningLow
Wah (all types)All soundsOn mixed soundMedium
Delay (Flanger+Echo)All soundsOn mixed soundMedium/low
Moog low-passAll soundsOn mixed soundHigh/medium
ReverbAll soundsOn mixed soundHigh
Overdrive/distortionAll soundsOn mixed soundMedium/low
Peak limiterAll soundsOn mixed soundMedium/low
ArpeggiatorNotes in keyboard areaNote-on/off processingLow
AutochordNotes in keyboard areaNote-on/off processingVaries from low to medium depending on speed of playing
ChorusNotes in keyboard areaNote-on/off processingVaries from low to medium depending on speed of playing
RetuneDepends where appliedTone generationLow
BacktracksEffects trackNote-on/off processingLow

Tweaking the webgui

Tweaking the gui requires some knowledge of HTML and optionally also knowledge of CSS (style sheets). Just looking at the pages may give you enough information for a quick start.
For a better understanding a brief introduction on the setup and way of working follows below - you may decide to skip that and only use the list of building blocks. Keep in mind this is 'living' documentation: the actual status is listed on your distribution via the readme screen.

The webgui uses a very simple http server returning files in the webgui subdirectory tree (pages, stylesheets, scripts, pictures, etc) with an addition to pass internal samplerbox variables to your webbrowser and process any input returned (like a REST API).
In short: /root/SamplerBox/webgui is the webroot of a specialized embedded webserver.
Communication flows down via the generated SamplerBox.API in cooporation with stored script SamplerBox_GUI.js and flows up again via the standard submit of your browser.
Your browser renders these pages as usual and makes them look prettier with stylesheet SamplerBox.css. The distributed pages are created for use with 7" tablets in portrait..

             +---------------------+         +------------------+
             | S a m p l e r B o x |  <===>  | tablet/PC/mobile |
             +---------------------+         +------------------+
                 |            ^
                 V            |
  +------------------+    +----------------+
  |  SamplerBox.API  |    |                |
  +------------------+    |   index.html   |   +----------------+
            |             |      and       |<--| SamplerBox.css |
            V             |     other      |   +----------------+
  +-------------------+   |    webpages    |
  | SamplerBox_GUI.js |-->|                |
  +-------------------+   +----------------+
In order to make the above work, every webpage needs to include in the header:
<LINK REL="stylesheet" TYPE="text/css" HREF="SamplerBox.css">
<script SRC="SamplerBox.API" TYPE="text/javascript"></script>
<script SRC="SamplerBox_GUI.js" TYPE="text/javascript"></script>

as well as activation at the bottom (before the </BODY> tag):
<script>SB_Update();</script>

The "SamplerBox_GUI.js" contains building blocks for generating the html code to show and update variables (via tables, dropdowns, sliders, etc) in the webpages. So you don't have to bother with the technical part of the interface and/or write lengthy html code.

In general building blocks for R/W variables are referred by "input_SB_<var-name>" and for R/O variables/elements by "elem_SB_<var-name>". They are "called" by using ID parameters in html tags (<span;>, <div> etcetera). These tags can often contain text, which is displayed together with slider / dropdown / button, whatever is appropriate for his particular variable.
The R/W elements must appear between <FORM ID="elem_SB_Form" STYLE="line-height:300%;"> and </FORM>> statements.
Almost all R/W elements have an implicit submit, making the samplerbox react instantly to changes.

The above is very brief, please use the distributed pages as examples. The readme.html contains also a more direct way to access the variables.
The exceptions on implicit submit are all in these distributed pages; you can recognise them via the "set" buttons.
Ofcourse it is possible create alternative building blocks. I suggest to use extra scriptfiles for that and leave the SamplerBox_GUI.js alone as it is integral part of future distributions forcing re-applying local changes if any. I will gladly include improved blocks in future versions, just let me know.

The html pages can be changed, deleted or extended at your convenience, likewise for the SamplerBox.css.
If you have suggestions - or even better - make improvements on look and feel, please don't hesitate to let me know!
The building blocks at time of writing these docs:

General / miscellaneous elem_SB_bTracks
elem_SB_DefErr
elem_SB_Form
elem_SB_IPlist
elem_SB_Wireless
elem_SB_LastMidiNote
elem_SB_LastMusicNote
elem_SB_LCDdisplay
elem_SB_Mode
elem_SB_Samplesdir
elem_SB_xvoice
input_SB_Button
input_SB_DefinitionTxt
input_SB_FXpreset
input_SB_IP
input_SB_SSID
input_SB_MidiChannel
input_SB_Pitchrange
input_SB_Preset
input_SB_RenewMedia
input_SB_Voice
Volume input_SB_Gain
input_SB_MidiVolume
input_SB_SoundVolume
Peak limiter:
Avoid distortion caused by
too much input dynamics
input_SB_PLattack
input_SB_PLrelease
input_SB_PLthresh
input_SB_PLtype
Notemapping
(redefine keyboard)
elem_SB_Notemap
input_SB_Notemap
input_SB_nm_inote
input_SB_nm_onote
input_SB_nm_unote
input_SB_nm_Q
input_SB_nm_retune
input_SB_nm_voice
input_SB_nm_clr
input_SB_nm_map
input_SB_nm_sav
Chords and Scales
for AutoChord
elem_SB_Chord
elem_SB_Chords
elem_SB_Scale
elem_SB_Scales
input_SB_Chord
input_SB_Scale
Arpeggiator input_SB_ARPeggiator
input_SB_ARP2end
input_SB_ARPfade
input_SB_ARPloop
input_SB_ARPord
input_SB_ARPstep
input_SB_ARPsustain
Chorus input_SB_CHOdepth
input_SB_CHOgain
input_SB_CHOrus
Modulation effects via LFO
(Low Frequency Oscillator):
- Vibrato
- Tremolo
- Panning
- Rotate (cheap leslie)
input_SB_LFOtype
input_SB_PANspeed
input_SB_PANwidth
input_SB_TREMampl
input_SB_TREMspeed
input_SB_TREMtrill
input_SB_VIBRpitch
input_SB_VIBRspeed
input_SB_VIBRtrill
Delay effects:
- Echo
- Flanger
input_SB_DLYdry
input_SB_DLYfb
input_SB_DLYmax
input_SB_DLYmin
input_SB_DLYsteep
input_SB_DLYsteplen
input_SB_DLYtime
input_SB_DLYtype
input_SB_DLYwet
Low-pass filter using a digital
implementation of Moog ladder,
the classic 4-pole, 24 dB/octave
analog filter introduced in 1965
input_SB_LFcutoff
input_SB_LFdrive
input_SB_LFgain
input_SB_LFlvl
input_SB_LFresonance
input_SB_LFtype
Reverb using freeverb by
Jezar at Dreampoint
input_SB_FVdamp
input_SB_FVlevel
input_SB_FVroomsize
input_SB_FVtype
input_SB_FVwidth
Wah effects:
- AutoWah
- LFO Wah
- wah-wah pedal
input_SB_AWattack
input_SB_AWlvlrange
input_SB_AWmaxfreq
input_SB_AWminfreq
input_SB_AWmixing
input_SB_AWqfactor
input_SB_AWrelease
input_SB_AWspeed
input_SB_AWtype
Overdrive:
Softclip distortion combined
with a low-pass filter
input_SB_ODboost
input_SB_ODdrive
input_SB_ODtone
input_SB_ODtype
input_SB_ODmix

Please look at the GUI and in its html sources to see what these blocks do.
The dictionary at the bottom of UI.py gives specs in very rudimentary way.
I figured that to be more effective than trying to describe it all here.

Distortion

No sound, distorted sound, clicks/plops, latency, notes not stopping, etcetera
This is now in the FAQ

Midi association


Wiki


Release parameter possible
values and resulting time

Release in seconds
00240,408
10,017250,425
20,034260,442
30,051270,459
40,068280,476
50,085290,493
60,102310,527
70,119320,544
80,136340,578
90,153360,612
100,170380,646
110,187410,697
120,204440,748
130,221470,799
140,238510,867
150,255550,935
160,272601,020
170,289671,139
180,306751,275
190,323851,445
200,34981,666
210,3571151,955
220,3741272,159
230,391


Loop end notes and
keyboard ranges

Note OnTurn Off
0C-1127G9
1C#-1126F#9
2D-1125F9
3D#-1124E9
4E-1123D#9
5F-1122D9
6F#-1121C#9
7G-1120C9
8G#-1119B8
9A-1118A#8
10A#-1117A8
11B-1116G#8
12C0115G8
13C#0114F#8
14D0113F8
15D#0112E8
16E0111D#8
17F0110D8
18F#0109C#8
19G0108C888
20G#0107B7
21A088106A#7
22A#0105A7
23B0104G#7
24C1103G776
25C#1102F#7
26D1101F7
27D#1100E7
28E17699D#7
29F198D7
30F#197C#7
31G196C761
32G#195B6
33A194A#6
34A#193A6
35B192G#6
36C26191G6
37C#290F#6
38D289F6
39D#288E6
40E287D#6
41F286D6
42F#285C#6
43G284C6
44G#283B5
45A282A#5
46A#281A5
47B280G#5
48C32579G5
49C#378F#5
50D377F5
51D#376E5
52E375D#5
53F374D5
54F#373C#5
55G372C525
56G#371B4
57A370A#4
58A#369A4
59B368G#4
60C467G4
61C#466F#4
62D465F4
63D#464E4


Mapping of quarter tones

 Midi  Music  Midi  Music 
0F#164D4
1Gk165Ds4
2G166D#4
3Gs167Ek4
4G#168E4
5Ak169Es4
6A170F4
7As171Fs4
8A#172F#4
9Bk173Gk4
10B174G4
11Ck275Gs4
12C276G#3
13Cs277Ak4
14C#278A4
15Dk279As4
16D280A#4
17Ds281Bk4
18D#282B4
19Ek283Ck5
20E284C5
21Es285Cs5
22F286C#5
23Fs287Dk5
24F#288D5
25Gk289Ds5
26G290D#5
27Gs291Ek5
28G#292E5
29Ak293Es5
30A294F5
31As295Fs5
32A#296F#5
33Bk297Gk5
34B298G5
35Ck399Gs5
36C3100G#5
37Cs3101Ak5
38C#3102A5
39Dk3103As5
40D3104A#5
41Ds3105Bk5
42D#3106B5
43Ek3107Ck6
44E3108C6
45Es3109Cs6
46F3110C#6
47Fs3111Dk6
48F#3112D6
49Gk3113Ds6
50G3114D#6
51Gs4115Ek6
52G#3116E6
53Ak3117Es6
54A3118F6
55As3119Fs6
56A#3120F#6
57Bk3121Gk6
58B3122G6
59Ck4123Gs6
60C4124G#6
61Cs4125Ak6
62C#4126A6
63Dk4127As6