Merge branch 'master' into stable

1 files changed, 978 insertions, 225 deletions

diff --git a/include/adlmidi.h b/include/adlmidi.h
index a1289a0..6ae184e 100644
--- a/include/adlmidi.h
+++ b/include/adlmidi.h
@@ -55,398 +55,1151 @@ typedef char            ADL_SInt8;
 typedef short           ADL_SInt16;
 #endif
 
+/* == Deprecated function markers == */
+
+#if defined(_MSC_VER) /* MSVC */
+#   if _MSC_VER >= 1500 /* MSVC 2008 */
+                     /*! Indicates that the following function is deprecated. */
+#       define ADLMIDI_DEPRECATED(message) __declspec(deprecated(message))
+#   endif
+#endif /* defined(_MSC_VER) */
+
+#ifdef __clang__
+#   if __has_extension(attribute_deprecated_with_message)
+#       define JSONCPP_DEPRECATED(message) __attribute__((deprecated(message)))
+#   endif
+#elif defined __GNUC__ /* not clang (gcc comes later since clang emulates gcc) */
+#   if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5))
+#       define ADLMIDI_DEPRECATED(message) __attribute__((deprecated(message)))
+#   elif (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))
+#       define ADLMIDI_DEPRECATED(message) __attribute__((__deprecated__))
+#   endif /* GNUC version */
+#endif /* __clang__ || __GNUC__ */
+
+#if !defined(ADLMIDI_DEPRECATED)
+#   define ADLMIDI_DEPRECATED(message)
+#endif /* if !defined(ADLMIDI_DEPRECATED) */
+
+
+#ifdef ADLMIDI_BUILD
+#   ifndef ADLMIDI_DECLSPEC
+#       if defined (_WIN32) && defined(ADLMIDI_BUILD_DLL)
+#           define ADLMIDI_DECLSPEC __declspec(dllexport)
+#       else
+#           define ADLMIDI_DECLSPEC
+#       endif
+#   endif
+#else
+#   define ADLMIDI_DECLSPEC
+#endif
+
+
+/**
+ * @brief Volume scaling models
+ */
 enum ADLMIDI_VolumeModels
 {
+    /*! Automatical choice by the specific bank */
     ADLMIDI_VolumeModel_AUTO = 0,
+    /*! Linearized scaling model, most standard */
     ADLMIDI_VolumeModel_Generic = 1,
+    /*! Native OPL3's logarithmic volume scale */
     ADLMIDI_VolumeModel_NativeOPL3 = 2,
+    /*! Native OPL3's logarithmic volume scale. Alias. */
     ADLMIDI_VolumeModel_CMF = ADLMIDI_VolumeModel_NativeOPL3,
+    /*! Logarithmic volume scale, using volume map table. Used in DMX. */
     ADLMIDI_VolumeModel_DMX = 3,
+    /*! Logarithmic volume scale, used in Apogee Sound System. */
     ADLMIDI_VolumeModel_APOGEE = 4,
+    /*! Aproximated and shorted volume map table. Similar to general, but has less granularity. */
     ADLMIDI_VolumeModel_9X = 5
 };
 
+/**
+ * @brief Sound output format
+ */
 enum ADLMIDI_SampleType
 {
-    ADLMIDI_SampleType_S16 = 0,  /* signed PCM 16-bit */
-    ADLMIDI_SampleType_S8,       /* signed PCM 8-bit */
-    ADLMIDI_SampleType_F32,      /* float 32-bit */
-    ADLMIDI_SampleType_F64,      /* float 64-bit */
-    ADLMIDI_SampleType_S24,      /* signed PCM 24-bit */
-    ADLMIDI_SampleType_S32,      /* signed PCM 32-bit */
-    ADLMIDI_SampleType_U8,       /* unsigned PCM 8-bit */
-    ADLMIDI_SampleType_U16,      /* unsigned PCM 16-bit */
-    ADLMIDI_SampleType_U24,      /* unsigned PCM 24-bit */
-    ADLMIDI_SampleType_U32,      /* unsigned PCM 32-bit */
-    ADLMIDI_SampleType_Count,
+    /*! signed PCM 16-bit */
+    ADLMIDI_SampleType_S16 = 0,
+    /*! signed PCM 8-bit */
+    ADLMIDI_SampleType_S8,
+    /*! float 32-bit */
+    ADLMIDI_SampleType_F32,
+    /*! float 64-bit */
+    ADLMIDI_SampleType_F64,
+    /*! signed PCM 24-bit */
+    ADLMIDI_SampleType_S24,
+    /*! signed PCM 32-bit */
+    ADLMIDI_SampleType_S32,
+    /*! unsigned PCM 8-bit */
+    ADLMIDI_SampleType_U8,
+    /*! unsigned PCM 16-bit */
+    ADLMIDI_SampleType_U16,
+    /*! unsigned PCM 24-bit */
+    ADLMIDI_SampleType_U24,
+    /*! unsigned PCM 32-bit */
+    ADLMIDI_SampleType_U32,
+    /*! Count of available sample format types */
+    ADLMIDI_SampleType_Count
 };
 
+/**
+ * @brief Sound output format context
+ */
 struct ADLMIDI_AudioFormat
 {
-    enum ADLMIDI_SampleType type;  /* type of sample */
-    unsigned containerSize;        /* size in bytes of the storage type */
-    unsigned sampleOffset;         /* distance in bytes between consecutive samples */
+    /*! type of sample */
+    enum ADLMIDI_SampleType type;
+    /*! size in bytes of the storage type */
+    unsigned containerSize;
+    /*! distance in bytes between consecutive samples */
+    unsigned sampleOffset;
 };
 
+/**
+ * @brief Instance of the library
+ */
 struct ADL_MIDIPlayer
 {
+    /*! Private context descriptor */
     void *adl_midiPlayer;
 };
 
 /* DEPRECATED */
 #define adl_setNumCards adl_setNumChips
 
-/* Sets number of emulated chips (from 1 to 100). Emulation of multiple chips exchanges polyphony limits*/
-extern int adl_setNumChips(struct ADL_MIDIPlayer *device, int numChips);
+/**
+ * @brief Sets number of emulated chips (from 1 to 100). Emulation of multiple chips extends polyphony limits
+ * @param device Instance of the library
+ * @param numChips Count of virtual chips to emulate
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_setNumChips(struct ADL_MIDIPlayer *device, int numChips);
 
-/* Get current number of emulated chips */
-extern int adl_getNumChips(struct ADL_MIDIPlayer *device);
+/**
+ * @brief Get current number of emulated chips
+ * @param device Instance of the library
+ * @return Count of working chip emulators
+ */
+extern ADLMIDI_DECLSPEC int adl_getNumChips(struct ADL_MIDIPlayer *device);
 
-/* Sets a number of the patches bank from 0 to N banks. Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time. */
-extern int adl_setBank(struct ADL_MIDIPlayer *device, int bank);
+/**
+ * @brief Sets a number of the patches bank from 0 to N banks.
+ *
+ * Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time.
+ *
+ * @param device Instance of the library
+ * @param bank Number of embedded bank
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_setBank(struct ADL_MIDIPlayer *device, int bank);
 
-/* Returns total number of available banks */
-extern int adl_getBanksCount();
+/**
+ * @brief Returns total number of available banks
+ * @return Total number of available embedded banks
+ */
+extern ADLMIDI_DECLSPEC int adl_getBanksCount();
 
