// SPDX-License-Identifier: BSD-2-Clause

// This code is part of the sfizz library and is licensed under a BSD 2-clause
// license. You should have receive a LICENSE.md file along with the code.
// If not, contact the sfizz maintainers at https://github.com/sfztools/sfizz

/**
  @file
  @brief sfizz public C++ API.
*/

#pragma once
#include "sfizz_message.h"
#include <string>
#include <utility>
#include <vector>
#include <memory>

#if defined SFIZZ_EXPORT_SYMBOLS
  #if defined _WIN32
    #define SFIZZ_EXPORTED_API __declspec(dllexport)
  #else
    #define SFIZZ_EXPORTED_API __attribute__ ((visibility ("default")))
  #endif
#else
  #define SFIZZ_EXPORTED_API
#endif

//! @cond Doxygen_Suppress
#if defined _WIN32
  #define SFIZZ_DEPRECATED_API __declspec(deprecated)
#else
  #define SFIZZ_DEPRECATED_API __attribute__ ((deprecated))
#endif
//! @endcond

struct sfizz_synth_t;

namespace sfz
{
class Client;
/**
 * @brief Synthesizer for SFZ instruments
*
* The synthesizer must be operated under indicated constraints in order to
* guarantee thread-safety.
*
* At any given time, no more than 2 tasks must interact in parallel with this
* library:
* - a processing tasks @b RT for audio and MIDI, which can be real-time
* - a Control tasks @b CT
*
* The tasks RT and CT can be assumed by different threads over the lifetime, as
* long as the switch is adequately synchronized. If real-time processing is not
* required, it's acceptable for the 2 tasks can be assumed by a single thread.
*
* Where one or more following items are indicated on a function, the constraints apply.
* - @b RT: the function must be invoked from the Real-time thread
* - @b CT: the function must be invoked from the Control thread
* - @b OFF: the function cannot be invoked while a thread is calling @b RT functions
*/
class SFIZZ_EXPORTED_API Sfizz
{
public:
    /**
     * @brief Construct a new Sfizz object.
     *
     * The synth by default is set at 48 kHz and a block size of 1024.
     * You should change these values if they are not suited to your application.
     */
    Sfizz();
    ~Sfizz();

    /**
     * @brief Move constructor.
     */
    Sfizz(Sfizz&& other) noexcept;

    /**
     * @brief Move assignment operator.
     */
    Sfizz& operator=(Sfizz&& other) noexcept;

    Sfizz(const Sfizz& other) = delete;
    Sfizz& operator=(const Sfizz& other) = delete;

    /**
     * @brief Reference an existing synth handle.
     */
    explicit Sfizz(sfizz_synth_t* synth);

    /**
     * @brief Get the synth handle.
     */
    sfizz_synth_t* handle() const noexcept { return synth; }

    /**
     * @brief Processing mode.
     * @since 0.4.0
     */
    enum ProcessMode {
        ProcessLive,
        ProcessFreewheeling,
    };

    /**
     * @brief Empties the current regions and load a new SFZ file into the synth.
     *
     * @since 0.2.0
     *
     * @param path The path to the file to load, as string.
     *
     * @return @false if the file was not found or no regions were loaded,
     *         @true otherwise.
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     * - @b OFF: the function cannot be invoked while a thread is calling @b RT functions
     */
    bool loadSfzFile(const std::string& path);

    /**
     * @brief Empties the current regions and load a new SFZ document from memory.
     *
     * This is similar to loadSfzFile() in functionality.
     * This accepts a virtual path name for the imaginary sfz file, which is not
     * required to exist on disk. The purpose of the virtual path is to locate
     * samples with relative paths.
     *
     * @since 0.4.0
     *
     * @param path The virtual path of the SFZ file, as string.
     * @param text The contents of the virtual SFZ file.
     *
     * @return @false if no regions were loaded,
     *         @true otherwise.
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     * - @b OFF: the function cannot be invoked while a thread is calling @b RT functions
     */
    bool loadSfzString(const std::string& path, const std::string& text);

    /**
     * @brief Sets the tuning from a Scala file loaded from the file system.
     *
     * @since 0.4.0
     *
     * @param path The path to the file in Scala format.
     *
     * @return @true when tuning scale loaded OK,
     *         @false if some error occurred.
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     * - @b OFF: the function cannot be invoked while a thread is calling @b RT functions
     */
    bool loadScalaFile(const std::string& path);

