
ReCombinator v1.2
=================

  22nd of January, 2016.

  mail: bs AT tkscript.de
   web: http://tkscript.de/recombinator/
   d/l: http://tkscript.de/recombinator/recombinator-22Jan2016.7z (latest)
   d/l: http://tkscript.de/recombinator/recombinator-09Jan2016.7z
   d/l: http://tkscript.de/recombinator/recombinator-20Dec2015.7z
   d/l: http://tkscript.de/recombinator/recombinator-26Nov2015.7z



** What's this ?

 ReCombinator is a Windows command line utility that creates polyphonic patch files for use with Propellerheads' Reason.

 It takes two input files:

   - a monophonic patch template ("imono")

   - a polyphonic patch template ("ipoly")


 and creates a new ".cmb" output file that instances the monophonic patch "n" times.


 Polyphonic patches can easily contain hundreds of devices and several hundred CV/audio connections so
  while editing these by hand is surely do-able, it just aint practical.

 This utility greatly simplifies the creation of polyphonic "modular" patches in Reason by automating the
  necessary device duplication and CV/audio connection routing.


 Applications:
  - Polyphonize any monophonic synth
  - Thicken synths that are already polyphonic
     (the "voice patch" in the input combinator does not necessarily have to be monophonic)
  - Detailed control over envelopes.
     (for example, I'm often missing "curve" parameters for the decay/release times in polyphonic synths)
  - Detailed control over unison (e.g. phase start offsets, detuning, panning, ..) (can do unison with any synth)
  - Per-voice parameter randomization (also very useful for non-unison patches)
  - Arbitrary per-voice modulation (LFOs, automation / MIDI input)
  - Voice cross modulation
  - Store multiple, similar sounding patches in one combinator and use the Distributor for "patch selection"
    (don't have to create a new track for each patch variation)
  - Use any filter you like / multiple filters per voice, ..
  - Polyphonic microtuning (via the monophonic MicroTune RE)



** Changelog

 * 22Jan2016
   - Fix "in pitch", "in mod", "in press", "in sust" (ignore <voice_nr> prefix)


 * 09Jan2016
   - Prefix names of generated voice device instances with "<voice_nr>:"
      - This can be turned off using the new "-np" command line option
      - The update mode (-u) ignores the name prefix when searching for the devices to be updated
         but keeps the original device names in the new output file.

         For example, when the update device name is "rnd phase" and the combinator patch to be updated contains
         4 instances named "1:rnd phase", "2:rnd phase", "3:rnd phase", "4:rnd phase", these instances will
         be replaced with the mono input file device named "rnd phase" but the "1:", "2:" prefixes will be kept intact.


 * 20Dec2015
   - Fixed a Reason 7 compatibility issue ('form2' chunk is optional now)


 * 26Nov2015
   - Add "-u" command line option (update mode)

     This can be used to update all devices in a given combinator patch with a device in the "imono" input file.
     The mod matrix and trim settings for the device are updated as well.

     Example:
      recombinator data.tkx examples/microtune -u examples/microtune_out_b.cmb "SubTractor 1 copy"

      => Read "examples/microtune_imono.cmb" and "examples/microtune_out_b.cmb" and copy the device named
          "SubTractor 1 copy" from the mono input file to all instances in the polyphonic output file.
          The resulting patch will be saved to "examples/microtune_out.cmb"

     This option is useful when you have already edited the "out" file from a previous run but want to update
      all voice instances of a specific device (e.g. when you have edited a synth voice or effect patch).


 * 23Nov2015
   - Initial release. 



** Requirements:

 - Microsoft Windows (tested on Windows 7. Earlier versions, e.g. XP, will probably work, too)
    - Note: Something like WINE <https://www.winehq.org/> will most likely work, too

 - Propellerhead Reason v8.3 (earlier versions may work, too but are untested)

 - "Distributor" Rack Extension <https://shop.propellerheads.se/product/distributor/>  (costs 19 euros)

 - "One-Note Stand" Rack Extension <https://shop.propellerheads.se/product/one-note-stand/>  (free of charge)



** Usage:

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

 2) This is a command line utility so you will need to open a new "shell":

    Press "left windows key + r", then type "cmd" and press return.

    This should leave you with a new command line window.

 3) Now change to the unpacked recombinator directory:

    C:\users\xyz> d:
    D:\> cd recombinator
    D:\recombinator> 

 4) Try out one of the example patches:

    d:\recombinator> recombinator data.tkx examples\subtractor_dc2_pad

    This should output the following lines:
      [...] Using mono template file = "examples\subtractor_dc2_pad_imono.cmb"
      [...] Using poly template file = "examples\subtractor_dc2_pad_ipoly.cmb"
      [...] Using   poly output file = "examples\subtractor_dc2_pad_out.cmb"
      [...] ok, .cmb file loaded from "examples\subtractor_dc2_pad_ipoly.cmb", size=4548
      [...] Using numVoices=8
      [...] ok, .cmb file loaded from "examples\subtractor_dc2_pad_imono.cmb", size=8398
      [...] processing voice 1/8
      [...] ok, .cmb file loaded from "examples\subtractor_dc2_pad_imono.cmb", size=8398
      [...] processing voice 2/8
      [...] ok, .cmb file loaded from "examples\subtractor_dc2_pad_imono.cmb", size=8398
      [...] processing voice 3/8
      [...] ok, .cmb file loaded from "examples\subtractor_dc2_pad_imono.cmb", size=8398
      [...] processing voice 4/8
      [...] ok, .cmb file loaded from "examples\subtractor_dc2_pad_imono.cmb", size=8398
      [...] processing voice 5/8
      [...] ok, .cmb file loaded from "examples\subtractor_dc2_pad_imono.cmb", size=8398
      [...] processing voice 6/8
      [...] ok, .cmb file loaded from "examples\subtractor_dc2_pad_imono.cmb", size=8398
      [...] processing voice 7/8
      [...] ok, .cmb file loaded from "examples\subtractor_dc2_pad_imono.cmb", size=8398
      [...] processing voice 8/8
      [...] generated CMB has 42 devices and 74 connections
      [...] ok, .cmb file written to "examples\subtractor_dc2_pad_out.cmb", size=60502
 
    And there you have it, a polyphonized combinator patch file !

    You can load it into Reason and play it. This particular patch uses Synapse's "DC 2" Chorus RE.
     If you don't have that, just remove the Chorus device from the monophonic patch file
     ("subtractor_dc2_pad_imono.cmb") and re-run the Recombinator.



