Kronos SW Developers - user-created 'programmers ref'
Posted: Sat Nov 17, 2012 6:26 pm
I am starting this thread to engage the community of Kronos owners who are also software developers. Sorry for the large post.
First, I must give Korg a lot of credit for providing the MIDI Implementation data, which is very useful and accurate in the areas that are covered. But if you have actually implemented software, you have probably found some details that are missing or confusing. I propose that we work together to develop a more comprehensive "Programmers Reference" for the Kronos.
At this point, I have personally only worked closely with the Combi (CombiAndSongTimbreSet.txt) and the Effects (Effect.txt) documentation. By making this a community effort we can all contribute what we learn from our individual “deep dives” into any particular area of the Kronos.
I have a few files to contribute to start the project. First is a spreadsheet that shows how the effects-specific parameter data fits into the Combi data structures. This data is represented as * in the Korg document. Although the largest number of bytes defined in any Kronos effect is currently 25, 64 bytes are reserved for the 12 IFXs and 2 each MFX and TFX. It took me a while to figure out how those 64 byte blocks fit into the * gaps in the Combi specification, since they appear to be different sizes. My file KronosCombiDataStructures.xlsx makes it clearer. On the 2nd tab there is a mapping of the offsets in the Combi file to the data structures within and their sizes. I have also included a set of data structures that correspond to the Combi. I used the spreadsheet to make sure my data structures matched exactly to the almost 8000 bytes in a Combi.
I can't guarantee everything is correct, but they are accurate enough to enable my program to convert Triton Studio Combis into Kronos Combis (except for the programs themselves and arpeggiator / Karma).
I have also explored parameters a bit. Many Combi parameters are defined in the CombiAndSongTimbreSet.txt (in the "TYP|SOC|SUB|PID|IDX" columns at the right). However, there are some that are missing. For example, the effects parameters are not documented.
In the process of turning the files like CombiAndSongTimbreSet.txt into data that I can use in my programs, I have developed some Perl scripts to parse those files. One parses the Effect.txt file and outputs CSV format (such as 1,0,8,7,0,"St. Amp Simulation","Amplifier Type","00~02","SS~6L6") that I can easily load (KorgKronosEffect.pl). I have also created one to parse out the parameter information (KorgParameterMapExtract.pl). These took a while to write and debug. If you need something like this, you are free to adapt them to your own purposes. Please upload your modifications so we can all benefit.
What is still needed to be done from the community, to better document the Kronos?
One important area is to understand and define the _meaning_ of parameters that are not simple integer types (like a 0-127 for volume). An example is Banks. The values 00..0x1E map to INT-A through U-GG. There are 14 banks, but the range is 0-30 decimal. How do they map? It turns out that banks are documented in KRONOS_MIDI_SysEx.txt, but many other enumerated types are not documented. Another example is frequency ranges used in the EFX. While some are simple integers, others use a varying step size of hertz/parameter unit to approximate an exponential mapping. Other than incrementing through all the values on the Kronos and observing the parameter change messages, I don't know how to determine mapping of parameter value to frequency. Even numeric values do not always map directly to the parameter value. LFO frequency, portamento or envelope times are examples when the parameter value has a relation to the actual value that is not a 1 to 1 mapping.
This would be an excellent area for those who have figured these things out to share your findings.
The area of the Programs is also wide open for contribution. Looking at Prog_HD-1.txt, there are a many data structures that are common to Combis, but some are not. Understanding the MS Bank UUId and MS Numbering formats would be very helpful information. The EXi definitions are also unexplored territory for me.
Above and beyond the MIDI implementation, there is also the PCG file format which (as far as I know) not officially documented. Michel Keijzers has obviously done a lot of work to figure that out, but I can't speak for him on whether his is able and willing to share any of the details.
I should point out that I'm not suggesting reverse engineering the internals of the Kronos - I'm not that "brave". This effort is about working with the provided interfaces (MIDI and supported files) and enabling developers to create software to augment the functionality. My hope is that if we work together we can spend more time developing our software’s features and functions (and thus improving the Kronos), and spend less time on figuring out the necessary details.
Also, I don't expect people to post their source code. The useful information to be shared is in the data structures, or even simple text files describing particular parameter mappings or file formats. If you can share those, regardless of the language you program in, others can put the information to use, and save us all a lot of time and effort. By posting in this forum, it becomes a resource for all to use and build on.
I have created a page for related files, including the ones I mentioned above. There is an email link on that page that you can use to provide additional files that I will upload (or PM me here).
What do you think? Is this worthwhile effort? Will you help?
First, I must give Korg a lot of credit for providing the MIDI Implementation data, which is very useful and accurate in the areas that are covered. But if you have actually implemented software, you have probably found some details that are missing or confusing. I propose that we work together to develop a more comprehensive "Programmers Reference" for the Kronos.
At this point, I have personally only worked closely with the Combi (CombiAndSongTimbreSet.txt) and the Effects (Effect.txt) documentation. By making this a community effort we can all contribute what we learn from our individual “deep dives” into any particular area of the Kronos.
I have a few files to contribute to start the project. First is a spreadsheet that shows how the effects-specific parameter data fits into the Combi data structures. This data is represented as * in the Korg document. Although the largest number of bytes defined in any Kronos effect is currently 25, 64 bytes are reserved for the 12 IFXs and 2 each MFX and TFX. It took me a while to figure out how those 64 byte blocks fit into the * gaps in the Combi specification, since they appear to be different sizes. My file KronosCombiDataStructures.xlsx makes it clearer. On the 2nd tab there is a mapping of the offsets in the Combi file to the data structures within and their sizes. I have also included a set of data structures that correspond to the Combi. I used the spreadsheet to make sure my data structures matched exactly to the almost 8000 bytes in a Combi.
I can't guarantee everything is correct, but they are accurate enough to enable my program to convert Triton Studio Combis into Kronos Combis (except for the programs themselves and arpeggiator / Karma).
I have also explored parameters a bit. Many Combi parameters are defined in the CombiAndSongTimbreSet.txt (in the "TYP|SOC|SUB|PID|IDX" columns at the right). However, there are some that are missing. For example, the effects parameters are not documented.
In the process of turning the files like CombiAndSongTimbreSet.txt into data that I can use in my programs, I have developed some Perl scripts to parse those files. One parses the Effect.txt file and outputs CSV format (such as 1,0,8,7,0,"St. Amp Simulation","Amplifier Type","00~02","SS~6L6") that I can easily load (KorgKronosEffect.pl). I have also created one to parse out the parameter information (KorgParameterMapExtract.pl). These took a while to write and debug. If you need something like this, you are free to adapt them to your own purposes. Please upload your modifications so we can all benefit.
What is still needed to be done from the community, to better document the Kronos?
One important area is to understand and define the _meaning_ of parameters that are not simple integer types (like a 0-127 for volume). An example is Banks. The values 00..0x1E map to INT-A through U-GG. There are 14 banks, but the range is 0-30 decimal. How do they map? It turns out that banks are documented in KRONOS_MIDI_SysEx.txt, but many other enumerated types are not documented. Another example is frequency ranges used in the EFX. While some are simple integers, others use a varying step size of hertz/parameter unit to approximate an exponential mapping. Other than incrementing through all the values on the Kronos and observing the parameter change messages, I don't know how to determine mapping of parameter value to frequency. Even numeric values do not always map directly to the parameter value. LFO frequency, portamento or envelope times are examples when the parameter value has a relation to the actual value that is not a 1 to 1 mapping.
This would be an excellent area for those who have figured these things out to share your findings.
The area of the Programs is also wide open for contribution. Looking at Prog_HD-1.txt, there are a many data structures that are common to Combis, but some are not. Understanding the MS Bank UUId and MS Numbering formats would be very helpful information. The EXi definitions are also unexplored territory for me.
Above and beyond the MIDI implementation, there is also the PCG file format which (as far as I know) not officially documented. Michel Keijzers has obviously done a lot of work to figure that out, but I can't speak for him on whether his is able and willing to share any of the details.
I should point out that I'm not suggesting reverse engineering the internals of the Kronos - I'm not that "brave". This effort is about working with the provided interfaces (MIDI and supported files) and enabling developers to create software to augment the functionality. My hope is that if we work together we can spend more time developing our software’s features and functions (and thus improving the Kronos), and spend less time on figuring out the necessary details.
Also, I don't expect people to post their source code. The useful information to be shared is in the data structures, or even simple text files describing particular parameter mappings or file formats. If you can share those, regardless of the language you program in, others can put the information to use, and save us all a lot of time and effort. By posting in this forum, it becomes a resource for all to use and build on.
I have created a page for related files, including the ones I mentioned above. There is an email link on that page that you can use to provide additional files that I will upload (or PM me here).
What do you think? Is this worthwhile effort? Will you help?