    /**
     * @brief Sets the tuning from a Scala file loaded from memory.
     *
     * @since 0.4.0
     *
     * @param text The contents of the file in Scala format.
     *
     * @return @true when tuning scale loaded OK,
     *         @false if some error occurred.
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     * - @b OFF: the function cannot be invoked while a thread is calling @b RT functions
     */
    bool loadScalaString(const std::string& text);

    /**
     * @brief Sets the scala root key.
     *
     * @since 0.4.0
     *
     * @param rootKey The MIDI number of the Scala root key (default 60 for C4).
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void setScalaRootKey(int rootKey);

    /**
     * @brief Gets the scala root key.
     * @since 0.4.0
     *
     * @return The MIDI number of the Scala root key (default 60 for C4).
     */
    int getScalaRootKey() const;

    /**
     * @brief Sets the reference tuning frequency.
     *
     * @since 0.4.0
     *
     * @param frequency The frequency which indicates where standard tuning A4 is (default 440 Hz).
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void setTuningFrequency(float frequency);

    /**
     * @brief Gets the reference tuning frequency.
     * @since 0.4.0
     *
     * @return The frequency which indicates where standard tuning A4 is (default 440 Hz).
     */
    float getTuningFrequency() const;

    /**
     * @brief Configure stretch tuning using a predefined parametric Railsback curve.
     *
     * A ratio 1/2 is supposed to match the average piano; 0 disables (the default).
     *
     * @since 0.4.0
     *
     * @param ratio The parameter in domain 0-1.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void loadStretchTuningByRatio(float ratio);

    /**
     * @brief Return the current number of regions loaded.
     * @since 0.2.0
     */
    int getNumRegions() const noexcept;

    /**
     * @brief Return the current number of groups loaded.
     * @since 0.2.0
     */
    int getNumGroups() const noexcept;

    /**
     * @brief Return the current number of masters loaded.
     * @since 0.2.0
     */
    int getNumMasters() const noexcept;

    /**
     * @brief Return the current number of curves loaded.
     * @since 0.2.0
     */
    int getNumCurves() const noexcept;

    /**
     * @brief Return a list of unsupported opcodes, if any.
     * @since 0.2.0
     */
    const std::vector<std::string>& getUnknownOpcodes() const noexcept;

    /**
     * @brief Return the number of preloaded samples in the synth.
     * @since 0.2.0
     */
    size_t getNumPreloadedSamples() const noexcept;

    /**
     * @brief Set the maximum size of the blocks for the callback.
     *
     * The actual size can be lower in each callback but should not be larger
     * than this value.
     *
     * @since 0.2.0
     *
     * @param samplesPerBlock The number of samples per block.
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     * - @b OFF: the function cannot be invoked while a thread is calling @b RT functions
     */
    void setSamplesPerBlock(int samplesPerBlock) noexcept;

    /**
     * @brief Set the sample rate.
     *
     * If you do not call it it is initialized to `sfz::config::defaultSampleRate`.
     *
     * @since 0.2.0
     *
     * @param sampleRate The sample rate.
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     * - @b OFF: the function cannot be invoked while a thread is calling @b RT functions
     */
    void setSampleRate(float sampleRate) noexcept;

    /**
     * @brief Get the default resampling quality.
     *
     * This is the quality setting which the engine uses when the instrument
     * does not use the opcode `sample_quality`. The engine uses distinct
     * default quality settings for live mode and freewheeling mode,
     * which both can be accessed by the means of this function.
     * @since 0.4.0
     *
     * @param[in] mode  The processing mode.
     *
     * @return The sample quality for the given mode, in the range 0 to 10.
     */
    int getSampleQuality(ProcessMode mode);