-/* Returns pointer to array of names of every bank */
-extern const char *const *adl_getBankNames();
+/**
+ * @brief Returns pointer to array of names of every bank
+ * @return Array of strings containing the name of every embedded bank
+ */
+extern ADLMIDI_DECLSPEC const char *const *adl_getBankNames();
 
-/* Reference to dynamic bank */
+/**
+ * @brief Reference to dynamic bank
+ */
 typedef struct ADL_Bank
 {
     void *pointer[3];
 } ADL_Bank;
 
-/* Identifier of dynamic bank */
+/**
+ * @brief Identifier of dynamic bank
+ */
 typedef struct ADL_BankId
 {
-    ADL_UInt8 percussive, msb, lsb;
+    /*! 0 if bank is melodic set, or 1 if bank is a percussion set */
+    ADL_UInt8 percussive;
+    /*! Assign to MSB bank number */
+    ADL_UInt8 msb;
+    /*! Assign to LSB bank number */
+    ADL_UInt8 lsb;
 } ADL_BankId;
 
-/* Flags for dynamic bank access */
+/**
+ * @brief Flags for dynamic bank access
+ */
 enum ADL_BankAccessFlags
 {
-    ADLMIDI_Bank_Create = 1,      /* create bank, allocating memory as needed */
-    ADLMIDI_Bank_CreateRt = 1|2,  /* create bank, never allocating memory */
+    /*! create bank, allocating memory as needed */
+    ADLMIDI_Bank_Create = 1,
+    /*! create bank, never allocating memory */
+    ADLMIDI_Bank_CreateRt = 1|2
 };
 
 typedef struct ADL_Instrument ADL_Instrument;
 
-#if defined(ADLMIDI_UNSTABLE_API)
-/* Preallocates a minimum number of bank slots. Returns the actual capacity. */
-extern int adl_reserveBanks(struct ADL_MIDIPlayer *device, unsigned banks);
-/* Gets the bank designated by the identifier, optionally creating if it does not exist. */
-extern int adl_getBank(struct ADL_MIDIPlayer *device, const ADL_BankId *id, int flags, ADL_Bank *bank);
-/* Gets the identifier of a bank. */
-extern int adl_getBankId(struct ADL_MIDIPlayer *device, const ADL_Bank *bank, ADL_BankId *id);
-/* Removes a bank. */
-extern int adl_removeBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank);
-/* Gets the first bank. */
-extern int adl_getFirstBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank);
-/* Iterates to the next bank. */
-extern int adl_getNextBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank);
-/* Gets the nth intrument in the bank [0..127]. */
-extern int adl_getInstrument(struct ADL_MIDIPlayer *device, const ADL_Bank *bank, unsigned index, ADL_Instrument *ins);
-/* Sets the nth intrument in the bank [0..127]. */
-extern int adl_setInstrument(struct ADL_MIDIPlayer *device, ADL_Bank *bank, unsigned index, const ADL_Instrument *ins);
-#endif /* defined(ADLMIDI_UNSTABLE_API) */
-
-/*Sets number of 4-operator channels between all chips.
-  By default, it is automatically re-calculating every bank change.
-  If you want to specify custom number of four operator channels,
-  please call this function after bank change (adl_setBank() or adl_openBank()),
-  otherwise, value will be overwritten by auto-calculated.*/
-extern int adl_setNumFourOpsChn(struct ADL_MIDIPlayer *device, int ops4);
-
-/*Get current total count of 4-operator channels between all chips*/
-extern int adl_getNumFourOpsChn(struct ADL_MIDIPlayer *device);
-
-/*Override Enable(1) or Disable(0) AdLib percussion mode. -1 - use bank default AdLib percussion mode*/
-extern void adl_setPercMode(struct ADL_MIDIPlayer *device, int percmod);
-
-/*Override Enable(1) or Disable(0) deep vibrato state. -1 - use bank default vibrato state*/
-extern void adl_setHVibrato(struct ADL_MIDIPlayer *device, int hvibro);
-
-/*Override Enable(1) or Disable(0) deep tremolo state. -1 - use bank default tremolo state*/
-extern void adl_setHTremolo(struct ADL_MIDIPlayer *device, int htremo);
-
-/*Override Enable(1) or Disable(0) scaling of modulator volumes. -1 - use bank default scaling of modulator volumes*/
-extern void adl_setScaleModulators(struct ADL_MIDIPlayer *device, int smod);
-
-/*Enable(1) or Disable(0) full-range brightness (MIDI CC74 used in XG music to filter result sounding) scaling.
-    By default, brightness affects sound between 0 and 64.
-    When this option is enabled, the range will use a full range from 0 up to 127.
-*/
-extern void adl_setFullRangeBrightness(struct ADL_MIDIPlayer *device, int fr_brightness);
-
-/*Enable or disable built-in loop (built-in loop supports 'loopStart' and 'loopEnd' tags to loop specific part)*/
-extern void adl_setLoopEnabled(struct ADL_MIDIPlayer *device, int loopEn);
-
-/* !!!DEPRECATED!!! Enable or disable Logariphmic volume changer */
-extern void adl_setLogarithmicVolumes(struct ADL_MIDIPlayer *device, int logvol);
-
-/*Set different volume range model */
-extern void adl_setVolumeRangeModel(struct ADL_MIDIPlayer *device, int volumeModel);
-
-/*Load WOPL bank file from File System. Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time.*/
-extern int adl_openBankFile(struct ADL_MIDIPlayer *device, const char *filePath);
-
-/*Load WOPL bank file from memory data*/
-extern int adl_openBankData(struct ADL_MIDIPlayer *device, const void *mem, unsigned long size);
 
 
-/* DEPRECATED */
-extern const char *adl_emulatorName();
 
