=============================================
 ShruthiWaveGen basic instructions and hints
=============================================

01) ShruthiWaveGen is provided for free and as is, without any guarantees, promises, liabilities and obligations. It has been tested on OS X Mavericks and Snow Leopard as well as on Windows 7 and Mint Linux 12. It should work on any System able running Java JRE7+, but depending on your hardware/driver/OS configuration you may discover issues. Besides that, it has some known limitations, which will be addressed further down the line.

02) General technical infos:

2a) ShruthiWaveGen comes in a zip achieve containing an executable App for Mac OS X, and batch launchers for Windows and Linux, which you'll find in their respective sub-folders. You may delete the sub-folders with OS editions which you don't need. The application folder should be placed at a location for which you have write access rights, since ShruthiWaveGen will store its data next to itself to stay portable. On windows this unfortunately means you have to place it on your data drive or in your documents folder, due to write access restrictions in the program folder. As ShruthiWaveGen is a Java Application you need to have a Java Runtime Environment (JRE) installed. Preferably JRE7 or later, though it might work with JRE6, too. 

2b) Mac OS X came with a preinstalled Java in older (Snow Leopard, etc.) OS X versions, newer OS versions may require you to download and install an OS X compatible JRE via AppStore or manually from the Java / Oracle website. Additionally OS X security measures may prevent ShruthiWaveGen from starting, so in case this happens please do one of the following: Either a) Open terminal and run xattr -rc /my/path/to/ShruthiWaveGen.app or b) Open the System Preferences, Security & Privacy Panel, General Tab and set “Allow apps downloaded from” to “Anywhere”.
Depending on your OS some OS specific functions like file selectors may differ in their feature set and behavior. On OS X the CMD-Q key-command bypasses the Java quit handling, so no preferences get saved automatically - please use either the quit button of ShruthiWaveGen or press "save global defs" before hitting CMD-Q. On Linux you may have to flag the ShruthiWaveGen.sh batch as executable by Right-Click->Properties->Permissions Tab->Set the Execute: "Allow executing file as program" Flag.

2c) IMPORTANT: from version 2015_01_01 on, there needs to be a folder/file named ShruthiWaveGenD/SWGFirmwares/shruthi_1_02_firmware.syx with Shruthis original firmware. Please move this subfolder (SWGFirmwares) from the installation archive into the 'ShruthiWaveGenD' folder next to the application. Failing to do so will inhibit the firmware patching features of ShruthiWaveGen. (see also section 08 below)

Ok - enough of the legal and technical blah, let's get into the application!

__________________________________________________________________________________________________________________________________

03) The original screen resolution of ShruthiWaveGen is 1920x1200, but it is still fairly usable down to 1366x768, since it scales all components. Most Buttons have a key-command, please check out the title bar of ShruthiWaveGen for the explanation of the key shortcuts. There is a bit of mathematics under the hood, but the selection and number of controls has been chosen to have maximum effect with a minimum of interface elements. Some sliders change there function depending on the value of others sliders - play with them and discover ;).

04) The main screen of ShruthiWaveGen is not intended to be a sample editor, but to generate, manipulate and adjust one cycle wav files to be used as wave table sounds for your Shruthi. So please use either the DAW of your choice to trim down your audio file to a single cycle / period of the wave you want to play with your Shruthi before loading it into ShruthiWaveGen or check out section 07) below for another option. ShruthiWaveGen just loads wav files with a duration of up to around one second and ignores the original sample rate of the wav file (you may use any you want) and plays back everything at 48kHz. Due to the way Java handles audio output buffering there is unfortunately a short lag between changing a parameter / pressing a button and hearing the result in the played audio. At least it doesn't seem to generate glitches with the current solution. (Hint: When preparing your one cycle wav files you may discover an issue of your DAW… E.g. Logic Pro X despite it's overall maturity isn't able to properly play back short loops of audio in its sample editor. Therefor you may need to do a few copies of your wave one after the other to be able to listen to it without glitches.)

__________________________________________________________________________________________________________________________________