    /**
     * @brief Set the default resampling quality.
     *
     * This is the quality setting which the engine uses when the instrument
     * does not use the opcode `sample_quality`. The engine uses distinct
     * default quality settings for live mode and freewheeling mode,
     * which both can be accessed by the means of this function.
     *
     * @since 0.4.0
     *
     * @param[in] mode    The processing mode.
     * @param[in] quality The desired sample quality, in the range 0 to 10.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void setSampleQuality(ProcessMode mode, int quality);

    /**
     * @brief Get the default oscillator quality.
     *
     * This is the quality setting which the engine uses when the instrument
     * does not use the opcode `oscillator_quality`. The engine uses distinct
     * default quality settings for live mode and freewheeling mode,
     * which both can be accessed by the means of this function.
     * @since 1.0.0
     *
     * @param[in] mode  The processing mode.
     *
     * @return The oscillator quality for the given mode, in the range 0 to 3.
     */
    int getOscillatorQuality(ProcessMode mode);

    /**
     * @brief Set the default oscillator quality.
     *
     * This is the quality setting which the engine uses when the instrument
     * does not use the opcode `oscillator_quality`. The engine uses distinct
     * default quality settings for live mode and freewheeling mode,
     * which both can be accessed by the means of this function.
     *
     * @since 1.0.0
     *
     * @param[in] mode    The processing mode.
     * @param[in] quality The desired oscillator quality, in the range 0 to 3.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void setOscillatorQuality(ProcessMode mode, int quality);

    /**
     * @brief Set whether pressing the sustain pedal cancels the release stage
     *
     * @param value
     */
    void setSustainCancelsRelease(bool value);

    /**
     * @brief Return the current value for the volume, in dB.
     * @since 0.2.0
     */
    float getVolume() const noexcept;