-/*Returns chip emulator name string*/
-extern const char *adl_chipEmulatorName(struct ADL_MIDIPlayer *device);
+/* ======== Setup ======== */
+
+/**
+ * @brief Preallocates a minimum number of bank slots. Returns the actual capacity
+ * @param device Instance of the library
+ * @param banks Count of bank slots to pre-allocate.
+ * @return actual capacity of reserved bank slots.
+ */
+extern ADLMIDI_DECLSPEC int adl_reserveBanks(struct ADL_MIDIPlayer *device, unsigned banks);
+/**
+ * @brief Gets the bank designated by the identifier, optionally creating if it does not exist
+ * @param device Instance of the library
+ * @param id Identifier of dynamic bank
+ * @param flags Flags for dynamic bank access (ADL_BankAccessFlags)
+ * @param bank Reference to dynamic bank
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_getBank(struct ADL_MIDIPlayer *device, const ADL_BankId *id, int flags, ADL_Bank *bank);
+/**
+ * @brief Gets the identifier of a bank
+ * @param device Instance of the library
+ * @param bank Reference to dynamic bank.
+ * @param id Identifier of dynamic bank
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_getBankId(struct ADL_MIDIPlayer *device, const ADL_Bank *bank, ADL_BankId *id);
+/**
+ * @brief Removes a bank
+ * @param device Instance of the library
+ * @param bank Reference to dynamic bank
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_removeBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank);
+/**
+ * @brief Gets the first bank
+ * @param device Instance of the library
+ * @param bank Reference to dynamic bank
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_getFirstBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank);
+/**
+ * @brief Iterates to the next bank
+ * @param device Instance of the library
+ * @param bank Reference to dynamic bank
+ * @return 0 on success, <0 when any error has occurred or end has been reached.
+ */
+extern ADLMIDI_DECLSPEC int adl_getNextBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank);
+/**
+ * @brief Gets the nth intrument in the bank [0..127]
+ * @param device Instance of the library
+ * @param bank Reference to dynamic bank
+ * @param index Index of the instrument
+ * @param ins Instrument entry
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_getInstrument(struct ADL_MIDIPlayer *device, const ADL_Bank *bank, unsigned index, ADL_Instrument *ins);
+/**
+ * @brief Sets the nth intrument in the bank [0..127]
+ * @param device Instance of the library
+ * @param bank Reference to dynamic bank
+ * @param index Index of the instrument
+ * @param ins Instrument structure pointer
+ * @return 0 on success, <0 when any error has occurred
+ *
+ * This function allows to override an instrument on the fly
+ */
+extern ADLMIDI_DECLSPEC int adl_setInstrument(struct ADL_MIDIPlayer *device, ADL_Bank *bank, unsigned index, const ADL_Instrument *ins);
+/**
+ * @brief Loads the melodic or percussive part of the nth embedded bank
+ * @param device Instance of the library
+ * @param bank Reference to dynamic bank
+ * @param num Number of embedded bank to load into the current bank array
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_loadEmbeddedBank(struct ADL_MIDIPlayer *device, ADL_Bank *bank, int num);
+
+
+
+/**
+ * @brief Sets number of 4-operator channels between all chips
+ *
+ * By default, it is automatically re-calculating every bank change.
+ * If you want to specify custom number of four operator channels,
+ * please call this function after bank change (adl_setBank() or adl_openBank()),
+ * otherwise, value will be overwritten by auto-calculated.
+ *
+ * @param device Instance of the library
+ * @param ops4 Count of four-op channels to allocate between all emulating chips
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_setNumFourOpsChn(struct ADL_MIDIPlayer *device, int ops4);
+
+/**
+ * @brief Get current total count of 4-operator channels between all chips
+ * @param device Instance of the library
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_getNumFourOpsChn(struct ADL_MIDIPlayer *device);
+
+/**
+ * @brief Override Enable(1) or Disable(0) AdLib percussion mode. -1 - use bank default AdLib percussion mode
+ *
+ * This function forces rhythm-mode on any bank. The result will work glitchy.
+ *
+ * @param device Instance of the library
+ * @param percmod 0 - disabled, 1 - enabled
+ */
+extern ADLMIDI_DECLSPEC void adl_setPercMode(struct ADL_MIDIPlayer *device, int percmod);
+
+/**
+ * @brief Override Enable(1) or Disable(0) deep vibrato state. -1 - use bank default vibrato state
+ * @param device Instance of the library
+ * @param hvibro 0 - disabled, 1 - enabled
+ */
+extern ADLMIDI_DECLSPEC void adl_setHVibrato(struct ADL_MIDIPlayer *device, int hvibro);
+
+/**
+ * @brief Override Enable(1) or Disable(0) deep tremolo state. -1 - use bank default tremolo state
+ * @param device Instance of the library
+ * @param htremo 0 - disabled, 1 - enabled
+ */
+extern ADLMIDI_DECLSPEC void adl_setHTremolo(struct ADL_MIDIPlayer *device, int htremo);
+
+/**
+ * @brief Override Enable(1) or Disable(0) scaling of modulator volumes. -1 - use bank default scaling of modulator volumes
+ * @param device Instance of the library
+ * @param smod 0 - disabled, 1 - enabled
+ */
+extern ADLMIDI_DECLSPEC void adl_setScaleModulators(struct ADL_MIDIPlayer *device, int smod);
+
+/**
+ * @brief Enable(1) or Disable(0) full-range brightness (MIDI CC74 used in XG music to filter result sounding) scaling
+ *
+ * By default, brightness affects sound between 0 and 64.
+ * When this option is enabled, the brightness will use full range from 0 up to 127.
+ *
+ * @param device Instance of the library
+ * @param fr_brightness 0 - disabled, 1 - enabled
+ */
+extern ADLMIDI_DECLSPEC void adl_setFullRangeBrightness(struct ADL_MIDIPlayer *device, int fr_brightness);
+
+/**
+ * @brief Enable or disable built-in loop (built-in loop supports 'loopStart' and 'loopEnd' tags to loop specific part)
+ * @param device Instance of the library
+ * @param loopEn 0 - disabled, 1 - enabled
+ */
+extern ADLMIDI_DECLSPEC void adl_setLoopEnabled(struct ADL_MIDIPlayer *device, int loopEn);
+
+/**
+ * @brief Enable or disable soft panning with chip emulators
+ * @param device Instance of the library
+ * @param softPanEn 0 - disabled, 1 - enabled
+ */
+extern ADLMIDI_DECLSPEC void adl_setSoftPanEnabled(struct ADL_MIDIPlayer *device, int softPanEn);
+
+/**
+ * @brief [DEPRECATED] Enable or disable Logarithmic volume changer
+ *
+ * This function is deprecated. Suggested replacement: `adl_setVolumeRangeModel` with `ADLMIDI_VolumeModel_NativeOPL3` volume model value;
+ */
+ADLMIDI_DEPRECATED("Use `adl_setVolumeRangeModel(device, ADLMIDI_VolumeModel_NativeOPL3)` instead")
+extern ADLMIDI_DECLSPEC void adl_setLogarithmicVolumes(struct ADL_MIDIPlayer *device, int logvol);
+
+/**
+ * @brief Set different volume range model
+ * @param device Instance of the library
+ * @param volumeModel Volume model type (#ADLMIDI_VolumeModels)
+ */
+extern ADLMIDI_DECLSPEC void adl_setVolumeRangeModel(struct ADL_MIDIPlayer *device, int volumeModel);
+
+/**
+ * @brief Load WOPL bank file from File System
+ *
+ * Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time.
+ *
+ * @param device Instance of the library
+ * @param filePath Absolute or relative path to the WOPL bank file. UTF8 encoding is required, even on Windows.
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_openBankFile(struct ADL_MIDIPlayer *device, const char *filePath);
+
+/**
+ * @brief Load WOPL bank file from memory data
+ *
+ * Is recommended to call adl_reset() to apply changes to already-loaded file player or real-time.
+ *
+ * @param device Instance of the library
+ * @param mem Pointer to memory block where is raw data of WOPL bank file is stored
+ * @param size Size of given memory block
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_openBankData(struct ADL_MIDIPlayer *device, const void *mem, unsigned long size);
 
+
+/**
+ * @brief [DEPRECATED] Dummy function
+ *
+ * This function is deprecated. Suggested replacement: `adl_chipEmulatorName`
+ *
+ * @return A string that contains a notice to use `adl_chipEmulatorName` instead of this function.
+ */
+ADLMIDI_DEPRECATED("Use `adl_chipEmulatorName(device)` instead")
+extern ADLMIDI_DECLSPEC const char *adl_emulatorName();
+
+/**
+ * @brief Returns chip emulator name string
+ * @param device Instance of the library
+ * @return Understandable name of current OPL3 emulator
+ */
+extern ADLMIDI_DECLSPEC const char *adl_chipEmulatorName(struct ADL_MIDIPlayer *device);
+
+/**
+ * @brief List of available OPL3 emulators
+ */
 enum ADL_Emulator
 {
+    /*! Nuked OPL3 v. 1.8 */
     ADLMIDI_EMU_NUKED = 0,
+    /*! Nuked OPL3 v. 1.7.4 */
     ADLMIDI_EMU_NUKED_174,
+    /*! DosBox */
     ADLMIDI_EMU_DOSBOX,
+    /*! Count instrument on the level */
     ADLMIDI_EMU_end
 };
 
