Table of Contents

1. Abstract

A modular synthesizer usually contains modules which have similarities. Oscillator modules for example have a controller for it's frequency and an (audio) output connector. The JPatch API supports taking advantage of these similarities. Mappings from one module to another can be defined in a XML file and the transformations can be automated. The user can use this feature to switch from one module to another while (some of the) parameter values and connections are retained.

2. Mappings

In this document the term mapping refers to the transformation t := (m_a → m_b) and the inverse t^-1 := (m_b → m_a) of the modules m_a, module m_b.

Each mapping contains the components (parameters and connectors) of two modules which can be mapped. The components have a selector id associated with them which is used to link a component of module m_a and a component of module m_b.

Using this table the mapping is defined as the intersection of the selectors: mapping(m_a,m_b) := selectors(m_a) ∩ selectors(m_b)

3. Transformations

Each pair of modules (m_a,m_b) defines a possible mapping, thus the mappings can be defined as a matrix with a row/column for each module. Because the the pairs of modules (m_a,m_b) and (m_b,m_a) refer to the same mapping the matrix is symmetrical. The pairs (m_a, m_a) are the identical mapping (diagonale).

If an initial set of mappings is defined it is possible to add some of the missing mappings to the matrix using an algorithm. For example in the matrix above the mappings (m₁, m₂) and (m₂, m_n) were defined at the beginning. These two mappings imply the third mapping (m₁, m_n). However, the algorithm must work carefully because different paths could result in better or worse mappings.

4. Transformations XML v1.1

The initial mappings can be defined using the Transformations XML v1.1 format.

4.1 Document Structure

Element: transformations

The element transformations is the root element. It has an attribute version containing the version of the specification (current version "1.1"). The element contains any number of group-elements.

<?xml version="1.0" encoding="utf-8"?>
<transformations version="1.1">
  ...
</transformations>

Element: group

The element group has no attributes and contains any number module-elements. Each combination of the containing modules defines a mapping. Two different groups must not contain the same pair of modules, more formally for each two groups g₁ and g₂ the condition g1 ≠ g2 ⇒ | g1 ∩ g2 | < 2 must be true. A group can contain at most one module with a specific id (component-id).

<group>
  ...
</group>

Element: module

The element module has the attribute component-id which contains the identifier (id) of the module. Possible child elements are parameter and connector.

<module component-id="SineOsc">
  ...
</module>

Element: parameter

The element parameter has the attribute component-id which contains the id of the parameter. The attribute selector is used to map this parameter to another parameter in the same group. A parameter (identified by it's component id) can be declared one time at most in the module element and there must not be any other parameter or connector element with the same selector value.

<parameter component-id="frequency" selector="freq" />

Element: connector

The element connector has the attribute component-id which contains the id of the connector. The attribute selector is used to map this connector to another connector in the same group. A connector (identified by it's component id) can be declared one time at most in the module element and there must not be any other parameter or connector element with the same selector value. The connectors which are mapped to each other must be of the same type either input or output.

<connector component-id="aout" selector="out" />

4.2 Example Document

<?xml version="1.0" encoding="utf-8"?>
<transformations version="1.1">
	<group>
		<module component-id="SineOsc">
			<parameter component-id="frequency" selector="freq" />
			<connector component-id="audioout" selector="aout" />
		</module>
		<module component-id="PulseOsc">
			<parameter component-id="frequency" selector="freq" />
			<connector component-id="audioout" selector="aout" />
			<connector component-id="fm-in" selector="fmin" />
		</module>
		<module component-id="SawtoothOsc">
			<parameter component-id="frequency" selector="freq" />
			<connector component-id="audioout" selector="aout" />
			<connector component-id="fm-in" selector="fmin" />
		</module>
	</group>
	<group>
		<module component-id="PulseOsc">
			<parameter component-id="frequency" selector="freq" />
			<connector component-id="audioout" selector="aout" />
			<connector component-id="fm-in" selector="fmin" />
		</module>
		<module component-id="PulseOscB">
			<parameter component-id="frequency" selector="freq" />
			<connector component-id="audioout" selector="aout" />
			<connector component-id="fm-in" selector="fmin" />
		</module>
	</group>
	<group>
		<module component-id="WaveWrapper">
			<parameter component-id="amount" selector="amount" />
			<connector component-id="audioout" selector="aout" />
		</module>
		<module component-id="Overdrive">
			<parameter component-id="overdrive" selector="amount" />
			<connector component-id="audioout" selector="aout" />
		</module>
	</group>
</transformations>

The example document defines the initial mappings of the modules SinceOsc, PulseOsc, SawtoothOsc, PulseOscB, WaveWrapper, Overdrive. Three mappings are defined in the first group { (SineOsc, PulseOsc), (SinceOsc, SawtoothOsc), (PulseOsc,SawtoothOsc) }, one in the second group { (PulseOsc, PulseOscB) }, and one in the third group { (WaveWrapper, Overdrive) }.

Some of the undefined mappings are derived using the matrix.

• ((SineOscB,PulseOsc) → (PulseOsc, PulseOscB)) ⇒ (SineOscB,PulseOscB)
• ((SawtoothOsc,PulseOsc) → (PulseOsc, PulseOscB)) ⇒ (SawtoothOsc,PulseOscB)

The third group {WaveWrapper, Overdrive} is independent of the other two groups, no further mappings can be derived.

This is the graph of the matrix above. Each edge represents a mapping. The blue edges are defined in the XML file, the red edges are derived.