     /**
     * @brief Set the value for the volume.
     *
     * This value will be clamped within `sfz::default::volumeRange`.
     *
     * @since 0.2.0
     *
     * @param volume The new volume.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void setVolume(float volume) noexcept;

    /**
     * @brief Send a note on event to the synth.
     * @since 0.2.0
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param noteNumber the midi note number, in domain 0 to 127.
     * @param velocity the midi note velocity, in domain 0 to 127.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void noteOn(int delay, int noteNumber, int velocity) noexcept;

    /**
     * @brief Send a high-precision note on event to the synth.
     * @since 1.0.0
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param noteNumber the midi note number, in domain 0 to 127.
     * @param velocity the normalized midi note velocity, in domain 0 to 1.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void hdNoteOn(int delay, int noteNumber, float velocity) noexcept;

    /**
     * @brief Send a note off event to the synth.
     * @since 0.2.0
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param noteNumber the midi note number, in domain 0 to 127.
     * @param velocity the midi note velocity, in domain 0 to 127.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void noteOff(int delay, int noteNumber, int velocity) noexcept;

    /**
     * @brief Send a note off event to the synth.
     * @since 1.0.0
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param noteNumber the midi note number, in domain 0 to 127.
     * @param velocity the normalized midi note velocity, in domain 0 to 1.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void hdNoteOff(int delay, int noteNumber, float velocity) noexcept;

    /**
     * @brief Send a CC event to the synth
     * @since 0.2.0
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param ccNumber the cc number, in domain 0 to 127.
     * @param ccValue the cc value, in domain 0 to 127.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void cc(int delay, int ccNumber, int ccValue) noexcept;

    /**
     * @brief Send a high precision CC event to the synth
     * @since 0.4.0
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param ccNumber the cc number, in domain 0 to 127.
     * @param normValue the normalized cc value, in domain 0 to 1.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void hdcc(int delay, int ccNumber, float normValue) noexcept;

    /**
     * @brief Send a program change event to the synth
     * @since 1.1.2
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param program the cc number, in domain 0 to 127.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void programChange(int delay, int program) noexcept;

    /**
     * @brief Send a high precision CC automation to the synth
     *
     * This updates the CC value known to the synth, but without performing
     * additional MIDI-specific interpretations. (eg. the CC 120 and up)
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @since 1.0.0
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param ccNumber the cc number, in domain 0 to 127.
     * @param normValue the normalized cc value, in domain 0 to 1.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void automateHdcc(int delay, int ccNumber, float normValue) noexcept;

    /**
     * @brief Send a pitch bend event to the synth
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @since 0.2.0
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param pitch the pitch value centered between -8192 and 8192.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void pitchWheel(int delay, int pitch) noexcept;

    /**
     * @brief Send a high-precision pitch bend event to the synth
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @since 1.0.0
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param pitch the normalized pitch, in domain -1 to 1.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void hdPitchWheel(int delay, float pitch) noexcept;

    /**
     * @brief Send an aftertouch event to the synth.
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @since 0.2.0
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param aftertouch the aftertouch value, in domain 0 to 127.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    SFIZZ_DEPRECATED_API void aftertouch(int delay, int aftertouch) noexcept;

    /**
     * @brief Send a channel aftertouch (channel pressure) event to the synth.
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @since 0.2.0
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param aftertouch the aftertouch value, in domain 0 to 127.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void channelAftertouch(int delay, int aftertouch) noexcept;

    /**
     * @brief Send a high-precision aftertouch event to the synth.
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @since 1.0.0
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param aftertouch the normalized aftertouch value, in domain 0 to 1.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void hdChannelAftertouch(int delay, float aftertouch) noexcept;

    /**
     * @brief Send a polyphonic aftertouch event to the synth.
     *        This feature is experimental and needs more testing in the internal engine.
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @since 1.0.0
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param noteNumber the note number, in domain 0 to 127.
     * @param aftertouch the aftertouch value, in domain 0 to 127.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void polyAftertouch(int delay, int noteNumber, int aftertouch) noexcept;

    /**
     * @brief Send a high-precision polyphonic aftertouch event to the synth.
     *        This feature is experimental and needs more testing in the internal engine.
     *
     * This command should be delay-ordered with all other midi-type events
     * (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the
     * synth is undefined.
     *
     * @since 1.0.0
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param noteNumber the note number, in domain 0 to 127.
     * @param aftertouch the normalized aftertouch value, in domain 0 to 1.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void hdPolyAftertouch(int delay, int noteNumber, float aftertouch) noexcept;

    /**
     * @brief Send a tempo event to the synth.
     *
     * This command should be delay-ordered with all other time/signature commands, namely
     * tempo(), timeSignature(), timePosition(), and playbackState(), otherwise the behavior
     * of the synth is undefined.
     *
     * @since 0.2.0
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param secondsPerBeat the new period of the beat.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    SFIZZ_DEPRECATED_API void tempo(int delay, float secondsPerBeat) noexcept;

    /**
     * @brief Send a tempo event to the synth.
     *
     * This command should be delay-ordered with all other time/signature commands, namely
     * tempo(), timeSignature(), timePosition(), and playbackState(), otherwise the behavior
     * of the synth is undefined.
     *
     * @since 1.0.0
     *
     * @param delay the delay at which the event occurs; this should be lower
     *              than the size of the block in the next call to renderBlock().
     * @param beatsPerMinute the new tempo, in beats per minute.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void bpmTempo(int delay, float beatsPerMinute) noexcept;

    /**
     * @brief Send the time signature.
     *
     * This command should be delay-ordered with all other time/signature commands, namely
     * tempo(), timeSignature(), timePosition(), and playbackState(), otherwise the behavior
     * of the synth is undefined.
     *
     * @since 0.5.0
     *
     * @param delay       The delay.
     * @param beatsPerBar The number of beats per bar, or time signature numerator.
     * @param beatUnit    The note corresponding to one beat, or time signature denominator.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void timeSignature(int delay, int beatsPerBar, int beatUnit);

    /**
     * @brief Send the time position.
     *
     * This command should be delay-ordered with all other time/signature commands, namely
     * tempo(), timeSignature(), timePosition(), and playbackState(), otherwise the behavior
     * of the synth is undefined.
     *
     * @since 0.5.0
     *
     * @param delay   The delay.
     * @param bar     The current bar.
     * @param barBeat The fractional position of the current beat within the bar.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void timePosition(int delay, int bar, double barBeat);

    /**
     * @brief Send the playback state.
     *
     * This command should be delay-ordered with all other time/signature commands, namely
     * tempo(), timeSignature(), timePosition(), and playbackState(), otherwise the behavior
     * of the synth is undefined.
     *
     * @since 0.5.0
     *
     * @param delay         The delay.
     * @param playbackState The playback state, 1 if playing, 0 if stopped.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void playbackState(int delay, int playbackState);

    /**
     * @brief Render an block of audio data in the buffer.
     *
     * This call will reset the synth in its waiting state for the next batch
     * of events. The buffers must be float[numSamples][numOutputs * 2].
     *
     * @since 0.2.0
     *
     * @param buffers the buffers to write the next block into.
     * @param numFrames the number of stereo frames in the block.
     * @param numOutputs the number of stereo outputs.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void renderBlock(float** buffers, size_t numFrames, int numOutputs = 1) noexcept;

    /**
     * @brief Return the number of active voices.
     * @since 0.2.0
     */
    int getNumActiveVoices() const noexcept;

