C++ API

Error Handling

libopenmpt C++ uses C++ exception handling for errror reporting.

Unless otherwise noted, any libopenmpt function may throw exceptions and all exceptions thrown by libopenmpt itself are derived from openmpt::exception. In addition, any libopenmpt function may also throw any exception specified by the C++ language and C++ standard library. These are all derived from std::exception.

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.

File I/O

libopenmpt can use 3 different strategies for file I/O.

• openmpt::module::module() with any kind of memory buffer as parameter will load the module from the provided memory buffer, which will require loading all data upfront by the library caller.
• openmpt::module::module() with a seekable std::istream as parameter will load the module via the stream interface. libopenmpt will not implement an additional buffering layer in this case whih means the callbacks are assumed to be performant even with small i/o sizes.
• openmpt::module::module() with an unseekable std::istream as parameter will load the module via the stream interface. libopempt will make an internal copy as it goes along, and sometimes have to pre-cache the whole file in case it needs to know the complete file size. This strategy is intended to be used if the file is located on a high latency network.

constructor	speed	memory consumption
memory buffer	fast	medium
seekable stream	slow	low
unseekable stream	medium	high

In all cases, the data or stream passed to the constructor is no longer needed after the openmpt::module has been constructed and can be destroyed by the caller.

Output Format

libopenmpt supports a wide range of PCM output formats: [8000..192000]/[mono|stereo|quad]/[f32|i16].

Unless you have some very specific requirements demanding a particular aspect of the output format, you should always prefer 48000/stereo/f32 as the libopenmpt PCM format.

• Please prefer 48000Hz unless the user explicitly demands something else. Practically all audio equipment and file formats use 48000Hz nowadays.
• Practically all module formats are made for stereo output. Mono will not give you any measurable speed improvements and can trivially be obtained from the stereo output anyway. Quad is not expected by almost all modules and even if they do use surround effects, they expect the effects to be mixed to stereo.
• Floating point output provides headroom instead of hard clipping if the module is louder than 0dBFs, will give you a better signal-to-noise ratio than int16 output, and avoid the need to apply an additional dithering to the output by libopenmpt. Unless your platform has no floating point unit at all, floating point will thus also be slightly faster.

libopenmpt in multi-threaded environments

• libopenmpt is thread-aware.
• Individual libopenmpt objects are not thread-safe.
• libopenmpt itself does not spawn any user-visible threads but may spawn threads for internal use.
• You must ensure to only ever access a particular libopenmpt object via non-const member functions from a single thread at a time.
• You may access a particular libopenmpt object concurrently from different threads when using only const member functions from all threads.
• Consecutive accesses can happen from different threads.
• Different objects can be accessed concurrently from different threads.

Windows support

Using the libopenmpt C++ API when libopenmpt is compiled as a DLL on Windows requires #define LIBOPENMPT_USE_DLL (or some equivalent build system configuration) before #include <libopenmpt/libopenmpt.hpp> in order to correctly import the symbols from the DLL.

Detailed documentation

libopenmpt C++

Example

/*
 * libopenmpt_example_cxx.cpp
 * --------------------------
 * Purpose: libopenmpt C++ API example
 * Notes  : PortAudio C++ is used for sound output.
 * Authors: OpenMPT Devs
 * The OpenMPT source code is released under the BSD license. Read LICENSE for more details.
 */
 
/*
 * Usage: libopenmpt_example_cxx SOMEMODULE
 */
 
#if defined( __MINGW32__ ) && !defined( __MINGW64__ )
#include <sys/types.h>
#endif
 
#include <exception>
#include <fstream>
#include <iostream>
#include <new>
#include <stdexcept>
#include <vector>
 
#include <libopenmpt/libopenmpt.hpp>
 
#if defined( __clang__ )
#if ( ( __clang_major__ * 10000 + __clang_minor__ * 100 + __clang_patchlevel__ ) >= 40000 )
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wdeprecated-dynamic-exception-spec"
#endif
#endif
#include <portaudiocpp/PortAudioCpp.hxx>
#if defined( __clang__ )
#if ( ( __clang_major__ * 10000 + __clang_minor__ * 100 + __clang_patchlevel__ ) >= 40000 )
#pragma clang diagnostic pop
#endif
#endif
 
#if defined( __DJGPP__ )
#include <crt0.h>
#endif /* __DJGPP__ */
 
#if defined( __DJGPP__ )
/* clang-format off */
extern "C" int _crt0_startup_flags = 0
  | _CRT0_FLAG_NONMOVE_SBRK          /* force interrupt compatible allocation */
  | _CRT0_DISABLE_SBRK_ADDRESS_WRAP  /* force NT compatible allocation */
  | _CRT0_FLAG_LOCK_MEMORY           /* lock all code and data at program startup */
  | 0;