-/* Switch the emulation core */
-extern int adl_switchEmulator(struct ADL_MIDIPlayer *device, int emulator);
-
+/**
+ * @brief Switch the emulation core
+ * @param device Instance of the library
+ * @param emulator Type of emulator (#ADL_Emulator)
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_switchEmulator(struct ADL_MIDIPlayer *device, int emulator);
 
+/**
+ * @brief Library version context
+ */
 typedef struct {
     ADL_UInt16 major;
     ADL_UInt16 minor;
     ADL_UInt16 patch;
 } ADL_Version;
 
-/*Run emulator with PCM rate to reduce CPU usage on slow devices. May decrease sounding accuracy.*/
-extern int adl_setRunAtPcmRate(struct ADL_MIDIPlayer *device, int enabled);
+/**
+ * @brief Run emulator with PCM rate to reduce CPU usage on slow devices.
+ *
+ * May decrease sounding accuracy on some chip emulators.
+ *
+ * @param device Instance of the library
+ * @param enabled 0 - disabled, 1 - enabled
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_setRunAtPcmRate(struct ADL_MIDIPlayer *device, int enabled);
 
-/*Returns string which contains a version number*/
-extern const char *adl_linkedLibraryVersion();
+/**
+ * @brief Set 4-bit device identifier. Used by the SysEx processor.
+ * @param device Instance of the library
+ * @param id 4-bit device identifier
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_setDeviceIdentifier(struct ADL_MIDIPlayer *device, unsigned id);
 
-/*Returns structure which contains a version number of library */
-extern const ADL_Version *adl_linkedVersion();
+/**
+ * @section Information
+ */
 
-/*Returns string which contains last error message of initialization*/
-extern const char *adl_errorString();
+/**
+ * @brief Returns string which contains a version number
+ * @return String which contains a version of the library
+ */
+extern ADLMIDI_DECLSPEC const char *adl_linkedLibraryVersion();
 
-/*Returns string which contains last error message on specific device*/
-extern const char *adl_errorInfo(struct ADL_MIDIPlayer *device);
+/**
+ * @brief Returns structure which contains a version number of library
+ * @return Library version context structure which contains version number of the library
+ */
+extern ADLMIDI_DECLSPEC const ADL_Version *adl_linkedVersion();
 
-/*Initialize ADLMIDI Player device*/
-extern struct ADL_MIDIPlayer *adl_init(long sample_rate);
 
-/*Set 4-bit device identifier*/
-extern int adl_setDeviceIdentifier(struct ADL_MIDIPlayer *device, unsigned id);
+/* ======== Error Info ======== */
 
-/*Load MIDI file from File System*/
-extern int adl_openFile(struct ADL_MIDIPlayer *device, const char *filePath);
+/**
+ * @brief Returns string which contains last error message of initialization
+ *
+ * Don't use this function to get info on any function except of `adl_init`!
+ * Use `adl_errorInfo()` to get error information while workflow
+ *
+ * @return String with error message related to library initialization
+ */
+extern ADLMIDI_DECLSPEC const char *adl_errorString();
 
-/*Load MIDI file from memory data*/
-extern int adl_openData(struct ADL_MIDIPlayer *device, const void *mem, unsigned long size);
+/**
+ * @brief Returns string which contains last error message on specific device
+ * @param device Instance of the library
+ * @return String with error message related to last function call returned non-zero value.
+ */
+extern ADLMIDI_DECLSPEC const char *adl_errorInfo(struct ADL_MIDIPlayer *device);
 
-/*Resets MIDI player*/
-extern void adl_reset(struct ADL_MIDIPlayer *device);
 
-/*Get total time length of current song*/
-extern double adl_totalTimeLength(struct ADL_MIDIPlayer *device);
 
-/*Get loop start time if presented. -1 means MIDI file has no loop points */
-extern double adl_loopStartTime(struct ADL_MIDIPlayer *device);
+/* ======== Initialization ======== */
 
-/*Get loop end time if presented. -1 means MIDI file has no loop points */
-extern double adl_loopEndTime(struct ADL_MIDIPlayer *device);
+/**
+ * @brief Initialize ADLMIDI Player device
+ *
+ * Tip 1: You can initialize multiple instances and run them in parallel
+ * Tip 2: Library is NOT thread-safe, therefore don't use same instance in different threads or use mutexes
+ * Tip 3: Changing of sample rate on the fly is not supported. Re-create the instance again.
+ *
+ * @param sample_rate Output sample rate
+ * @return Instance of the library. If NULL was returned, check the `adl_errorString` message for more info.
+ */
+extern ADLMIDI_DECLSPEC struct ADL_MIDIPlayer *adl_init(long sample_rate);
 
-/*Get current time position in seconds*/
-extern double adl_positionTell(struct ADL_MIDIPlayer *device);
+/**
+ * @brief Close and delete ADLMIDI device
+ * @param device Instance of the library
+ */
+extern ADLMIDI_DECLSPEC void adl_close(struct ADL_MIDIPlayer *device);
 
-/*Jump to absolute time position in seconds*/
-extern void adl_positionSeek(struct ADL_MIDIPlayer *device, double seconds);
 
-/*Reset MIDI track position to begin */
-extern void adl_positionRewind(struct ADL_MIDIPlayer *device);
 
-/*Set tempo multiplier: 1.0 - original tempo, >1 - play faster, <1 - play slower */
-extern void adl_setTempo(struct ADL_MIDIPlayer *device, double tempo);
+/* ======== MIDI Sequencer ======== */
 
-/*Close and delete ADLMIDI device*/
-extern void adl_close(struct ADL_MIDIPlayer *device);
+/**
+ * @brief Load MIDI (or any other supported format) file from File System
+ *
+ * Available when library is built with built-in MIDI Sequencer support.
+ *
+ * @param device Instance of the library
+ * @param filePath Absolute or relative path to the music file. UTF8 encoding is required, even on Windows.
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_openFile(struct ADL_MIDIPlayer *device, const char *filePath);
 
+/**
+ * @brief Load MIDI (or any other supported format) file from memory data
+ *
+ * Available when library is built with built-in MIDI Sequencer support.
+ *
+ * @param device Instance of the library
+ * @param mem Pointer to memory block where is raw data of music file is stored
+ * @param size Size of given memory block
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_openData(struct ADL_MIDIPlayer *device, const void *mem, unsigned long size);
 
+/**
+ * @brief Resets MIDI player (per-channel setup) into initial state
+ * @param device Instance of the library
+ */
+extern ADLMIDI_DECLSPEC void adl_reset(struct ADL_MIDIPlayer *device);
 
-/**META**/
+/**
+ * @brief Get total time length of current song
+ *
+ * Available when library is built with built-in MIDI Sequencer support.
+ *
+ * @param device Instance of the library
+ * @return Total song length in seconds
+ */
+extern ADLMIDI_DECLSPEC double adl_totalTimeLength(struct ADL_MIDIPlayer *device);
 
-/*Returns string which contains a music title*/
-extern const char *adl_metaMusicTitle(struct ADL_MIDIPlayer *device);
+/**
+ * @brief Get loop start time if presented.
+ *
+ * Available when library is built with built-in MIDI Sequencer support.
+ *
+ * @param device Instance of the library
+ * @return Time position in seconds of loop start point, or -1 when file has no loop points
+ */
+extern ADLMIDI_DECLSPEC double adl_loopStartTime(struct ADL_MIDIPlayer *device);
 