    /**
     * @brief Return the total number of voices in the synth (the polyphony).
     * @since 0.2.0
     */
    int getNumVoices() const noexcept;

    /**
     * @brief Change the number of voices (the polyphony).
     *
     * @since 0.2.0
     *
     * @param numVoices The number of voices.
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     * - @b OFF: the function cannot be invoked while a thread is calling @b RT functions
     */
    void setNumVoices(int numVoices) noexcept;

    /**
     * @brief Set the oversampling factor to a new value.
     *
     * As of 1.0, This is an inactive stub for future work on oversampling in the engine.
     *
     *
     * @since 0.2.0
     *
     * @param factor The oversampling factor.
     *
     * @return @true if the factor did indeed change, @false otherwise.
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     * - @b OFF: the function cannot be invoked while a thread is calling @b RT functions
     */
    bool setOversamplingFactor(int factor) noexcept;

    /**
     * @brief Return the current oversampling factor.
     * @since 0.2.0
     *
     * As of 1.0, This is an inactive stub for future work on oversampling in the engine.
     *
     */
    int getOversamplingFactor() const noexcept;

    /**
     * @brief Set the preloaded file size.
     *
     * @since 0.2.0
     *
     * @param preloadSize  The preload size.
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     * - @b OFF: the function cannot be invoked while a thread is calling @b RT functions
     */
    void setPreloadSize(uint32_t preloadSize) noexcept;

    /**
     * @brief Return the current preloaded file size.
     * @since 0.2.0
     */
    uint32_t getPreloadSize() const noexcept;

    /**
     * @brief Return the number of allocated buffers.
     * @since 0.2.0
     */
    int getAllocatedBuffers() const noexcept;

    /**
     * @brief Return the number of bytes allocated through the buffers.
     * @since 0.2.0
     */
    int getAllocatedBytes() const noexcept;

    /**
     * @brief Enable freewheeling on the synth.
     *
     * This will wait for background loaded files to finish loading
     * before each render callback to ensure that there will be no dropouts.
     *
     * @since 0.2.0
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void enableFreeWheeling() noexcept;

    /**
     * @brief Disable freewheeling on the synth.
     *
     * You should disable freewheeling before live use of the plugin
     * otherwise the audio thread will lock.
     *
     * @since 0.2.0
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void disableFreeWheeling() noexcept;

    /**
     * @brief Check if the SFZ should be reloaded.
     *
     * Depending on the platform this can create file descriptors.
     *
     * @since 0.2.0
     *
     * @return @true if any included files (including the root file) have
     *         been modified since the sfz file was loaded, @false otherwise.
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     */
    bool shouldReloadFile();

    /**
     * @brief Check if the tuning (scala) file should be reloaded.
     *
     * Depending on the platform this can create file descriptors.
     *
     * @since 0.4.0
     *
     * @return @true if a scala file has been loaded and has changed, @false otherwise.
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     */
    bool shouldReloadScala();

    /**
     * @brief Enable logging of timings to sidecar CSV files.
     * @since 0.3.0
     *
     * @note This can produce many outputs so use with caution.
     *
     * @param prefix the file prefix to use for logging.
     *
     * @par Thread-safety constraints
     * - TBD ?
     */
    SFIZZ_DEPRECATED_API void enableLogging() noexcept;

    /**
     * @brief Enable logging of timings to sidecar CSV files.
     *
     * @since 0.3.2
     *
     * @note This can produce many outputs so use with caution.
     * Deprecated since 1.2.0
     *
     * @param prefix the file prefix to use for logging.
     *
     * @par Thread-safety constraints
     * - TBD ?
     */
    SFIZZ_DEPRECATED_API void enableLogging(const std::string& prefix) noexcept;

    /**
     * @brief Set the logging prefix.
     *
     * @since 0.3.2
     * @note Deprecated since 1.2.0
     *
     * @param prefix
     *
     *
     * @par Thread-safety constraints
     * - TBD ?
     */
    SFIZZ_DEPRECATED_API void setLoggingPrefix(const std::string& prefix) noexcept;

