Waldorf Quantum/Iridium: write up to four layers, the layout of the MK2 generation

documentation/CHANGELOG.md

@@ -119,6 +119,7 @@
   * Fixed: The cutoff of the filter was written with the normalized parameter value as its display text, so the device listed a patch with a cutoff of e.g. 61.7 Hz as '0.2592 Hz'. A cutoff at the top of the range of the model (20,000 Hz) also wrote a parameter value slightly above the 1.0 the device expects; it is now limited to the 19,912.2 Hz of the device.
   * New: The volume and the pan of the whole timbre (TBPIVolume, an attenuation in dB, and TBPIPan, -63..63) are read and applied on top of the settings of the partials; a timbre which the editor turned down - by up to 16 dB in the Studio G Dallas library - was converted at full level.
 * Waldorf Quantum/Iridium
+  * New: The 'Use a second layer' option became 'Maximum number of layers' with 1 to 4 layers. With 3 or 4 layers a source with more than 6 groups is written with up to 9 or 12 multi-samples in the layout of the MK2 generation: the layer count 2, the format version 15 and always four stored layers, of which the unused ones are switched off, exactly as the Iridium MK2 stores its own patches (304 files of the corpus). The loader of the device clears the file offsets of the layers 3 and 4 in files up to the version 14, which is why four layers need the version 15; the first generation of the instruments holds two layers (its manuals) and cannot play such a file. Verified on an Iridium MK2 (OS 4.0.6): a written 4-layer patch with one sample pitch per layer plays all four pitches, a 3-layer patch with its switched-off fourth layer plays its three. Only as many layers as the groups need are used, so a source with up to 6 groups is still written as the 2-layer patch which every instrument of the family plays. The samples of all later layers are named in the first layer for the importer of the device. A setting of the old option is taken over.
   * New: Round robins are written into one sample map. Entries of a map which overlap in key and velocity alternate on successive notes on the device, which is exactly a round robin; the zones of a round robin were spread over separate oscillators as if they were stacked layers, so all of them sounded at once on every note. When reading, overlapping entries of a map become a round robin. The device has no random selection, so random zones alternate as well.
   * New: A monophonic source is written with the mono mode of the patch (PolyMonoMode), which is read back as well.
   * New: The key window of an oscillator (Osc{i}MinNote/MaxNote) is applied when reading: a zone outside of it is silent on the device and is dropped, a zone across its edge is cut at it.

documentation/README-FORMATS.md

@@ -1015,7 +1015,7 @@ Writing creates such a folder, which only needs to be copied to the device. Note
 
 This family of Waldorf synthesizers supports the playback of multi-samples. One preset can contain several layers - 2 on the first generation of the instruments and 4 on the MK2 generation (Iridium MK2, Quantum MK2 and instruments upgraded to MK2 hardware). A layer is a complete preset in itself and the layers are simply concatenated. Each layer can have up to 3 oscillators of which each oscillator can contain its own multi-sample. The format is not documented by Waldorf; the file layout, the sample map and the value laws which are read and written are described in *documentation/design/WALDORF_QPAT_FORMAT.md*.
 
-If this format is used as the source it produces one output preset per layer which plays samples; a layer which is switched off, or which plays a wave-table instead of samples, is reported and skipped. If used as the destination format, each group of the source multi-sample is applied to one of the 3 oscillators of a layer; with the *Use a second layer* option a preset holds up to 6 multi-samples instead of 3, and all groups which do not fit are added to the multi-sample of the last oscillator, as before. Note that the device cannot select a layer by velocity - it splits its layers by key, by MIDI channel or cycles them - so a velocity split is always written into the sample maps of one layer and only sounds which are meant to be heard together are spread across the layers. A round robin stays inside one sample map as well: entries of a map which overlap in key and velocity alternate on successive notes on the device, which is how it plays a round robin, and overlapping entries are read back as one (the device has no random selection, so random zones alternate too). A monophonic source is written with the mono mode of the patch.
+If this format is used as the source it produces one output preset per layer which plays samples; a layer which is switched off, or which plays a wave-table instead of samples, is reported and skipped. If used as the destination format, each group of the source multi-sample is applied to one of the 3 oscillators of a layer; with the *Layers* option a preset holds up to 6 multi-samples on 2 layers or up to 9 or 12 on 3 or 4 layers of the MK2 generation instead of 3, and all groups which do not fit are added to the multi-sample of the last oscillator, as before. Note that the device cannot select a layer by velocity - it splits its layers by key, by MIDI channel or cycles them - so a velocity split is always written into the sample maps of one layer and only sounds which are meant to be heard together are spread across the layers. A round robin stays inside one sample map as well: entries of a map which overlap in key and velocity alternate on successive notes on the device, which is how it plays a round robin, and overlapping entries are read back as one (the device has no random selection, so random zones alternate too). A monophonic source is written with the mono mode of the patch.
 
 The volume, panning and tuning of an oscillator are offsets on top of the values of its sample map entries, therefore the two are combined when reading instead of the oscillator replacing the sample map. When writing, the volume and panning of a group are stored on its oscillator and only the remainder in its sample map, so they survive a Quantum/Iridium round-trip - previously the oscillator was always written as 0 dB and Center. The volume, gain and panning of a layer are applied on top of its oscillators when reading. The importer of the device copies only the samples which the first layer names, so the samples of a second layer are named in a map of the first layer as well, in entries which never play.
 
