1. Intro

This section will help you get to grips with the KORG SYRO library. It shows how the functions can be used to generate syrostream (the audio signal that the volca sample understands) from syrodata (the raw data you want to send - sample audio or sequence patterns).

Good luck and have fun!

2. what's inside the SDK?

syro : syro itself. It generates syrostream from syrodata.
example : examples using syro that creates a syro wav file from an audio sample
project : contains the project files to build the examples.
there is a visual studio 2010 project file and Makefile for gcc or clang.
pattern : definitions for pattern data structure and functions to initialize pattern data.
alldata : data for restoring factory preset samples or for deleting all sample data.

3. how to use the SDK to generate syrostream from syrodata

3.1 essential source files

korg_syro_volcasample.c
korg_syro_func.c
korg_syro_comp.c

add the following to call syro functions.

#include "korg_syro_volcasample.h"

3.2 outline of usage

prepare the data to be converted
call the conversion start function
process syrodata for each frame
call the conversion end function

Each step is explained in detail below.
Please refer to korg_syro_volcasample_example.c for a working example.

3.3a preparing the data to be converted

Both sample and sequence data can be converted.
You can also send a sample delete command.
It is possible to send multiple data in one operation.

Once you have the data you want to convert, set the necessary information in the SyroData structure.

SyroDataType DataType;
specifies any of the following data type to be converted.  
DataType_Sample_Compress        : convert single audio sample  
DataType_Sample_Erase           : delete single sample slot on volca sample  
DataType_Sample_AllCompress     : convert all sample data  
DataType_Pattern                : convert sequence pattern  

uint8_t *pData;
pointer which specifies the data to be converted.
not used when deleting samples.

uint32_t Number;
the sample (0-99) or sequence pattern (0-9) number.

uint32_t Size;
size of data to be converted (in bytes).
set it to sizeof(VolcaSample_Pattern_Data) when converting sequence data.
not used when deleting samples.

uint32_t Quality;
The conversion bit depth. It can be set to 8-16.
not used when deleting samples.

Endian SampleEndian;
set to LittleEndian or BigEndian to suite your sample data.
only used when converting single samples.

Only 16bit monaural audio samples are supported, so convert as necessary beforehand.
Only files with extension .alldata contained in folder 'alldata' can be used with all data conversion.

Lower bit depths will increase transfer speed at the cost of audio resolution.
The prepared audio must be 16bit regardless of this setting.
The sample is always stored at 16bit in the volca sample regardless of this value, so memory usage is not affected by this setting.

To send multiple data, create an array of SyroData structures and set the above information for each one. A maximum of 110 SyroData structures can be transferred in one operation.

3.3b calling the conversion start function

SyroStatus SyroVolcaSample_Start(
    SyroHandle *pHandle, 
    SyroData *pData, 
    int NumOfData,
        uint32_t Flags,
    uint32_t *pNumOfSyroFrame
);

The arguments are as follows:

SyroHandle *pHandle         [out]pointer of the handle(resource for proceeding conversions) accquired after calling this function.
SyroData *pData             [in]pointer of the SyroData structure prepared in 3.2
int NumOfData               [in]the number of data to be converted (number of SyroData that has been prepared)
uint32_t Flags              [in]a flag to be used during conversion. It is currently not used so set to 0.
uint32_t *pNumOfSyroFrame   [out]the pointer of the value which stores the size of the SyroData after conversion
                                Units in frames (an LR pair is one unit)

After successful conversion, Status_Success is returned.
Once this function is called, you must call SyroVolcaSample_End to finish or terminate.

Refer to error codes in 3.4 in case of failure.

3.3c process SyroData per frame

Call the SyroVolcaSample_GetSample function

SyroStatus SyroVolcaSample_GetSample(
    SyroHandle Handle, 
    int16_t *pLeft, 
    int16_t *pRight
);

The arguments are as follows:

SyroHandle Handle           the handle obtained at step 3.3b
int16_t *pLeft              the pointer of an array which is about to store L channel output sample data
int16_t *pRight             the pointer of an array which is about to store R channel output sample data

