AR Uploader v1.0
================

  19th of Feburary, 2016.

  mail: bs AT tkscript.de
   d/l: http://tkscript.de/files/other/ar_uploader-19Feb2016.7z (latest)
   d/l: http://tkscript.de/files/other/ar_uploader-14Feb2016.7z (older)



** What's this ?

 AR Uploader is a sample upload tool for the Elektron Analog Rytm drum computer.

 It uses the MIDI Sample Dump Standard (SDS) protocol.

 
 Unlike the C6 uploader for Windows, provided by Elektron themselves, this application
 can batch-upload thousands of samples in one go.

 The problem with C6 is that batch sample uploads often stop after a few uploaded samples,
 forcing you to baby-sit the uploads.

 It's actually not Elektron's fault but an issue with the Windows 7 USB MIDI driver but
 there is a workaround so I hope that Elektron implements that in their own tool as well.


 Once you've installed the recommended tools, using this tool is as easy as this:

   $ ./upload_dir.sh /d/samples/percussion/packs/samples_from_mars/Modded\ 707\ From\ Mars\ -\ Samples\ From\ Mars/Modded\ 707\ From\ Mars\ -\ WAV/

 This will convert the entire sample directory and all its sub-directories to the AR sample format and
 upload the samples to the AR.

 All you will probably want to do afterwards is sort the files into directories
 (on the AR, there's no known way to automate this), then make some nice music.

 
 ** SAMPLE CHAINS **

 Since the February 19th release, this tool can also be used to create "sample chains".

 A sample chain is basically just a long sample that contains "sub samples" that can
 be played by adjusting the sample start parameter on the Analog Rytm.

 Sub-samples in sample chains are automatically aligned so that the exact sample start
 can be dialed in on the Analog Rytm (without requiring any tricks like using an LFO for fine tuned start points).

 Sample chains come in two flavours:
  - With regular sample chains, sub-samples are evenly distributed in the generated waveform.
    Therefore, a fixed sample start "step" (e.g. 8) can be used to address the sub-samples on the AR

  - "Varichains" use varying sub-sample lengths.
    Therefore, the sample start parameter on the AR is not a multiple of a "step" constant.
    However, all sub-samples are still aligned to a common block size.

 Last but not least, it is possible to add some silence / padding after each sample chain sub-sample.
 This can be used to avoid accidental replay of the following sub-sample.

 Historically, "sample chains" were first used with "Tracker" programs on the Amiga home computer in the early 90ies.
 The software back then had a limitation of 31 samples per song ("module"), so musicians had to find a way
 around that limitation -- they used sample start offsets and stored more than one samples in one waveform.




** Changelog

 * 19Feb2016
   - Fix stereo->mono channel conversion in "upload_dir.sh" script (add "-c 1" SOX option)
   - Add "convert_dir.sh" script (convert to 48k mono 16bit but do not upload samples)
   - Add "-chain <length>" option (create sample chain that consists of <length> evenly spaced sub-samples)
   - Add "-varichain" option (create sample chain that consists of aligned, but not evenly spaced sub-samples)
   - Add "-dir" option (prefix filenames in filelist.txt with a specific dirname)
   - Add "-single <filename.wav>" option (upload a single wav file instead of using filelist.txt)
   - Add "-name <samplename>" option (set AR sample name of single wav or sample chain file upload)
   - Add "-pad <numsamplefragments>" option (add padding after each sub-sample in a sample chain)
   - Add "-autodir" option (prefix filenames in filelist.txt with dirname of filelist.txt)
   - Add "-d" option (lots of debug text, plus this saves the generated sample chain to "debug.wav")
   - Add "-noupload" option (e.g. for generating sample chains without uploading them)
   - Add "upload_chain.sh" script (convert directory to 48k mono 16bit and upload as sample chain)
   - Add "upload_varichain.sh" script (convert directory to 48k mono 16bit and upload as vari-chain)


 * 14Feb2016
   - Initial release.



** Requirements:

 - Microsoft Windows (tested on Windows 7. Earlier versions, e.g. XP, will probably work, too)

 - Elektron Analog Rytm (with recent firmware, tested with 1.22B)

 - Recommended: SOX <https://sourceforge.net/projects/sox/files/sox/14.4.2/sox-14.4.2-win32.zip/download>
    Note: Use the default installation path (C:\Program Files (x86)\sox-14-4-2) or the "setenv.sh" script
           must be adjusted.

 - Recommended: MSYS/MingW <https://sourceforge.net/projects/mingw/files/latest/download?source=files>
    Note: After you have downloaded and started the installer and the "MinGW Installation Manager" appears,
           click on "All Packages", then on "MSYS Base System", then on the "msys-base" checkbox in the right panel
           (select "Mark For Installation"), then choose "Installation -> Apply Changes" in the pulldown menu.
           This should start the package download and installation.
           Now all you need to do is grow a beard and you will be on your best way to becoming a Unix hacker.



** Usage:

 1) Unpack this archive somewhere. The following instructions assume that you have unpacked it to "d:\ar_uploader"

 2) Open a new MSYS shell by executing "C:\MinGW\msys\1.0\msys.bat"

    This should leave you with a new command line window.

 3) Now change to the unpacked "ar_uploader" directory:

     (note don't copy'n'paste the $ char, just the string after that)

    $ cd /d/ar_uploader

    and run the environment variable setup script:

    $ . setenv.sh
    
    If you have MSYS and SOX installed, the following command will convert all .wav files in the
    specified directory and all its sub-directories to the AR sample format, then
    upload the samples to the AR:

    $ ./upload_dir.sh /d/my_samples/my_new_sample_pack/

    Keep in mind that you can use the TAB key to auto-complete file/directory names in the shell.

    Press "ctrl-c" to cancel any sample conversions and/or transfers.



** Notes

  - Samples are uploaded as fast as possible which puts the AR CPU under a lot of stress.
    It's not really possible to use the AR while samples are being uploaded.
    This is different from C6, which uses slower upload speeds to allow the machine
    to be operated in the mean time.

  - Since this is a command line tool, it is highly recommended to install a proper "shell".
    I'd suggest this one:  http://www.mingw.org/wiki/MSYS
    That gives you the same shell that is native to Linux and MacOS X.

  - Samples must be in .wav format, 48000Hz, 16-bit, mono.
    You can use SOX to convert the samples.



** Tips'n'Tricks




** Bugs

  If you have found a bug, drop me a mail and I'll try to fix it.


Have fun !