@@ -1029,7 +1029,7 @@ Since the device has a field of its own for the bank, a source which carries its
 * Author: Written into the preset's Author field, which the device shows and can group presets by. When left empty, the creator from the source metadata is kept (e.g. the sound designer stored in a SoundFont).
 * Bank: Written into the preset's Bank field. When left empty, the description from the source metadata is kept. Both the Author and the Bank only take as much text as the device shows completely: its *Load Patch* page shows the name, the bank and the author of the selected preset in a narrow column and leaves out every character which does not fit - e.g. of the bank 'Digital Collection Vintage' only 'Digital Collection Vinta' is visible. The font is proportional, so how many characters fit depends on the characters: on average 17 capital letters or 20 lower-case ones, but e.g. 11 of the letter 'm'. On the command line (QPATAuthor / QPATBank) a value which is too wide is reported, together with the part which the device would show, and nothing is converted.
 * Prefix file names with an import number: Prefixes each written preset file with a 5-digit number (e.g. *05002-Name.qpat*), which mirrors the naming of the device's own preset export; on import the device assigns the preset to that number. The *First import number* is used for the first written preset and each further preset increases the number by one; the source presets are converted in alphabetical order.
-* Use a second layer for more than 3 groups: A preset normally holds one layer with up to 3 multi-samples, one on each oscillator, and every further group of the source is merged into the third of them. With this option a source with more than 3 groups is written as 2 layers with up to 6 multi-samples, which keeps the groups apart and gives the second set of them its own filter and amplitude envelope. Two layers are stored the same way by every instrument of the family, so such a preset plays on a Quantum, an Iridium and an Iridium Core as well as on the MK2 generation. Only groups which sound at the same time are put into a separate layer - the device cannot select a layer by velocity, so a velocity split stays inside the sample maps. Disabled by default. Verified on an Iridium MK2: the written preset loads and its second layer carries its own filter and amplitude envelope. The device imports only the samples which the first layer names, so the samples of the second layer are named in the last sample map of the first layer as well, in entries which never play. Verified on an Iridium MK2 (OS 4.0.6): a test preset whose second layer brings a sample of its own plays both layers after the import, while the same preset without the entries fails to load that sample.
+* Maximum number of layers: A preset normally holds one layer with up to 3 multi-samples, one on each oscillator, and every further group of the source is merged into the third of them. With 2 layers a source with more than 3 groups is written as 2 layers with up to 6 multi-samples, which keeps the groups apart and gives the second set of them its own filter and amplitude envelope; with 3 or 4 layers a source with more than 6 groups is written with up to 9 or 12 multi-samples - 3 leaves the fourth layer of an MK2 free for a sound of your own. Only as many layers as the groups need are used. Two layers are stored the same way by every instrument of the family, so such a preset plays on a Quantum, an Iridium and an Iridium Core as well as on the MK2 generation; a preset with 3 or 4 layers uses the layout of the MK2 generation (format version 15, four stored layers of which the unused ones are switched off), which only the Iridium MK2, the Quantum MK2 and first-generation instruments upgraded with the MK2 hardware can play - the first generation holds two layers. Only groups which sound at the same time are put into a separate layer - the device cannot select a layer by velocity, so a velocity split stays inside the sample maps. The default is 1 layer. Verified on an Iridium MK2: a written 2-layer preset loads and its second layer carries its own filter and amplitude envelope. The device imports only the samples which the first layer names, so the samples of the later layers are named in the last sample map of the first layer as well, in entries which never play - verified on an Iridium MK2 (OS 4.0.6): a test preset whose second layer brings a sample of its own plays both layers after the import, while the same preset without the entries fails to load that sample. Verified on an Iridium MK2 (OS 4.0.6) as well: a written 4-layer preset with one sample pitch per layer plays all four pitches, and a 3-layer preset with its switched-off fourth layer plays its three.
 * Shorten file names to the displayed preset name: Names the written file after the preset name which the device displays instead of the full name of the source. A preset of a bank otherwise carries its bank in the file name (e.g. *05000-Full Arco String - Arco Strings Lo.qpat*, 45 characters), which is more than the import screen of the device shows - measured on an Iridium MK2, its file list displays about 43 characters and cuts off the rest, exactly the end that tells the presets apart. With this option the example becomes *05000-Arco Strings Lo.qpat*, and the whole file name - including the import number prefix and the file ending - is kept within 40 characters. Disabled by default, since the full name is what tells the presets of different banks apart in a file browser on the computer.
 * Options to write/update [WAV Chunk Information](#wav-chunk-information)
 

documentation/design/WALDORF_QPAT_FORMAT.md

@@ -750,7 +750,12 @@ brings a sample of its own plays both layers after the import, while the same pa
 entry fails with *loading samples/.../L2_saw_octave.wav failed*.
 
 A written two-layer patch loads and its second layer carries its own filter and amplitude envelope
-**(hw)**; the samples of the second layer were the open problem described above.
+**(hw)**; the samples of the second layer were the open problem described above. ConvertWithMoss
+writes the four-layer layout of the MK2 - count 2, version 15, four stored layers, the unused ones
+with `LayerActive` 0 and without oscillators - when a source needs three or four layers. Verified
+on an Iridium MK2 with OS 4.0.6 **(hw)**: a written four-layer patch with one sample pitch per
+layer plays all four pitches after the import, and a three-layer patch with its switched-off
+fourth layer plays its three.
 
 ## 8. Reading a patch
 
@@ -816,7 +821,12 @@ A written two-layer patch loads and its second layer carries its own filter and
   whether an MK2 can write code 1, and whether a first-generation instrument accepts code 2, is
   unknown. The loader accepts the codes 1, 2 and 3 as "more than one layer" and loads the layers 3
   and 4 for the codes 2 and 3 (fw). A written two-layer patch loads and, with the entries of
-  section 7.5, plays its own samples in the second layer (hw).
+  section 7.5, plays its own samples in the second layer; a written four-layer patch (count 2,
+  version 15) plays all four layers on an Iridium MK2 (hw). The first generation holds two layers -
+  the Iridium and Iridium Core manuals switch "between the two layers by tapping on the Layer 1 or
+  Layer 2 button", and Waldorf describes the MK2 upgrade as raising the layer count from 2 to 4 -
+  so a count-2 file is for the MK2 generation only; how a first-generation OS reacts to one is not
+  known (manual).
 * **Oscillator type indices.** *Off* is 5 in versions 9-11 and 6 in version 15; how an instrument
   interprets the index of a file of another version (e.g. a version-14 file with `Osc2Type` = 5 on
   an MK2) is untested - hence the advice to write nothing for unused oscillators.
@@ -870,7 +880,7 @@ For readers who want to compare an implementation against ConvertWithMoss (`Wald
   Experimental*).
 * **Options**: re-sample to 16 bit / 44.1 kHz (default on), *Author* and *Bank* overrides, the
   `NNNNN-` import number prefix with a configurable first number, short file names which keep the
-  whole file name within 40 characters, and *Use a second layer for more than 3 groups* (off by
-  default, which writes exactly what earlier versions wrote). It writes at most two layers - the
-  layer count 1, which every instrument of the family has stored since the format version 8 - and
-  never the four-layer count, which has only been seen in files of the version 15.
+  whole file name within 40 characters, and *Maximum number of layers* with 1 to 4 layers (1 by default,
+  which writes exactly what earlier versions wrote). One or two layers use the layer count 1, which
+  every instrument of the family has stored since the format version 8; three or four use the
+  four-layer layout of section 7.5 with the format version 15.