05) ShruthiWaveGen's main window has 8 sectors with the following jobs (from left to right and top to bottom):

5a) A list of single cycle/period wav files, which are the source of the following manipulations; use the 4 buttons below to add to, remove from, save or load the file list.

5b) The waveform display of the selected of the loaded waves.

5c) The frequency spectrum display of the selected of the loaded waves.

5d) The waveform of the selected of the loaded waves after all manipulations and the adaption on Shruthi's sample size (128).

5e) Here you can generate loads of new waveforms with frequency domain synthesis and choose some options how to adapt and manipulate the loaded and selected wave (controls below the "play generated" and "mute audio" buttons). Additionally you can save and load the generating parameters here (please note, that in random mode you won't get the same wave again, but just one with similar properties, so please save with "save generated wave" or inside a "wave set" in this case.) "Save global defs" saves things like window position, size, loaded files, etc.

5f) The display of the frequency spectrum of the generated wave form and also the frequency shape which may be imposed on the adapted wave via the "Filter adapted with gen spectrum slider" (only available in DFT mode).

5g) The display of the generated wave form

5h) Here you can add the adapted and / or generated wave to a wave set, which you may then save, load, export or send. Please note that Shruthi supports a wave set of 8 waves. If you add less to the wave set, the rest of the 8 waves get filled with chopped versions of the last wave in the wave set list. If the wave list contains more than 8 waves, only the 1st 8 waves get transmitted to your Shruthi or saved into a *.mid or *.syx file. To keep the whole list, please save it with "save wave set". If you have a massive amount of MIDI Ins&Outs, the "midi port scan" may take quite a while. Please wait until the light of the button goes off ;).

5i) Please note that there are some MIDI interfaces / drivers which lack reliability when it comes to sending SysEx bulk data. So if you encounter problems here, please try a different Interface 1st, before you blame ShruthiWaveGen. Setting the "export / send dithered 8bit" flag adds a simple LSB/2 FS/2 dither signal to the adapted / generated wave before it gets truncated to 8bit and exported / sent. This slightly reduces the audible effect of the 8bits quantization. If you love it gritty, just leave it off ;). 

5k) With the "send *.syx file" button you can send any previously saved or somewhere downloaded *.syx file to the selected MIDI port. Please note that Mac OS X has a broken Java MIDI implementation resulting in defunct transmission data. Therefor I would advise to use "SysEx Librarian.app" to transmit any generated *.syx file on OS X.

__________________________________________________________________________________________________________________________________

06) ShruthiWaveGen's playback handling is controlled by the following two entries in the file 'ShruthiWaveGen.swgd' in the directory 'ShruthiWaveGenD' both of which are created on the 1st start of ShruthiWaveGen:

<entry key="autoPlay">0</entry>
<entry key="autoMute">0.0</entry>

6a) autoPlay = 0; autoMute = 0.0: playback is started on pressing the corresponding buttons / key-commands and not stopped before 'mute' / either STRG-m or ALT-m is pressed depending on the used window.

6b) autoPlay = 1; autoMute = 0.0: playback is started as described under 6a) as well as by selecting a wave in one of the list fields or when altering any other wave changing parameter. playback has to be stopped manually as under 6a)

6c) autoMute > 0.0 (= seconds with 1 fraction digit): playback as under 6a) or 6b) depending of the variable 'autoPlay', but playback is automatically stopped/muted after 'autoMute' seconds.

__________________________________________________________________________________________________________________________________

07) ShruthiWaveGen:WaveEditor / wave editor / CTRL—NUMPAD-MINUS
To make it easier to acquire wave cycles I've added a slim wave editor to ShruthiWaveGen with a feature set optimized for this one specific task. It can load wav files up to 2GB (depending on the amount of RAM on your machine) and sports quite some key commands in addition to the visible controls. The loaded file is not altered by WaveEditor (as long as you don't overwrite it via 'save selection' ;)), so the options to the right of the 'open file' button are just added to the loaded audio data. Now to the list of available functions:

- extend to zero crossings / ALT-z / ALT-SHIFT-z:
select the audio from the cursor(-range) up to the next low to high zero crossing to the right; ALT-SHIFT-z searches for zero crossings in both directions of the cursor

- shrink to zero crossings / ALT-u / ALT-SHIFT-u:
shrink the audio selection from the cursor(-range) down to the next low to high zero crossing to the left; ALT-SHIFT-z searches for zero crossings inwards of the cursor selection range

- mark from selection / ALT-t / ALT-SHIFT-t:
save the current selection to the internal marker list; ALT-SHIFT-t removes the marker under the current cursor (the cursor(-range) needs to be inside or equal to the marker range) and sets the cursor selection to the markers boundaries

- previous cycle / ALT-LEFT / ALT-SHIFT-LEFT:
- next cycle / ALT-RIGHT / ALT-SHIFT-RIGHT:
if you have selected a wave cycle with the (z) and / or (u) command, you can use this commands to step cycle-wise through the audio data in both directions. The SHIFT variant tries to keep the cycle smaller, the regular version may increase the cycle length depending on the audio material. If this happened, you may also utilize the (u) command to slim the cycle down again.

- ALT-SHIFT-UP / ALT-SHIFT-DOWN:
if you have selected a wave cycle, you can use this commands to step cycle-wise with a fixed cycle length through the audio data in both directions. 

- ALT-UP / ALT-DOWN:
jump to next marker region to the left or right and set the selection to the marker region

- remove ALL markers / ALT-r:
this function removes all set marker regions at once after a confirmation dialog. ATTENTION: NO UNDO here!

- play selection / ALT-,:
plays the current selection accordingly to the above described playback settings

- play cycles / ALT-p:
plays a sequence of all marked regions (each marked cycle is repeated a few times for a better listening experience) accordingly to the above described playback settings

- play all / ALT-NUMPAD-*:
plays the complete audio file in a loop accordingly to the above described playback settings

- mute / ALT-m: 
mutes / stops any of the above playback options

- save markers / ALT-f:
saves all currently defined marker regions with a link to the currently loaded audio file. Please note that if you move that file from its location on your hard drive, the next attempt to load it with 'load markers' will fail.

- load markers / ALT-g:
loads the file for which the markers have been defined and marks all saved regions. In case you've moved the audio file: there is a way to rescue the marker file by opening it in a text editor and change the 'audioFile' entry to the new location.

- save selection / ALT-s / ALT-SHIFT-s:
saves the audio data inside the current selection to a *.wav file and automatically adds it to ShruthiWaveGen's file list. The SHIFT variant skips the adding to the file list. 

- export cycle sequence / ALT-y / ALT-SHIFT-y:
saves the concatenated audio data of all marked regions to a single *.wav file and automatically adds it to ShruthiWaveGen's file list. The SHIFT variant skips adding the file to the list. 

- export wave cycle file(s) / ALT-e / ALT-SHIFT-e:
saves the audio data to a *.wav file for each marked region and automatically adds all of them to ShruthiWaveGen's file list. The SHIFT variant skips adding all the files to the list. 

- ALT-w:
close ShruthiWaveGen:WaveEditor window.

__________________________________________________________________________________________________________________________________

08) ShruthiWaveGen:FirmwarePatcher / firmware waves / CTRL-NUMPAD-PLUS
1st a word of caution: if something goes wrong with uploading the patched firmware into your Shruthi, it won't start anymore until you've managed a complete upload of its firmware.
2nd you should know, that after you've made changes to Shruthi's internal waves / waveTables, it'll never sound the same again - well at least not until you restore the original firmware. To put it differently: all programmed sounds in your Shruthi which use the internal ROM waveforms / wavetables, which you may alter with this tool, will sound different. And when you program sounds with your new waveforms, they'll be spoiled in case you would go back to the official firmware version.

Make sure you've read and understood section 2c) and 5k) before you continue here!
To have as much screen / window real estate available to display the waveforms, the ShruthiWaveGen:FirmwarePatcher heavily relies on key-commands, mouse-buttons and modifier keys (heavy nerd alarm here ;)), which will be listed in the following description. But 1st to the few visible controls:

original / ALT-1:
user / ALT-2:
waveSet / ALT-3:
with these buttons you may switch between the three views / tabs / panels containing the waves and waveTables of the original firmware, the user firmware (that's yours!) and the waveSet, which is a visual copy of the waves you've defined in ShruthiWaveGen's 'wave set' section. Any change in that section is directly reflected in FirmwarePatcher's waveSet view.
'original' and waveSet are read-only pages intended solely as waveform copy from source.

mute / ALT-m:
just does what it says when something plays…

export / ALT-x / ALT-SHIFT-x / ALT—CTRL-x / ALT—CTRL—SHIFT-x:
it's all in the x:
ALT-x = saves your patched Shruthi firmware to the default file inside the ShruthiWaveGenD/SWGFirmwares folder.
ALT-SHIFT-x = saves your patched Shruthi firmware with a file name of your choice inside the ShruthiWaveGenD/SWGFirmwares folder and sets this very file name as the new default file name.
ALT—CTRL-x = loads a user firmware file (*.syx) of your liking to the user view/tab and takes it as the new default file to save to and load from.
ALT—CTRL—SHIFT-x = loads user firmware from binary (*.bin) file which just contains the naked firmware data (super-geek-only-feature).

The list next to these few buttons shows all of Shruthis waveTables which contain references to the waves you are about to patch in Shruthi's ROM. When you select a list entry, the referenced waves of this waveTable are shown to the right. Depending on how many waves are defined in a waveTable, there may be shown any number of waves in between 1 and 17.

And now to all the invisible commands…

You select a wave in the upper part of the window with a left-mouse-click, you may play it with a center-mouse-click and you should be careful with the right-mouse-click (read below).
But 1st the only two non-destructive operations:

- ALT-PAGE_UP / ALT-PAGE_DOWN: 
after you've selected a wave in the user panel (it has got a green frame) you can swap it with the wave to the right or left with this command. All references in the waveTables of the user firmware patch panel are adjusted accordingly. This is intended to sort the waveforms in 'I wanna keep that one' and 'why should I use that one' sections without changing anything sonically on your Shruthis sound programs.

- SHIFT+right-mouse-click:
all as above, but you swap the selected wave with the one you are right-clicking on

And now it gets destructive. Please be warned - there is NO undo, like in real life ;). (Except for the last saved firmware version, you could restore to via ALT—CTRL-x.)

- right-mouse-click (on upper part of panel):
you overwrite the wave you've clicked on with the one you've selected with left-mouse-click before. This source wave may also reside on the 'original' or 'waveSet' panels.

- right-mouse-click (on lower part of panel in the waveTables):
you overwrite the reference to the wave you've clicked on or you add the waves reference to the waveTable at the end of the table, when you click into an unused wave slot.

- ALT-NUMPAD-PLUS / ALT-NUMPAD-MINUS:
if you want less waves in a waveTable press ALT-NUMPAD-MINUS, if you want more press ALT-NUMPAD-PLUS. Please note, that this does not delete or add references to waves, but just hides or uncovers these. 

- ALT-SHIFT-w:
close ShruthiWaveGen:FirmwarePatcher window.

And I saved the worst for last:
- ALT-CTRL-META-SHIFT-r:
resets the user firmware panel to Shruthis official firmware (shruthi_1_02_firmware.syx). NO UNDO! (except for the reload last saved user firmware trick)
META on OS X = Apple-key, on Windows = Windows-key

__________________________________________________________________________________________________________________________________

I hope the rest of this specialist tool application is pretty self-explaining and you have a lot of fun with it, while creating crazy new waves for your Shruthi!

Cheers,
badtidude


(c) 2014/2015 badtidude

__________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________

P.S.: the direct launch command in case of trouble with the app or exe is:

java -Xmx9200M -jar ShruthiWaveGen.jar

__________________________________________________________________________________________________________________________________