-/*Returns string which contains a copyright string*/
-extern const char *adl_metaMusicCopyright(struct ADL_MIDIPlayer *device);
+/**
+ * @brief Get loop endtime if presented.
+ *
+ * Available when library is built with built-in MIDI Sequencer support.
+ *
+ * @param device Instance of the library
+ * @return Time position in seconds of loop end point, or -1 when file has no loop points
+ */
+extern ADLMIDI_DECLSPEC double adl_loopEndTime(struct ADL_MIDIPlayer *device);
+
+/**
+ * @brief Get current time position in seconds
+ *
+ * Available when library is built with built-in MIDI Sequencer support.
+ *
+ * @param device Instance of the library
+ * @return Current time position in seconds
+ */
+extern ADLMIDI_DECLSPEC double adl_positionTell(struct ADL_MIDIPlayer *device);
+
+/**
+ * @brief Jump to absolute time position in seconds
+ *
+ * Available when library is built with built-in MIDI Sequencer support.
+ *
+ * @param device Instance of the library
+ * @param seconds Destination time position in seconds to seek
+ */
+extern ADLMIDI_DECLSPEC void adl_positionSeek(struct ADL_MIDIPlayer *device, double seconds);
+
+/**
+ * @brief Reset MIDI track position to begin
+ *
+ * Available when library is built with built-in MIDI Sequencer support.
+ *
+ * @param device Instance of the library
+ */
+extern ADLMIDI_DECLSPEC void adl_positionRewind(struct ADL_MIDIPlayer *device);
+
+/**
+ * @brief Set tempo multiplier
+ *
+ * Available when library is built with built-in MIDI Sequencer support.
+ *
+ * @param device Instance of the library
+ * @param tempo Tempo multiplier value: 1.0 - original tempo, >1 - play faster, <1 - play slower
+ */
+extern ADLMIDI_DECLSPEC void adl_setTempo(struct ADL_MIDIPlayer *device, double tempo);
+
+/**
+ * @brief Returns 1 if music position has reached end
+ * @param device Instance of the library
+ * @return 1 when end of sing has been reached, otherwise, 0 will be returned. <0 is returned on any error
+ */
+extern ADLMIDI_DECLSPEC int adl_atEnd(struct ADL_MIDIPlayer *device);
+
+/**
+ * @brief Returns the number of tracks of the current sequence
+ * @param device Instance of the library
+ * @return Count of tracks in the current sequence
+ */
+extern ADLMIDI_DECLSPEC size_t adl_trackCount(struct ADL_MIDIPlayer *device);
+
+/**
+ * @brief Track options
+ */
+enum ADLMIDI_TrackOptions
+{
+    /*! Enabled track */
+    ADLMIDI_TrackOption_On   = 1,
+    /*! Disabled track */
+    ADLMIDI_TrackOption_Off  = 2,
+    /*! Solo track */
+    ADLMIDI_TrackOption_Solo = 3
+};
+
+/**
+ * @brief Sets options on a track of the current sequence
+ * @param device Instance of the library
+ * @param trackNumber Identifier of the designated track.
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_setTrackOptions(struct ADL_MIDIPlayer *device, size_t trackNumber, unsigned trackOptions);
+
+/**
+ * @brief Handler of callback trigger events
+ * @param userData Pointer to user data (usually, context of something)
+ * @param trigger Value of the event which triggered this callback.
+ * @param track Identifier of the track which triggered this callback.
+ */
+typedef ADLMIDI_DECLSPEC void (*ADL_TriggerHandler)(void *userData, unsigned trigger, size_t track);
+
+/**
+ * @brief Defines a handler for callback trigger events
+ * @param device Instance of the library
+ * @param handler Handler to invoke from the sequencer when triggered, or NULL.
+ * @param userData Instance of the library
+ * @return 0 on success, <0 when any error has occurred
+ */
+extern ADLMIDI_DECLSPEC int adl_setTriggerHandler(struct ADL_MIDIPlayer *device, ADL_TriggerHandler handler, void *userData);
 
-/*Returns count of available track titles: NOTE: there are CAN'T be associated with channel in any of event or note hooks */
-extern size_t adl_metaTrackTitleCount(struct ADL_MIDIPlayer *device);
 
-/*Get track title by index*/
-extern const char *adl_metaTrackTitle(struct ADL_MIDIPlayer *device, size_t index);
 
+
+/* ======== Meta-Tags ======== */
+
+/**
+ * @brief Returns string which contains a music title
+ * @param device Instance of the library
+ * @return A string that contains music title
+ */
+extern ADLMIDI_DECLSPEC const char *adl_metaMusicTitle(struct ADL_MIDIPlayer *device);
+
+/**
+ * @brief Returns string which contains a copyright string*
+ * @param device Instance of the library
+ * @return A string that contains copyright notice, otherwise NULL
+ */
+extern ADLMIDI_DECLSPEC const char *adl_metaMusicCopyright(struct ADL_MIDIPlayer *device);
+
+/**
+ * @brief Returns count of available track titles
+ *
+ * NOTE: There are CAN'T be associated with channel in any of event or note hooks
+ *
+ * @param device Instance of the library
+ * @return Count of available MIDI tracks, otherwise NULL
+ */
+extern ADLMIDI_DECLSPEC size_t adl_metaTrackTitleCount(struct ADL_MIDIPlayer *device);
+
+/**
+ * @brief Get track title by index
+ * @param device Instance of the library
+ * @param index Index of the track to retreive the title
+ * @return A string that contains track title, otherwise NULL.
+ */
+extern ADLMIDI_DECLSPEC const char *adl_metaTrackTitle(struct ADL_MIDIPlayer *device, size_t index);
+
+/**
+ * @brief MIDI Marker structure
+ */
 struct Adl_MarkerEntry
 {
+    /*! MIDI Marker title */
     const char      *label;
+    /*! Absolute time position of the marker in seconds */
     double          pos_time;
+    /*! Absolute time position of the marker in MIDI ticks */
     unsigned long   pos_ticks;
 };
 
-/*Returns count of available markers*/
-extern size_t adl_metaMarkerCount(struct ADL_MIDIPlayer *device);
+/**
+ * @brief Returns count of available markers
+ * @param device Instance of the library
+ * @return Count of available MIDI markers
+ */
+extern ADLMIDI_DECLSPEC size_t adl_metaMarkerCount(struct ADL_MIDIPlayer *device);
+
+/**
+ * @brief Returns the marker entry
+ * @param device Instance of the library
+ * @param index Index of the marker to retreive it.
+ * @return MIDI Marker description structure.
+ */
+extern ADLMIDI_DECLSPEC struct Adl_MarkerEntry adl_metaMarker(struct ADL_MIDIPlayer *device, size_t index);
+
 
-/*Returns the marker entry*/
-extern struct Adl_MarkerEntry adl_metaMarker(struct ADL_MIDIPlayer *device, size_t index);
 
 
-/*Take a sample buffer and iterate MIDI timers */
-extern int  adl_play(struct ADL_MIDIPlayer *device, int sampleCount, short *out);
+/* ======== Audio output Generation ======== */
 
