~*~*~*~*~*~*~*RETUNE FOR LIVE*~*~*~*~*~*~*~

~*~*~*~*~*~*~*~*~*version 1.4*~*~*~*~*~*~*~
~*~*~*~*~*~*Coded by Ursin(e)*~*~*~*~*~*~*~

=-=-=-=-=Package includes:=-=-=-=-=
- Retune for Live Transmitter.amxd
- Retune for Live Receiver.amxd
- An example of a custom .csv tuning file ("Ho Cheng Tien Tuning.csv")
- Some of Ursin(e)'s favorite .scl files
- Two well-matched .scl+.kbm pairs to inspire you with new possibilities!
- This readme

Most recent video tutorial available at https://youtu.be/p864_GmKBNM

=-=-=-=-=To set up a retuned instrument:=-=-=-=-=

(Thank you so much to softpunch for posting this fabulous one-track solution to the
maxforlive.com listing of RfL)

1. Create a MIDI Track, add a RfL Receiver and your instrument to the track

2. Highlight both devices (Shift+click), right-click and choose Group (Ctrl+G)

3. In the newly created rack, show the chain list (middle left small circle icon)

4. Highlight the chain, right-click, select Duplicate (Ctrl+D) and create as many
copies as you would like for voice polyphony

5. Select the channel in each receiver from 1 through [however many voices you're
using]. I recommend starting at the last group in the chain and using the up arrow
key and clicking to work your way through the list.

6. Drop a RfL Transmitter in front of the Instrument rack and get cooking! (Be sure
all settings like Pitch Bend Range, Instrument # and Number of Voices are all
correct)

(7. To easily make alterations to your settings across all synths/receivers,

remember to right-click -> "Copy to Siblings")

||You can repeat this process for up to 32 instruments.

||Make sure to select a new "Instrument #" on both your new
||Transmitter and Receiver tracks.
||
||To use multiple tunings, select a different "Tuning Channel" and make changes!
||This way, Transmitters can either share tuning information or not.