    /**
     * @brief Disable logging of timings to sidecar CSV files.
     *
     * @since 0.3.0
     * @note Deprecated since 1.2.0
     *
     * @par Thread-safety constraints
     * - TBD ?
     */
    SFIZZ_DEPRECATED_API void disableLogging() noexcept;

    struct CallbackBreakdown
    {
        double dispatch;
        double renderMethod;
        double data;
        double amplitude;
        double filters;
        double panning;
        double effects;
    };

    /**
     * @brief Get the last callback breakdown. Call after a render method.
     *
     * @since 1.2.0
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     *
     * @return CallbackBreakdown
     */
    CallbackBreakdown getCallbackBreakdown() noexcept;

    /**
     * @brief Shuts down the current processing, clear buffers and reset the voices.
     *
     * @since 0.3.2
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void allSoundOff() noexcept;

    /**
     * @brief Add external definitions prior to loading.
     *
     * @since 0.4.0
     *
     * @note These do not get reset by loading or resetting the synth.
     * You need to call clearExternalDefintions() to erase them.
     *
     * @param id    The definition variable name.
     * @param value The definition value.
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     */
    void addExternalDefinition(const std::string& id, const std::string& value);

    /**
     * @brief Clears external definitions for the next file loading.
     *
     * @since 0.4.0
     *
     * @par Thread-safety constraints
     * - @b CT: the function must be invoked from the Control thread
     */
    void clearExternalDefinitions();

    /**
     * @brief Get the key labels, if any.
     * @since 0.4.0
     */
    const std::vector<std::pair<uint8_t, std::string>>& getKeyLabels() const noexcept;

    /**
     * @brief Get the CC labels, if any.
     * @since 0.4.0
     */
    const std::vector<std::pair<uint16_t, std::string>>& getCCLabels() const noexcept;

    /**
     * @brief Export a MIDI Name document describing the currently loaded SFZ file.
     * @since 1.0.0
     *
     * @param model  The model name used if a non-empty string, otherwise generated.
     *
     * @return A XML string.
     */
    std::string exportMidnam(const std::string& model) const;

    /**
     * @addtogroup Messaging
     * @{
     */

private:
    struct ClientDeleter {
        void operator()(Client *client) const noexcept;
    };

public:
//! @cond Doxygen_Suppress
    using ClientPtr = std::unique_ptr<Client, ClientDeleter>;
//! @endcond

    /**
     * @brief Create a new messaging client
     * @since 1.0.0
     *
     * @param data         The opaque data pointer which is passed to the receiver.
     * @return             The new client.
     */
    static ClientPtr createClient(void* data);

    /**
     * @brief Get the client data
     * @since 1.0.0
     *
     * @param client       The client.
     * @return             The client data.
     */
    static void* getClientData(Client& client);

    /**
     * @brief Set the function which receives reply messages from the synth engine.
     * @since 1.0.0
     *
     * @param client       The client.
     * @param receive      The pointer to the receiving function.
     */
    static void setReceiveCallback(Client& client, sfizz_receive_t* receive);

    /**
     * @brief Send a message to the synth engine
     *
     * @since 1.0.0
     *
     * @param client       The client sending the message.
     * @param delay        The delay of the message in the block, in samples.
     * @param path         The OSC address pattern.
     * @param sig          The OSC type tag string.
     * @param args         The OSC arguments, whose number and format is determined the type tag string.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void sendMessage(Client& client, int delay, const char* path, const char* sig, const sfizz_arg_t* args);

    /**
     * @brief Set the function which receives broadcast messages from the synth engine.
     *
     * @since 1.0.0
     *
     * @param broadcast    The pointer to the receiving function.
     * @param data         The opaque data pointer which is passed to the receiver.
     *
     * @par Thread-safety constraints
     * - @b RT: the function must be invoked from the Real-time thread
     */
    void setBroadcastCallback(sfizz_receive_t* broadcast, void* data);

    /**
     * @}
     */

private:
    sfizz_synth_t* synth {};
};
//! @cond Doxygen_Suppress
using ClientPtr = Sfizz::ClientPtr;
//! @endcond
}