-/*Take a sample buffer and iterate MIDI timers */
-extern int  adl_playFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_UInt8 *left, ADL_UInt8 *right, const struct ADLMIDI_AudioFormat *format);
+/**
+ * @brief Generate PCM signed 16-bit stereo audio output and iterate MIDI timers
+ *
+ * Use this function when you are playing MIDI file loaded by `adl_openFile` or by `adl_openData`
+ * with using of built-in MIDI sequencer.
+ *
+ * Don't use count of frames, use instead count of samples. One frame is two samples.
+ * So, for example, if you want to take 10 frames, you must to request amount of 20 samples!
+ *
+ * Available when library is built with built-in MIDI Sequencer support.
+ *
+ * @param device Instance of the library
+ * @param sampleCount Count of samples (not frames!)
+ * @param out Pointer to output with 16-bit stereo PCM output
+ * @return Count of given samples, otherwise, 0 or when catching an error while playing
+ */
+extern ADLMIDI_DECLSPEC int  adl_play(struct ADL_MIDIPlayer *device, int sampleCount, short *out);
 
-/*Generate audio output from chip emulators without iteration of MIDI timers.*/
-extern int  adl_generate(struct ADL_MIDIPlayer *device, int sampleCount, short *out);
+/**
+ * @brief Generate PCM stereo audio output in sample format declared by given context and iterate MIDI timers
+ *
+ * Use this function when you are playing MIDI file loaded by `adl_openFile` or by `adl_openData`
+ * with using of built-in MIDI sequencer.
+ *
+ * Don't use count of frames, use instead count of samples. One frame is two samples.
+ * So, for example, if you want to take 10 frames, you must to request amount of 20 samples!
+ *
+ * Available when library is built with built-in MIDI Sequencer support.
+ *
+ * @param device Instance of the library
+ * @param sampleCount Count of samples (not frames!)
+ * @param left Left channel buffer output (Must be casted into bytes array)
+ * @param right Right channel buffer output (Must be casted into bytes array)
+ * @param format Destination PCM format format context
+ * @return Count of given samples, otherwise, 0 or when catching an error while playing
+ */
+extern ADLMIDI_DECLSPEC int  adl_playFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_UInt8 *left, ADL_UInt8 *right, const struct ADLMIDI_AudioFormat *format);
 
-/*Generate audio output from chip emulators without iteration of MIDI timers.*/
-extern int  adl_generateFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_UInt8 *left, ADL_UInt8 *right, const struct ADLMIDI_AudioFormat *format);
+/**
+ * @brief Generate PCM signed 16-bit stereo audio output without iteration of MIDI timers
+ *
+ * Use this function when you are using library as Real-Time MIDI synthesizer or with
+ * an external MIDI sequencer. You must to request the amount of samples which is equal
+ * to the delta between of MIDI event rows. One MIDI row is a group of MIDI events
+ * are having zero delta/delay between each other. When you are receiving events in
+ * real time, request the minimal possible delay value.
+ *
+ * Don't use count of frames, use instead count of samples. One frame is two samples.
+ * So, for example, if you want to take 10 frames, you must to request amount of 20 samples!
+ *
+ * @param device Instance of the library
+ * @param sampleCount
+ * @param out Pointer to output with 16-bit stereo PCM output
+ * @return Count of given samples, otherwise, 0 or when catching an error while playing
+ */
+extern ADLMIDI_DECLSPEC int  adl_generate(struct ADL_MIDIPlayer *device, int sampleCount, short *out);
+
+/**
+ * @brief Generate PCM stereo audio output in sample format declared by given context without iteration of MIDI timers
+ *
+ * Use this function when you are using library as Real-Time MIDI synthesizer or with
+ * an external MIDI sequencer. You must to request the amount of samples which is equal
+ * to the delta between of MIDI event rows. One MIDI row is a group of MIDI events
+ * are having zero delta/delay between each other. When you are receiving events in
+ * real time, request the minimal possible delay value.
+ *
+ * Don't use count of frames, use instead count of samples. One frame is two samples.
+ * So, for example, if you want to take 10 frames, you must to request amount of 20 samples!
+ *
+ * @param device Instance of the library
+ * @param sampleCount
+ * @param left Left channel buffer output (Must be casted into bytes array)
+ * @param right Right channel buffer output (Must be casted into bytes array)
+ * @param format Destination PCM format format context
+ * @return Count of given samples, otherwise, 0 or when catching an error while playing
+ */
+extern ADLMIDI_DECLSPEC int  adl_generateFormat(struct ADL_MIDIPlayer *device, int sampleCount, ADL_UInt8 *left, ADL_UInt8 *right, const struct ADLMIDI_AudioFormat *format);
 
 /**
  * @brief Periodic tick handler.
- * @param device
- * @param seconds seconds since last call
- * @param granularity don't expect intervals smaller than this, in seconds
- * @return desired number of seconds until next call
  *
- * Use it for Hardware OPL3 mode or when you want to process events differently from adl_play() function.
- * DON'T USE IT TOGETHER WITH adl_play()!!!
+ * Notice: The function is provided to use it with Hardware OPL3 mode or for the purpose to iterate
+ * MIDI playback without of sound generation.
+ *
+ * DON'T USE IT TOGETHER WITH adl_play() and adl_playFormat() calls
+ * as there are all using this function internally!!!
+ *
+ * @param device Instance of the library
+ * @param seconds Previous delay. On a first moment, pass the `0.0`
+ * @param granulality Minimal size of one MIDI tick in seconds.
+ * @return desired number of seconds until next call. Pass this value into `seconds` field in next time
  */
-extern double adl_tickEvents(struct ADL_MIDIPlayer *device, double seconds, double granuality);
+extern ADLMIDI_DECLSPEC double adl_tickEvents(struct ADL_MIDIPlayer *device, double seconds, double granulality);
 
-/*Returns 1 if music position has reached end*/
-extern int adl_atEnd(struct ADL_MIDIPlayer *device);
 
-/**RealTime**/
 
-/*Force Off all notes on all channels*/
-extern void adl_panic(struct ADL_MIDIPlayer *device);
 
-/*Reset states of all controllers on all MIDI channels*/
-extern void adl_rt_resetState(struct ADL_MIDIPlayer *device);
+/* ======== Real-Time MIDI ======== */
 
-/*Turn specific MIDI note ON*/
-extern int adl_rt_noteOn(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note, ADL_UInt8 velocity);
+/**
+ * @brief Force Off all notes on all channels
+ * @param device Instance of the library
+ */
+extern ADLMIDI_DECLSPEC void adl_panic(struct ADL_MIDIPlayer *device);
 
-/*Turn specific MIDI note OFF*/
-extern void adl_rt_noteOff(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note);
+/**
+ * @brief Reset states of all controllers on all MIDI channels
+ * @param device Instance of the library
+ */
+extern ADLMIDI_DECLSPEC void adl_rt_resetState(struct ADL_MIDIPlayer *device);
 
-/*Set note after-touch*/
-extern void adl_rt_noteAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note, ADL_UInt8 atVal);
-/*Set channel after-touch*/
-extern void adl_rt_channelAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 atVal);
+/**
+ * @brief Turn specific MIDI note ON
+ * @param device Instance of the library
+ * @param channel Target MIDI channel [Between 0 and 16]
+ * @param note Note number to on [Between 0 and 127]
+ * @param velocity Velocity level [Between 0 and 127]
+ * @return 1 when note was successfully started, 0 when note was rejected by any reason.
+ */
+extern ADLMIDI_DECLSPEC int adl_rt_noteOn(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note, ADL_UInt8 velocity);
 