=-=-=-=-=New in v1.4=-=-=-=-=
- Added full support for Scala Keyboard Mapping (.kbm) files. These work in tandem
with .scl files to allow the retuner to specify exactly where on the keyboard the
scale goes and what frequency gets used to map the scale. While .kbm files are easy
to create/modify within a text editor, I highly recommend creating these with the
Scala software (http://www.huygens-fokker.org/scala/downloads.html) or Sevish's
scale workshop (https://sevish.com/scaleworkshop/)

- Added "Tuning Channel" feature. This allows for Transmitters to share tunings or
to have independent tunings from each other. Users can now have up to 32
simultaneous Tuning Channels!

- Fixed issue with loading certain .scl files in Live 10/Max 8

- Majorly optimized and cleaned up existing code

- Fixed issue where unmapped notes would output high frequencies instead of silence

- Reworked "Center Frequency" feature. The note A4 can take on any value from 320-
560Hz and this now works much more reliably.

- Reduced size profile of Transmitter and Receiver devices

=-=-=-=-=New in v1.3=-=-=-=-=
- Fixed a glitch where only the first .csv imported into a session would work right

- Added Equal Division Setting to replace Equal Temperament

- Included Octave Stretching for Equal Divisions

=-=-=-=-=New in v1.2=-=-=-=-=
- Fixed glitch where notes would drop out and lots of MIDI data wasn't getting
passed through to all voices

- Retooled some details about passing data between the transmitters and receivers,
hopefully providing a more stable experience

- Fixed Center Frequency functionality, so that A4 can be defined as any frequency

between 220Hz and 880Hz

- Added automation names for Transmitter and Receiver parameters

=-=-=-=-=New in v1.0=-=-=-=-=
- Revamped the guts so it is now possible to implement any imaginable (audible)
tuning system, no longer restrained by the instrument's pitchbend range

- All settings on the Retune for Live device now save with the Live session.
(!!!!!) This was a big deal for me because it does away with a lot of the friction
in using the device.

- Retune for Live is now compatible with the Scala scale file (.scl) standard. To
read more about the .scl tuning standard and download the full archive, visit:
http://www.huygens-fokker.org/scala/scl_format.html

- RfL now supports .csv files instead of .txt files. For more information on the
custom file format, see the "Custom Tuning Files" section. I felt this would make
the custom tuning user experience a lot simpler, as .csv files are easily created
and edited with any spreadsheet software.

- Pitchbend wheel is now usable. The pitchbend wheel range is decreased one
semitone to leave room for the retuning magic that is going on.

- Slightly cleaner and more readable Max code.

=-=-=-=-=Hopes for Future Features=-=-=-=-=

- I would love to learn more about MPE and implement it in Retune for Live to give
users expressive control over the individual notes they play. It might be
impossible, or it might require a total reworking of the device, but it also might
be a quick rigging operation. (Read more here: https://www.midi.org/articles-
old/midi-polyphonic-expression-mpe)

- Implement a "movable root" just intonation feature, so the pitches are

recalculated whenever the root changes (right now this can be automated, but is not
easily done on the fly)

- Implement other tuning file standards, such as the .tun file or the SysEx MTS
Dump. Although I kind of feel like the .csv and the .scl+.kbm files offer enough
flexibility for users.

- I would love to create a VST version of Retune for Live for use on any DAW. If
you're reading this deep into the readme, I assume you're pretty hardcore. Are you
familiar with the JUCE C++ library/Steinberg SDK? I need some help getting this
project off the ground. Please contact me!

- Requests from users?

=-=-=-=-=Custom Tuning Files=-=-=-=-=

|| .csv
Retune for Live now supports two file formats for users to implement custom tuning
schemes. The first is a .csv file formatted in two columns and 128 rows, one per
MIDI note. Here are the first five lines of a properly formatted .csv file:

0,8.085297046
1,8.567455833
2,9.078367688
3,9.619747273
4,10.1934115

The first number is the MIDI note to be played, and the second number is the
desired frequency in Hz. Any note that should not be mapped should include a 0 for
that frequency value.

.csv files can be easily created in excel or google sheets, and offer great
flexibility in working with RfL. There are endless methods of contriving the
frequency values, so do some research and write some excel formulas!

|| .scl+.kbm
The second file format compatible with RfL is the Scala scale file (.scl) standard
as well as the mapping file (.kbm). Scala tuning files are extremely readable and
easy to create. Most importantly, there is a massive archive of 4000+ tunings that
have been contributed to the official archive almost two decades in the making. To
read more about the .scl tuning standard and download the full archive of tunings,
visit: http://www.huygens-fokker.org/scala/scl_format.html

To map a .scl file, Retune for Live simply takes the starting pitch from the
Transmitter's center note interface and builds the .scl file above and below the
center, assigning one note per chromatic keyboard key, and repeating until the
scale leaves the range of available MIDI notes. Custom mappings are not implemented
at this time.

Once you have loaded in a .scl file, pick a .kbm to select exactly which scale
degrees, where on the keyboard they go and which reference frequency.

Check out the two example kbm+scl pairs included with this download:

(19-31ji.scl) + (19_to_12.kbm) takes a 19 note scale and maps it onto the standard
keyboard by choosing specific scale degrees and a 12 note map pattern.

(pelog7.scl) + (white_notes7.kbm) takes a 7 note gamelan scale and maps it onto the
white notes of a standard keyboard for easy playing.
As I mentioned before, the Scala software (http://www.huygens-
fokker.org/scala/downloads.html) or Sevish's scale workshop
(https://sevish.com/scaleworkshop/) both offer amazing interfaces for designing
these scl+kbm pairs.

=-=-=-=Known "Bugs" or Otherwise Undesirable Behaviors=-=-=-=

- As of this release, I've tackled all known bugs. Please reach out with any you
find!

=-=-=-=-=Closing Thoughts and Contact Info=-=-=-=-=

||Retune for Live v1.4 coded by Ursin(e)

<manifesto>
This device represents an enormous amount of hours of research and development.
It's my baby, and it's been a blast improving it and making it great. I briefly
considered selling it, but a donation based system suits my goals more closely. (If
you tossed a few bucks my way, thank you so much! It means a lot to see your
support and helps me invest more time into improving this device.) My lofty goal is
to enable musicians familiar with the Ableton Live workflow to expand their tonal
options and start working with non-12edo scales. I believe that, if we want a
larger body of great microtonal music, we must equip great musicians with tools
that make it easy to include these kinds of melodies and harmonies into their
existing creative process. I hope to remove some of the barriers of clunky software
and pretension that infamously come with "experimental composition with non-western
tunings" for Ableton users merely interested in escaping the standard notes on a
keyboard. I love Equal Temperament - most of my favorite songs are written in it -
but playing around with Bohlen-Pierce or Gong Kebyar Pelog Selisir makes me feel
like a kid again, and I hope the users of this software gain similar amounts of
inspiration from this tool.
</manifesto>

<attribution>
Please don't take my code and call it your own without giving me a shout out! This
code is under a CC AttributionNonCommercialShareAlike license. If you're not sure
what that means, google it!
</attribution>

<thanks>
Speaking of, many thanks to EXIT INDUSTRIES (nezzyidy on the Ableton forums) for
her/his work on the PolyMind System. I completely stole a very key idea (i.e. the
udpsend and udpreceive objects) for implementing this Retuning system in M4L from
PolyMind. This has since been replaced by the max forward/receive object pair, but
their patch solved a big problem for me early on!

I also referenced the MICROTUNER M4L code, though I am having trouble figuring out
who to attribute original credit to. Please contact me if you want original credit
in this Readme.

Folks on the Cycling '74 forums have been a majorly important resource to me, and I
have tried to leave comments (both on the message board threads and in my code)
thanking users who have generated code that I have adapted/outrightly stolen for
RfL.

<history>
For more information on Ho Cheng Tien's nearly equal temperament tuning from the
4th century AD, see:

Nakaseko, Kazu. (1957). Symbolism in ancient Chinese music theory. Journal

of Music Theory, 1(2), 147 - 180.
</history></thanks>

Thoughts? Constructive criticism? Thanks?

||Contact Me: ursinemusic@gmail.com

=-=-=-=-=Shameless Self Promotion=-=-=-=-=

@ursinemusic on Instagram
www.ursine.bandcamp.com
@ursine_music on twitter