Store the obtained sample data as a wav file or output to an audio device.
Repeat this for pNumOfSyroFrame times, set at step 3.3b.

3.3d calling the conversion end function

When you have generated all sample data and/or want to terminate the conversion, call the function:

SyroStatus SyroVolcaSample_End(SyroHandle Handle)

Use the Handle obtained at step 3.3a.

3.4 About the returned value (SyroStatus)

Status_Success will be returned after successful conversion. Otherwise the following error code will be returned

Status_IllegalDataType      an illegal data type has been specified. Must specify SyroDataType.
Status_IllegalData          the data specified is abnormal
Status_IllegalParameter     the number of data specified at SyroVolcaSample_Start is illegal (must be 1 - 110).
Status_OutOfRange_Number    the specifed sample or sequence number is out of range
                            (sample number must be 0~99, sequence number must be 0~9)
Status_OutOfRange_Quality   specified bit depth is out of range
                            (must be 8~16)
Status_NotEnoughMemory      not enough memory

Status_InvalidHandle        and invalid handle has been used
Status_NoData               there is no more data to be converted

4. using the example to generate syrostream

The sample source code in the “example” folder generates syrostream in wav format.

The VC2010 project and Makefile to build the sample source code is contained in the project folder.
To create a project using an IDE, use and build the C source code inside the “example” and “syro” folders.
To create an executable using command line or terminal, use Makefile inside the “project”.
Type “make” for building. Default compiler is set to gcc. To use clang, type “make CC=clang”.

To execute within the console type the following:

>korg_syro_volcasample_example "TargetFile.wav" "SourceFile1" "SourceFile2" ......

####korg_syro_volcasample_example

name of the sample executable file
this is assumed to be the same as the source file name, but is dependant on the build environment.

####TargetFile.wav

the name of the generated syrostream file.
set the extension here to .wav
when using spaces in the file name, always put in double quotes.

####SourceFile

specifies the data to be converted
the data type and number are also set here.
remember to double quote when using spaces.

the format is as follows:

    "x17c12:filename"
     TT~TT~T~~~~T~~~
     || || |    +-------    the file name to be converted
     || || |                not necessary when deleting samples
     || || +------------    use : as a seperater
     || ||                  necessary even when a file name is not specified
     || |+--------------    the bit depth of the conversion 8~16 bits. applicable only when converting samples
     || |                   assumes 16 bits if omitted
     || +---------------    lossless compression
     ||                     (it's lossless so always use it)
     |+-----------------    sets sample slot number (0~99) or sequence number (1~10)
     |                      do not specify when converting for all samples
     +------------------    sets type of data to be converted
                            s:sample
                            e:erase sample
                            p:sequence pattern
                            a:all sample
                            only 16bit mono wav samples are supported

examples:

"s20c:kick.wav"                 converts kick.wav to be transfered to sample slot 20
"s57c12:snare.wav"              converts snare.wav to be transfered to sample slot 57 at a quality of 12bits
"e27:"                          generates syro stream to erase sample slot 27
"p01:pattern1.dat"              converts pattern1.dat to be transfered to sequence 1
"ac:volcasample_preset.alldata" converts volcasmple_preset.alldata to overwrite all samples

Multiples of these can be written in succession.
example:

"s0c:kick1.wav" "s1c:snare1.wav" converts kick1.wav to be transfered to sample slot 0 and snare1.wav to be transfered to sample slot 1.

5. Pattern data structure

SYRO for volca sample can convert sequence data as well.
Here, we explain the structure of the sequence pattern data.

The structure is defined in VolcaSample_PatternData in volcasample_pattern.h.
Always use little endian when storing 16 or 32 bit values.
Reserved and Padding member names do not have meaning so their explanations are omitted.

uint32_t Header;
uint16_t DevCode;

These are fields to specify that the data is pattern data for the volca sample.
set to 0x54535450 and 0x33b8.
(These are also defined as VOLCASAMPLE_PATTERN_HEADER、VOLCASAMPLE_PATTERN_DEVCODE)

uint16_t ActiveStep;

Sets active step on/off as a bitmap
steps 1~16 correspond t

Volcasample

Install / Use

README