Sequential Prophet X: read and write the sample instruments (GRP, ZIP)

documentation/CHANGELOG.md

@@ -5,6 +5,7 @@
 * Many thanks to Douglas Carmichael for plenty of contributions and fixes!
 * New: Added support for the E-mu Emulator (1981), the first Emulator (HFE, EMUFD, IMG). Written disks are not yet verified on hardware.
 * New: Added support for the E-mu Emax and Emax II (EM1, EB1, EM2, EB2, EM1FD, EM2FD, EZ1, EZ2, IMG, ISO, HFE). Written banks are not yet verified on hardware.
+* New: Added support for the sample instruments of the Sequential Prophet X / XL (GRP, ZIP): the instrument folders with their group file and the ZIP archives which the device imports from a USB drive, as written by the mapping utility of 8Dio and by PXToolkit. Reading was verified on a third-party sample pack; written instruments follow the same conventions but are not yet verified on hardware.
 * New: If no category could be detected, another attempt is made by using all group and zone names.
 * Fixed: The main window had a minimum size of 1280x840 pixels and therefore did not fit onto smaller screens like the 1366x768 pixels of many laptops - it opened larger than the screen and could not be made smaller. The minimum and the initial size of the window are now limited to the visible area of the screen.
 * Fixed: 32-bit float samples (e.g. the WAV files which DirectWave writes) were always converted to 16 bit, even though the log announced the 24 bit of the destination format. A float sample is now converted to the highest resolution the destination supports - 24 bit for e.g. SoundFont 2, Bliss, Tonverk, DirectWave and FLAC, 32 bit for ALAC - and keeps its float format for destinations without a restriction, e.g. when only the chunks of a WAV file are updated.

documentation/README-FORMATS.md

@@ -91,6 +91,7 @@ The following multi-sample formats are supported:
 * [Roland SP-404MK2](#roland-sp-404mk2)
 * [Roland ZEN-Core](#roland-zen-core)
 * [Sample files (AIFF, CAF, FLAC, NCW, OGG, WAV)](#sample-files-aiff-caf-flac-ncw-ogg-wav)
+* [Sequential Prophet X](#sequential-prophet-x)
 * [SFZ](#sfz)
 * [SoundFont 2](#soundfont-2)
 * [Spectrasonics Omnisphere 3](#spectrasonics-omnisphere-3)
@@ -864,6 +865,20 @@ WAV file can contain different sample formats. This converter supports (split) s
 
 * Audio file format: The format of the written sample files: WAV, AIFF, CAF, CAF-ALAC (CAF compressed with Apple Lossless), CAF-AAC (lossy) or FLAC.
 
+## Sequential Prophet X
+
+The Prophet X and Prophet XL are hybrid synthesizers from Sequential whose sample engine plays multi-sampled instruments. An instrument is a folder which contains its samples as WAV files and a *group file* (ending *.grp*): a tab-separated table with a header line and one line per sample - the file name, the key and velocity range, the loop, the number in a round robin set, the frequency at which the sample sounds and whether it tracks the keyboard. An optional *Volume.txt* next to it holds one gain factor per velocity. The device imports such instruments from a USB drive as ZIP archives which lie in the folder *px/<user bank>/<category>/*, e.g. *px/u00/15 Synth/Rhodes.zip*, which is the layout that the official mapping utility of 8Dio creates. Sequential does not document the format; it was reverse-engineered from the OS 2.2.2 firmware, see *documentation/design/PROPHET_X_GRP_FORMAT.md*.
+
+Reading takes both plain instrument folders (via their group file) and the import archives, including those which the free *PXToolkit* writes; the empty samples with which that tool keeps unmapped keys silent are skipped. Each line becomes a zone with its key range, velocity range, loop, root key and fine tuning (both from the frequency), key tracking (a *Mono Pitch* sample plays untransposed on every key) and its round robin number, which puts the samples of a set into groups that play in turn. The category comes from the category folder in which the instrument lies, or from the *Category* column if it lies in none, and the name from the *Instrument Name* column. The velocity volumes of *Volume.txt* are fitted to the amplitude velocity modulation (depth and curve); without the file the device uses its built-in curve, which is left to the defaults.
+
+Writing creates, by default, the import archive in the USB layout: copy the *px* folder onto a USB drive which was formatted by the device, insert it into the sample import port, set *Update Library* in the Global menu to *User* and press *Update Now*. The folder *u00* is the user bank 1 on the device, *u07* the bank 8. Keys which no zone covers are mapped to an empty sample, as PXToolkit does, since the device otherwise plays the nearest zone on them. Names are reduced to ASCII, which is all the display of the device shows, and the sample files carry only their format and data chunk. The category is the closest one of the 17 categories of the device to the category of the source, unless one is selected. The samples are written as 16 bit / 48 kHz WAV files: the device ignores the sample rate of a file and plays everything at 48 kHz, so any other rate would sound transposed. A zone with a play range is cut to it, since the format has no play range. Only the first loop of a zone is written and always as a forward loop; a backwards or alternating loop and reversed playback are reported. Round robin and random zones get their number in their set and the device picks one of them at random; zones which trigger on release are skipped. The velocity response is written to *Volume.txt* if all zones share one which differs from the default of full, linear velocity. The mapping utility of the device allows at most 128 samples per instrument, more are reported but written. The device identifies an instrument by a UUID as well as by its name; the UUID is derived from the bank, the category and the name, so a source which is converted again gives the same instrument. Envelopes, filter and LFO settings are not part of an instrument on the device but of the program which plays it, so they are not written. When a Prophet X instrument is converted to a Prophet X instrument again, enable the flat output, otherwise the *px* folder of the source is recreated below the destination folder and the new *px* folder lands inside it. Reading was verified on the archives of a third-party sample pack; the written archives follow the conventions of PXToolkit, whose archives play on the device, but are not yet verified on hardware themselves.
+
+### Destination Options
+
+* Category: The category of the device in which to store the instrument. *From the source* takes the closest one to the category of the source.
+* User bank: The user bank (u00 to u31) of the device in which to store the instrument.
+* Write the import archive: If enabled, the instrument is written as *px/<bank>/<category>/<name>.zip*, ready to be imported from a USB drive. If disabled, a plain folder with the group file and the samples is written instead.
+
 ## SFZ
 
 "The SFZ format is a file format to define how a collection of samples are arranged for performance. The goal behind the SFZ format is to provide a free, simple, minimalistic and expandable format to arrange, distribute and use audio samples with the highest possible quality and the highest possible performance flexibility" (cited from https://sfzformat.com/).