/* clang-format on */
#endif /* __DJGPP__ */
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
#if defined( __GNUC__ ) || ( defined( __clang__ ) && !defined( _MSC_VER ) )
// mingw-w64 g++ does only default to special C linkage for "main", but not for "wmain" (see <https://sourceforge.net/p/mingw-w64/wiki2/Unicode%20apps/>).
extern "C" int wmain( int /*argc*/, wchar_t * /*argv*/[] );
extern "C" int wmain( int argc, wchar_t * argv[] ) {
#else
int wmain( int argc, wchar_t * argv[] ) {
#endif
#else
int main( int argc, char * argv[] ) {
#endif
#if defined( __DJGPP__ )
  /* clang-format off */
  _crt0_startup_flags &= ~_CRT0_FLAG_LOCK_MEMORY;  /* disable automatic locking for all further memory allocations */
  /* clang-format on */
#endif /* __DJGPP__ */
  try {
    if ( argc != 2 ) {
      throw std::runtime_error( "Usage: libopenmpt_example_cxx SOMEMODULE" );
    }
    constexpr std::size_t buffersize = 480;
    constexpr std::int32_t samplerate = 48000;
    std::ifstream file( argv[1], std::ios::binary );
    openmpt::module mod( file );
    portaudio::AutoSystem portaudio_initializer;
    portaudio::System & portaudio = portaudio::System::instance();
    std::vector<float> left( buffersize );
    std::vector<float> right( buffersize );
    std::vector<float> interleaved_buffer( buffersize * 2 );
    bool is_interleaved = false;
#if defined( _MSC_VER ) && defined( _PREFAST_ )
    // work-around bug in VS2019 MSVC 16.5.5 static analyzer
    is_interleaved = false;
    portaudio::DirectionSpecificStreamParameters outputstream_parameters( portaudio.defaultOutputDevice(), 2, portaudio::FLOAT32, false, portaudio.defaultOutputDevice().defaultHighOutputLatency(), 0 );
    portaudio::StreamParameters stream_parameters( portaudio::DirectionSpecificStreamParameters::null(), outputstream_parameters, samplerate, paFramesPerBufferUnspecified, paNoFlag );
    portaudio::BlockingStream stream( stream_parameters );
#else
    portaudio::BlockingStream stream = [&]()
    {
      try {
        is_interleaved = false;
        portaudio::DirectionSpecificStreamParameters outputstream_parameters( portaudio.defaultOutputDevice(), 2, portaudio::FLOAT32, false, portaudio.defaultOutputDevice().defaultHighOutputLatency(), 0 );
        portaudio::StreamParameters stream_parameters( portaudio::DirectionSpecificStreamParameters::null(), outputstream_parameters, samplerate, paFramesPerBufferUnspecified, paNoFlag );
        return portaudio::BlockingStream( stream_parameters );
      } catch ( const portaudio::PaException & e ) {
        if ( e.paError() != paSampleFormatNotSupported ) {
          throw;
        }
        is_interleaved = true;
        portaudio::DirectionSpecificStreamParameters outputstream_parameters( portaudio.defaultOutputDevice(), 2, portaudio::FLOAT32, true, portaudio.defaultOutputDevice().defaultHighOutputLatency(), 0 );
        portaudio::StreamParameters stream_parameters( portaudio::DirectionSpecificStreamParameters::null(), outputstream_parameters, samplerate, paFramesPerBufferUnspecified, paNoFlag );
        return portaudio::BlockingStream( stream_parameters );
      }
    }();
#endif
    stream.start();
    while ( true ) {
      std::size_t count = is_interleaved ? mod.read_interleaved_stereo( samplerate, buffersize, interleaved_buffer.data() ) : mod.read( samplerate, buffersize, left.data(), right.data() );
      if ( count == 0 ) {
        break;
      }
      try {
        if ( is_interleaved ) {
          stream.write( interleaved_buffer.data(), static_cast<unsigned long>( count ) );
        } else {
          const float * const buffers[2] = { left.data(), right.data() };
          stream.write( buffers, static_cast<unsigned long>( count ) );
        }
      } catch ( const portaudio::PaException & pa_exception ) {
        if ( pa_exception.paError() != paOutputUnderflowed ) {
          throw;
        }
      }
    }
    stream.stop();
  } catch ( const std::bad_alloc & ) {
    std::cerr << "Error: " << std::string( "out of memory" ) << std::endl;
    return 1;
  } catch ( const std::exception & e ) {
    std::cerr << "Error: " << std::string( e.what() ? e.what() : "unknown error" ) << std::endl;
    return 1;
  }
  return 0;
}