-/*Apply controller change*/
-extern void adl_rt_controllerChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 type, ADL_UInt8 value);
+/**
+ * @brief Turn specific MIDI note OFF
+ * @param device Instance of the library
+ * @param channel Target MIDI channel [Between 0 and 16]
+ * @param note Note number to off [Between 0 and 127]
+ */
+extern ADLMIDI_DECLSPEC void adl_rt_noteOff(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note);
 
-/*Apply patch change*/
-extern void adl_rt_patchChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 patch);
+/**
+ * @brief Set note after-touch
+ * @param device Instance of the library
+ * @param channel Target MIDI channel [Between 0 and 16]
+ * @param note Note number to affect by aftertouch event [Between 0 and 127]
+ * @param atVal After-Touch value [Between 0 and 127]
+ */
+extern ADLMIDI_DECLSPEC void adl_rt_noteAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 note, ADL_UInt8 atVal);
 
-/*Apply pitch bend change*/
-extern void adl_rt_pitchBend(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt16 pitch);
-/*Apply pitch bend change*/
-extern void adl_rt_pitchBendML(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 msb, ADL_UInt8 lsb);
+/**
+ * @brief Set channel after-touch
+ * @param device Instance of the library
+ * @param channel Target MIDI channel [Between 0 and 16]
+ * @param atVal After-Touch level [Between 0 and 127]
+ */
+extern ADLMIDI_DECLSPEC void adl_rt_channelAfterTouch(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 atVal);
 
-/*Change LSB of the bank*/
-extern void adl_rt_bankChangeLSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 lsb);
-/*Change MSB of the bank*/
-extern void adl_rt_bankChangeMSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 msb);
-/*Change bank by absolute signed value*/
-extern void adl_rt_bankChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_SInt16 bank);
+/**
+ * @brief Apply controller change
+ * @param device Instance of the library
+ * @param channel Target MIDI channel [Between 0 and 16]
+ * @param type Type of the controller [Between 0 and 255]
+ * @param value Value of the controller event [Between 0 and 127]
+ */
+extern ADLMIDI_DECLSPEC void adl_rt_controllerChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 type, ADL_UInt8 value);
+
+/**
+ * @brief Apply patch change
+ * @param device Instance of the library
+ * @param channel Target MIDI channel [Between 0 and 16]
+ * @param patch Patch number [Between 0 and 127]
+ */
+extern ADLMIDI_DECLSPEC void adl_rt_patchChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 patch);
+
+/**
+ * @brief Apply pitch bend change
+ * @param device Instance of the library
+ * @param channel Target MIDI channel [Between 0 and 16]
+ * @param pitch 24-bit pitch bend value
+ */
+extern ADLMIDI_DECLSPEC void adl_rt_pitchBend(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt16 pitch);
+
+/**
+ * @brief Apply pitch bend change
+ * @param device Instance of the library
+ * @param channel Target MIDI channel [Between 0 and 16]
+ * @param msb MSB part of 24-bit pitch bend value
+ * @param lsb LSB part of 24-bit pitch bend value
+ */
+extern ADLMIDI_DECLSPEC void adl_rt_pitchBendML(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 msb, ADL_UInt8 lsb);
 
-/*Perform a system exclusive message*/
-extern int adl_rt_systemExclusive(struct ADL_MIDIPlayer *device, const ADL_UInt8 *msg, size_t size);
+/**
+ * @brief Change LSB of the bank number (Alias to CC-32 event)
+ * @param device Instance of the library
+ * @param channel Target MIDI channel [Between 0 and 16]
+ * @param lsb LSB value of the MIDI bank number
+ */
+extern ADLMIDI_DECLSPEC void adl_rt_bankChangeLSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 lsb);
+
+/**
+ * @brief Change MSB of the bank (Alias to CC-0 event)
+ * @param device Instance of the library
+ * @param channel Target MIDI channel [Between 0 and 16]
+ * @param msb MSB value of the MIDI bank number
+ */
+extern ADLMIDI_DECLSPEC void adl_rt_bankChangeMSB(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_UInt8 msb);
 
+/**
+ * @brief Change bank by absolute signed value
+ * @param device Instance of the library
+ * @param channel Target MIDI channel [Between 0 and 16]
+ * @param bank Bank number as concoctated signed 16-bit value of MSB and LSB parts.
+ */
+
+extern ADLMIDI_DECLSPEC void adl_rt_bankChange(struct ADL_MIDIPlayer *device, ADL_UInt8 channel, ADL_SInt16 bank);
 
-/**Hooks**/
+/**
+ * @brief Perform a system exclusive message
+ * @param device Instance of the library
+ * @param msg Raw SysEx message buffer (must begin with 0xF0 and end with 0xF7)
+ * @param size Size of given SysEx message buffer
+ * @return 1 when SysEx message was successfully processed, 0 when SysEx message was rejected by any reason
+ */
+extern ADLMIDI_DECLSPEC int adl_rt_systemExclusive(struct ADL_MIDIPlayer *device, const ADL_UInt8 *msg, size_t size);
 
+
+
+
+/* ======== Hooks and debugging ======== */
+
+/**
+ * @brief Raw event callback
+ * @param userdata Pointer to user data (usually, context of someting)
+ * @param type MIDI event type
+ * @param subtype MIDI event sub-type (special events only)
+ * @param channel MIDI channel
+ * @param data Raw event data
+ * @param len Length of event data
+ */
 typedef void (*ADL_RawEventHook)(void *userdata, ADL_UInt8 type, ADL_UInt8 subtype, ADL_UInt8 channel, const ADL_UInt8 *data, size_t len);
+
+/**
+ * @brief Note on/off callback
+ * @param userdata Pointer to user data (usually, context of someting)
+ * @param adlchn Chip channel where note was played
+ * @param note Note number [between 0 and 127]
+ * @param pressure Velocity level, or -1 when it's note off event
+ * @param bend Pitch bend offset value
+ */
 typedef void (*ADL_NoteHook)(void *userdata, int adlchn, int note, int ins, int pressure, double bend);
+
+/**
+ * @brief Debug messages callback
+ * @param userdata Pointer to user data (usually, context of someting)
+ * @param fmt Format strign output (in context of `printf()` standard function)
+ */
 typedef void (*ADL_DebugMessageHook)(void *userdata, const char *fmt, ...);
 
-/* Set raw MIDI event hook */
-extern void adl_setRawEventHook(struct ADL_MIDIPlayer *device, ADL_RawEventHook rawEventHook, void *userData);
+/**
+ * @brief Set raw MIDI event hook
+ * @param device Instance of the library
+ * @param rawEventHook Pointer to the callback function which will be called on every MIDI event
+ * @param userData Pointer to user data which will be passed through the callback.
+ */
+extern ADLMIDI_DECLSPEC void adl_setRawEventHook(struct ADL_MIDIPlayer *device, ADL_RawEventHook rawEventHook, void *userData);
+
+/**
+ * @brief Set note hook
+ * @param device Instance of the library
+ * @param noteHook Pointer to the callback function which will be called on every noteOn MIDI event
+ * @param userData Pointer to user data which will be passed through the callback.
+ */
+extern ADLMIDI_DECLSPEC void adl_setNoteHook(struct ADL_MIDIPlayer *device, ADL_NoteHook noteHook, void *userData);
+
+/**
+ * @brief Set debug message hook
+ * @param device Instance of the library
+ * @param debugMessageHook Pointer to the callback function which will be called on every debug message
+ * @param userData Pointer to user data which will be passed through the callback.
+ */
+extern ADLMIDI_DECLSPEC void adl_setDebugMessageHook(struct ADL_MIDIPlayer *device, ADL_DebugMessageHook debugMessageHook, void *userData);
+
+/**
+ * @brief Get a textual description of the channel state. For display only.
+ * @param device Instance of the library
+ * @param text Destination char buffer for channel usage state. Every entry is assigned to the chip channel.
+ * @param attr Destination char buffer for additional attributes like MIDI channel number that uses this chip channel.
+ * @param size Size of given buffers (both text and attr are must have same size!)
+ * @return 0 on success, <0 when any error has occurred
+ *
+ * Every character in the `text` buffer means the type of usage:
+ * ```
+ *  `-` - channel is unused (free)
+ *  `+` - channel is used by two-operator voice
+ *  `#` - channel is used by four-operator voice
+ *  `@` - channel is used to play automatic arpeggio on chip channels overflow
+ *  `r` - rhythm-mode channel note
+ * ```
+ *
+ * The `attr` field receives the MIDI channel from which the chip channel is used.
+ * To get the valid MIDI channel you will need to apply the & 0x0F mask to every value.
+ */
+extern ADLMIDI_DECLSPEC int adl_describeChannels(struct ADL_MIDIPlayer *device, char *text, char *attr, size_t size);
 
