Error Handling
- Functions with no return value in the corresponding C++ API return 0 on failure and 1 on success.
- Functions that return a string in the corresponding C++ API return a dynamically allocated const char *. I case of failure or memory allocation failure, a NULL pointer is returned.
- Functions that return integer values signal error condition by returning an invalid value (-1 in most cases, 0 in some cases).
Strings
- All strings returned from libopenmpt are encoded in UTF-8.
- All strings passed to libopenmpt should also be encoded in UTF-8. Behaviour in case of invalid UTF-8 is unspecified.
- libopenmpt does not enforce or expect any particular unicode normalization form.
- All strings returned from libopenmpt are dynamically allocated and must be freed with openmpt_free_string(). Do NOT use the C standard library free() for libopenmpt strings as that would make your code invalid on windows when dynamically linking against libopenmpt which itself statically links to the C runtime.
- All strings passed to libopenmpt are copied. No ownership is assumed or transferred.
Detailed documentation
libopenmpt C
The C API documentaion currently lacks behind the C++ API documentation. In case a function is not documented here, you might want to look at the libopenmpt C++ documentation. The C and C++ APIs are kept semantically as close as possible.
Examples
FILE*
#include <memory.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <portaudio.h>
#define BUFFERSIZE 480
#define SAMPLERATE 48000
static int16_t left[BUFFERSIZE];
static int16_t right[BUFFERSIZE];
static int16_t * const buffers[2] = { left, right };
int main( int argc, char * argv[] ) {
FILE * file = 0;
size_t count = 0;
PaStream * stream = 0;
PaStreamParameters streamparameters;
memset( &streamparameters, 0, sizeof( PaStreamParameters ) );
(void)argc;
file = fopen( argv[1], "rb" );
fclose( file );
Pa_Initialize();
streamparameters.device = Pa_GetDefaultOutputDevice();
streamparameters.channelCount = 2;
streamparameters.sampleFormat = paInt16 | paNonInterleaved;
streamparameters.suggestedLatency = Pa_GetDeviceInfo( streamparameters.device )->defaultHighOutputLatency;
Pa_OpenStream( &stream, NULL, &streamparameters, SAMPLERATE, paFramesPerBufferUnspecified, 0, NULL, NULL );
Pa_StartStream( stream );
while ( 1 ) {
if ( count == 0 ) {
break;
}
Pa_WriteStream( stream, buffers, count );
}
Pa_StopStream( stream );
Pa_CloseStream( stream );
Pa_Terminate();
return 0;
}
in memory
#include <memory.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <portaudio.h>
#define BUFFERSIZE 480
#define SAMPLERATE 48000
static int16_t left[BUFFERSIZE];
static int16_t right[BUFFERSIZE];
static int16_t * const buffers[2] = { left, right };
int main( int argc, char * argv[] ) {
FILE * file = 0;
size_t size = 0;
void * data = 0;
size_t count = 0;
PaStream * stream = 0;
PaStreamParameters streamparameters;
memset( &streamparameters, 0, sizeof( PaStreamParameters ) );
(void)argc;
file = fopen( argv[1], "rb" );
fseek( file, 0, SEEK_END );
size = ftell( file );
fseek( file, 0, SEEK_SET );
data = malloc( size );
size = fread( data, 1, size, file );
fclose( file );
free( data );
Pa_Initialize();
streamparameters.device = Pa_GetDefaultOutputDevice();
streamparameters.channelCount = 2;
streamparameters.sampleFormat = paInt16 | paNonInterleaved;
streamparameters.suggestedLatency = Pa_GetDeviceInfo( streamparameters.device )->defaultHighOutputLatency;
Pa_OpenStream( &stream, NULL, &streamparameters, SAMPLERATE, paFramesPerBufferUnspecified, 0, NULL, NULL );
Pa_StartStream( stream );
while ( 1 ) {
if ( count == 0 ) {
break;
}
Pa_WriteStream( stream, buffers, count );
}
Pa_StopStream( stream );
Pa_CloseStream( stream );
Pa_Terminate();
return 0;
}
reading FILE* and writing PCM data to STDOUT (usable without PortAudio)
#include <memory.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <unistd.h>
#define BUFFERSIZE 480
#define SAMPLERATE 48000
static ssize_t xwrite( int fd, const void * buffer, size_t size ) {
size_t written = 0;
ssize_t retval = 0;
while ( written < size ) {
retval = write( fd, (const char *)buffer + written, size - written );
if ( retval < 0 ) {
if ( errno != EINTR ) {
break;
}
retval = 0;
}
written += retval;
}
return written;
}
static int16_t buffer[BUFFERSIZE * 2];
int main( int argc, char * argv[] ) {
FILE * file = 0;
size_t count = 0;
(void)argc;
file = fopen( argv[1], "rb" );
fclose( file );
while ( 1 ) {
if ( count == 0 ) {
break;
}
xwrite( STDOUT_FILENO, buffer, count * 2 * sizeof( int16_t ) );
}
return 0;
}