** Polling mode

  ReCombinator can be run in polling mode by using the "-poll" option, e.g.:

    d:\recombinator> recombinator data.tkx examples\examples\subtractor_dc2_pad -poll

  This will create an initial "out" file, then wait for one of the input files to change:

      [...]
      [...] waiting for file update(s)..(press ctrl-c to quit)
      [...]    mono cmb: "examples\subtractor_dc2_pad2_imono.cmb"
      [...]    poly cmb: "examples\subtractor_dc2_pad2_ipoly.cmb"
      [...]     out cmb: "examples\subtractor_dc2_pad2_out.cmb"

  Once you have changed the "imono" or "ipoly" file in Reason and have saved it (important!), a new
   output file will be created automatically.

  You will still need to manually reload the output file in Reason, e.g. by switching to the previous patch, then
   switching back to the output patch (the arrow buttons in the combinator).

  To exit polling mode and quit, press "ctrl-c".



** Notes

 - The "imono" combinator input file MUST contain:
    - one "One-Note Stand" instance

       The CV/GATE connections will automatically be replaced with the Distributor CV/Gate voice 1..8 outputs
        when the polyphonic output patch is created.

       Make sure that no device other than the "One-Note Stand" receives notes (see Combinator Programmer in Reason).

 - the "imono" combinator SHOULD contain:

    - an audio-generating device that is connected to the "From Devices" inputs of the combinator

       This connection will be re-routed to the Mixer 14:2 input in the output file.
        (Input 1 for Voice 1, Input 2 for Voice 2, and so on)

       The device's CV/Gate inputs should also be connected to "One-Note Stand" CV/Gate outputs

 - The "imono" combinator may additionally contain:
    - Spider CV instances named
       - "in pitch"
       - "in mod"
       - "in press"
       - "in sust"

       If there's something connected to the "Split A" input of one of these Spider CV devices
        - a single instance of the connected device will be created in the output patch
        - the output of that device will be auto-routed to the Distributor "PITCH", "MOD", "PRESS" and "SUST" input(s)
        - the Distributor "PITCH", "MOD", "PRESS", "SUST" outputs will be auto-routed to the Spider CV instance

       This can be used to route global CV inputs to all voices.

 - The "ipoly" combinator input file MUST contain:
    - one Distributor instance
    - one Mixer 14:2 instance

 - The number of voices is determined by looking at the Distributor setting, i.e. the Distributor that is
    in the "ipoly" input file.

 - The number of voices can be overridden using the "-num" command line argument. For example,
      d:\recombinator> recombinator data.tkx examples\examples\subtractor_dc2_pad -num 2
    will create a duophonic output file.

 - The "imono" combinator modulation routing will be duplicated for each voice

 - Hint: The Distributor "mod" output is unipolar

 - Hint: The Distributor "sust" output has special meaning, it cannot be used as a general purpose CV output
    (if the CV value is > 0, the current voices will sustain)



** Tips'n'Tricks

 - It's generally a good idea to "randomize" the Mixer 14:2 panning in the "ipoly" input file

 - The tool can be used recursively, e.g. it is possible to create a unison output patch in the first run, then
    create the final polyphonic output patch in the second run.
     (you will need a very fast machine for this, though!)

 - The "One-Note Stand" device generates a CV=0 output when a note is released. This (unusual) behaviour differs
    from what the "Distributor" outputs in the generated patch and may cause connected devices (e.g. "CV Mutant")
    to retrigger.

    Tried workarounds include:
     - Latching the ONS CV output by using a "Volt SH-1" instance
        (a latch samples the incoming value when a gate signal is received)
        For an example how to do this, see the "ammo400_key_randphase" example patch
     - Connecting a "Charlotte" instance to the ONS CV/Gate outputs
        (it's a decent envelope generator and you will most likely need one, anyway)

 - The input and output file names are usually generated by appending
    - "_imono.cmb"
    - "_ipoly.cmb"
    - "_out.cmb"
    to the patch file name prefix you provided on the command line.

    However, the input file names can also be set manually by using the "-m" and "-p" command line options.
    The output file name can be set with the "-o" options.

 - Once you've edited the generated "out" file, remember to save it to a new file (e.g. "<patchprefix>_out_a.cmb")



** Reason CPU Usage

 Naturally, polyphonic patches need a lot more processing power than monophonic ones.

 For example, a patch using 8 voices, each containing an "Ammo400" oscillator and a "PMS-20" filter device,
  will cause an average load of ~12% on a modern day i7 quad core CPU (Reason will show 2 bars of DSP usage).

 However, the 8 voice "subtractor_dc2_pad" example patch mentioned above just uses ~3% CPU time.

 So, polyphonic patches are definitely something to consider, at least if you have a fast machine.

 One last thing regarding CPU usage: Reason has a bug that causes the DSP load display to show the wrong load
  when Reason is run on a machine that has a hyperthreaded CPU.

 For example, on a system with a i7-4770 CPU, a DSP load of 3 bars means that the CPU is actually at ~75% load.


** Bugs

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


Have fun !