-/* Set note hook */
-extern void adl_setNoteHook(struct ADL_MIDIPlayer *device, ADL_NoteHook noteHook, void *userData);
 
-/* Set debug message hook */
-extern void adl_setDebugMessageHook(struct ADL_MIDIPlayer *device, ADL_DebugMessageHook debugMessageHook, void *userData);
 
 
-/**Instrument structures**/
+/* ======== Instrument structures ======== */
 
+/**
+ * @brief Version of the instrument data format
+ */
 enum
 {
-    ADLMIDI_InstrumentVersion = 0,
+    ADLMIDI_InstrumentVersion = 0
 };
 
+/**
+ * @brief Instrument flags
+ */
 typedef enum ADL_InstrumentFlags
 {
-    /* Is two-operator single-voice instrument (no flags) */
+    /*! Is two-operator single-voice instrument (no flags) */
     ADLMIDI_Ins_2op        = 0x00,
-    /* Is true four-operator instrument */
+    /*! Is true four-operator instrument */
     ADLMIDI_Ins_4op        = 0x01,
-    /* Is pseudo four-operator (two 2-operator voices) instrument */
+    /*! Is pseudo four-operator (two 2-operator voices) instrument */
     ADLMIDI_Ins_Pseudo4op  = 0x02,
-    /* Is a blank instrument entry */
+    /*! Is a blank instrument entry */
     ADLMIDI_Ins_IsBlank    = 0x04,
-    /* Mask of the flags range */
-    ADLMIDI_Ins_ALL_MASK   = 0x07,
+
+    /*! RythmMode flags mask */
+    ADLMIDI_Ins_RhythmModeMask = 0x38,
+
+    /*! Mask of the flags range */
+    ADLMIDI_Ins_ALL_MASK   = 0x07
 } ADL_InstrumentFlags;
 
+/**
+ * @brief Rhythm-mode drum type
+ */
+typedef enum ADL_RhythmMode
+{
+    /*! RythmMode: BassDrum */
+    ADLMIDI_RM_BassDrum  = 0x08,
+    /*! RythmMode: Snare */
+    ADLMIDI_RM_Snare     = 0x10,
+    /*! RythmMode: TomTom */
+    ADLMIDI_RM_TomTom    = 0x18,
+    /*! RythmMode: Cymbal */
+    ADLMIDI_RM_Cymbal    = 0x20,
+    /*! RythmMode: HiHat */
+    ADLMIDI_RM_HiHat     = 0x28
+} ADL_RhythmMode;
+
+
+/**
+ * @brief Operator structure, part of Instrument structure
+ */
 typedef struct ADL_Operator
 {
-    /* AM/Vib/Env/Ksr/FMult characteristics */
+    /*! AM/Vib/Env/Ksr/FMult characteristics */
     ADL_UInt8 avekf_20;
-    /* Key Scale Level / Total level register data */
+    /*! Key Scale Level / Total level register data */
     ADL_UInt8 ksl_l_40;
-    /* Attack / Decay */
+    /*! Attack / Decay */
     ADL_UInt8 atdec_60;
-    /* Systain and Release register data */
+    /*! Systain and Release register data */
     ADL_UInt8 susrel_80;
-    /* Wave form */
+    /*! Wave form */
     ADL_UInt8 waveform_E0;
 } ADL_Operator;
 
+/**
+ * @brief Instrument structure
+ */
 typedef struct ADL_Instrument
 {
-    /* Version of the instrument object */
+    /*! Version of the instrument object */
     int version;
-    /* MIDI note key (half-tone) offset for an instrument (or a first voice in pseudo-4-op mode) */
+    /*! MIDI note key (half-tone) offset for an instrument (or a first voice in pseudo-4-op mode) */
     ADL_SInt16 note_offset1;
-    /* MIDI note key (half-tone) offset for a second voice in pseudo-4-op mode */
+    /*! MIDI note key (half-tone) offset for a second voice in pseudo-4-op mode */
     ADL_SInt16 note_offset2;
-    /* MIDI note velocity offset (taken from Apogee TMB format) */
+    /*! MIDI note velocity offset (taken from Apogee TMB format) */
     ADL_SInt8  midi_velocity_offset;
-    /* Second voice detune level (taken from DMX OP2) */
+    /*! Second voice detune level (taken from DMX OP2) */
     ADL_SInt8  second_voice_detune;
-    /* Percussion MIDI base tone number at which this drum will be played */
+    /*! Percussion MIDI base tone number at which this drum will be played */
     ADL_UInt8 percussion_key_number;
-    /* Enum ADL_InstrumentFlags */
+    /**
+     * @var inst_flags
+     * @brief Instrument flags
+     *
+     * Enums: #ADL_InstrumentFlags and #ADL_RhythmMode
+     *
+     * Bitwise flags bit map:
+     * ```
+     * [0EEEDCBA]
+     *  A) 0x00 - 2-operator mode
+     *  B) 0x01 - 4-operator mode
+     *  C) 0x02 - pseudo-4-operator (two 2-operator voices) mode
+     *  D) 0x04 - is 'blank' instrument (instrument which has no sound)
+     *  E) 0x38 - Reserved for rhythm-mode percussion type number (three bits number)
+     *     -> 0x00 - Melodic or Generic drum (rhythm-mode is disabled)
+     *     -> 0x08 - is Bass drum
+     *     -> 0x10 - is Snare
+     *     -> 0x18 - is Tom-tom
+     *     -> 0x20 - is Cymbal
+     *     -> 0x28 - is Hi-hat
+     *  0) Reserved / Unused
+     * ```
+     */
     ADL_UInt8 inst_flags;
-    /* Feedback&Connection register for first and second operators */
+    /*! Feedback&Connection register for first and second operators */
     ADL_UInt8 fb_conn1_C0;
-    /* Feedback&Connection register for third and fourth operators */
+    /*! Feedback&Connection register for third and fourth operators */
     ADL_UInt8 fb_conn2_C0;
-    /* Operators register data */
+    /*! Operators register data */
     ADL_Operator operators[4];
-    /* Millisecond delay of sounding while key is on */
+    /*! Millisecond delay of sounding while key is on */
     ADL_UInt16 delay_on_ms;
-    /* Millisecond delay of sounding after key off */
+    /*! Millisecond delay of sounding after key off */
     ADL_UInt16 delay_off_ms;
 } ADL_Instrument;