Basic use

Once you will compile library, you will be able to use it in your code.

Library gives one public header you need to include:

#include <adlmidi.h>

To work with a library, you need to declare the instance of it:

struct ADL_MIDIPlayer *midi_player = NULL;

Initialization of the library is very simple:

midi_player = adl_init(44100);

Where 44100 - is the output sample rate in Hertz of the stream you will receive from the library.

Tip: If you wish to change it in a middle of library run, you need to free the instance by the adl_close(midi_player); call and then call adl_init() again, but instead of 44100 give any other value you want.

Since you have initialized the library, you must to check, is it was initialized correctly, or something was happen:

if (!midi_player)
{
    printf("Couldn't initialize ADLMIDI: %s\n", adl_errorString());
    exit(1);
}

Note: The adl_errorString() function can be used only to take library initialization errors, never use it after you have initialized the library.

As you have initialized library, now you can load the MIDI file to play it:

if (adl_openFile(midi_player, "myfile.mid") < 0)
{
    printf("Couldn't open music file: %s\n", adl_errorInfo(midi_player));
    adl_close(midi_player);
    exit(1);
}

The adl_openFile() function returns zero when file was successfully loaded. Othewise, it returns -1 when you gave the wrong path or invalid music file.

Now, when you have initialized the library and loaded the file, you can begin the playing of it:

short buffer[4096];
int samples_count = 0;
do
{
    samples_count = adl_play(midi_player, 4096, buffer);
    if (samples_count > 0)
    {
        /* do something with the generated chunk */
    }
} while (samples_count <= 0);

The adl_play() function receiving three arguments: instance of the library, count of 16-bit PCM samples (must be multiple to two!) and the pointer to buffer that you are writing. In result, you will have 2048 16-bit PCM stereo frames. One frame contains two samples.

A gotten result can be passed into any audio output API or can be written into the file (RAW, WAV, or feed the encoder of some audio codec (for example, Vorbis, FLAC or OPUS) in dependence on your purposes). Repeat those operations until you will reach end of the file. The samples_count will result you a zero value when end of file has been reached.

After you have completed your work with the library, you can close it:

adl_close(midi_player);

Important note 1: Library is NOT thread-safe. You are able to use an instance only in one thread at a time. You are able to run multiple instances of the player each in a thread of their own, but never call library's functions with the same instance from concurrent threads! You can use mutexes to synchronize access to each instance of the library.

To compile your program with using libADLMIDI, you must to link the ADLMIDI (libADLMIDI.a, ADLMIDI.lib, libADLMIDI.so, or libADLMIDI.dylib). In GCC/Clang compilers it's will be -lADLMIDI. Be sure the library is installed into the system, or you need to pass the include path through -I compiler flag and the library link path through -L compiler flag. When you are building the C program, in some cases you will also need to link m and stdc++. If no linking errors occurred, then everything is fine.