libopenmpt  0.3.13+release
cross-platform C++ and C library to decode tracked music files
libopenmpt C

Modules

 Render param indices
 Parameter index to use with openmpt_module_get_render_param() and openmpt_module_set_render_param()
 
 Pattern cell indices
 Parameter index to use with openmpt_module_get_pattern_row_channel_command(), openmpt_module_format_pattern_row_channel_command() and openmpt_module_highlight_pattern_row_channel_command()
 

Classes

struct  openmpt_stream_callbacks
 Stream callbacks. More...
 
struct  openmpt_module_initial_ctl
 

Macros

#define OPENMPT_STRING_LIBRARY_VERSION   LIBOPENMPT_DEPRECATED_STRING( "library_version" )
 
#define OPENMPT_STRING_LIBRARY_FEATURES   LIBOPENMPT_DEPRECATED_STRING( "library_features" )
 
#define OPENMPT_STRING_CORE_VERSION   LIBOPENMPT_DEPRECATED_STRING( "core_version" )
 
#define OPENMPT_STRING_BUILD   LIBOPENMPT_DEPRECATED_STRING( "build" )
 
#define OPENMPT_STRING_CREDITS   LIBOPENMPT_DEPRECATED_STRING( "credits" )
 
#define OPENMPT_STRING_CONTACT   LIBOPENMPT_DEPRECATED_STRING( "contact" )
 
#define OPENMPT_STRING_LICENSE   LIBOPENMPT_DEPRECATED_STRING( "license" )
 
#define OPENMPT_STREAM_SEEK_SET   0
 
#define OPENMPT_STREAM_SEEK_CUR   1
 
#define OPENMPT_STREAM_SEEK_END   2
 
#define OPENMPT_ERROR_OK   0
 
#define OPENMPT_ERROR_BASE   256
 
#define OPENMPT_ERROR_UNKNOWN   ( OPENMPT_ERROR_BASE + 1 )
 
#define OPENMPT_ERROR_EXCEPTION   ( OPENMPT_ERROR_BASE + 11 )
 
#define OPENMPT_ERROR_OUT_OF_MEMORY   ( OPENMPT_ERROR_BASE + 21 )
 
#define OPENMPT_ERROR_RUNTIME   ( OPENMPT_ERROR_BASE + 30 )
 
#define OPENMPT_ERROR_RANGE   ( OPENMPT_ERROR_BASE + 31 )
 
#define OPENMPT_ERROR_OVERFLOW   ( OPENMPT_ERROR_BASE + 32 )
 
#define OPENMPT_ERROR_UNDERFLOW   ( OPENMPT_ERROR_BASE + 33 )
 
#define OPENMPT_ERROR_LOGIC   ( OPENMPT_ERROR_BASE + 40 )
 
#define OPENMPT_ERROR_DOMAIN   ( OPENMPT_ERROR_BASE + 41 )
 
#define OPENMPT_ERROR_LENGTH   ( OPENMPT_ERROR_BASE + 42 )
 
#define OPENMPT_ERROR_OUT_OF_RANGE   ( OPENMPT_ERROR_BASE + 43 )
 
#define OPENMPT_ERROR_INVALID_ARGUMENT   ( OPENMPT_ERROR_BASE + 44 )
 
#define OPENMPT_ERROR_GENERAL   ( OPENMPT_ERROR_BASE + 101 )
 
#define OPENMPT_ERROR_INVALID_MODULE_POINTER   ( OPENMPT_ERROR_BASE + 102 )
 
#define OPENMPT_ERROR_ARGUMENT_NULL_POINTER   ( OPENMPT_ERROR_BASE + 103 )
 
#define OPENMPT_ERROR_FUNC_RESULT_NONE   0
 
#define OPENMPT_ERROR_FUNC_RESULT_LOG   ( 1 << 0 )
 
#define OPENMPT_ERROR_FUNC_RESULT_STORE   ( 1 << 1 )
 
#define OPENMPT_ERROR_FUNC_RESULT_DEFAULT   ( OPENMPT_ERROR_FUNC_RESULT_LOG | OPENMPT_ERROR_FUNC_RESULT_STORE )
 
#define OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES   0x1ul
 
#define OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS   0x2ul
 
#define OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT   ( OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES | OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS )
 
#define OPENMPT_PROBE_FILE_HEADER_FLAGS_NONE   0x0ul
 
#define OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS   1
 
#define OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE   0
 
#define OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA   (-1)
 
#define OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR   (-255)
 

Typedefs

typedef size_t(* openmpt_stream_read_func) (void *stream, void *dst, size_t bytes)
 Read bytes from stream. More...
 
typedef int(* openmpt_stream_seek_func) (void *stream, int64_t offset, int whence)
 Seek stream position. More...
 
typedef int64_t(* openmpt_stream_tell_func) (void *stream)
 Tell stream position. More...
 
typedef struct openmpt_stream_callbacks openmpt_stream_callbacks
 Stream callbacks. More...
 
typedef void(* openmpt_log_func) (const char *message, void *user)
 Logging function. More...
 
typedef int(* openmpt_error_func) (int error, void *user)
 Error function. More...
 
typedef struct openmpt_module openmpt_module
 Opaque type representing a libopenmpt module. More...
 
typedef struct openmpt_module_initial_ctl openmpt_module_initial_ctl
 

Functions

uint32_t openmpt_get_library_version (void)
 Get the libopenmpt version number. More...
 
uint32_t openmpt_get_core_version (void)
 Get the core version number. More...
 
void openmpt_free_string (const char *str)
 Free a string returned by libopenmpt. More...
 
const char * openmpt_get_string (const char *key)
 Get library related metadata. More...
 
const char * openmpt_get_supported_extensions (void)
 Get a list of supported file extensions. More...
 
int openmpt_is_extension_supported (const char *extension)
 Query whether a file extension is supported. More...
 
void openmpt_log_func_default (const char *message, void *user)
 Default logging function. More...
 
void openmpt_log_func_silent (const char *message, void *user)
 Silent logging function. More...
 
int openmpt_error_is_transient (int error)
 Check whether the error is transient. More...
 
const char * openmpt_error_string (int error)
 Convert error code to text. More...
 
int openmpt_error_func_default (int error, void *user)
 Default error function. More...
 
int openmpt_error_func_log (int error, void *user)
 Log error function. More...
 
int openmpt_error_func_store (int error, void *user)
 Store error function. More...
 
int openmpt_error_func_ignore (int error, void *user)
 Ignore error function. More...
 
int openmpt_error_func_errno (int error, void *user)
 Errno error function. More...
 
void * openmpt_error_func_errno_userdata (int *error)
 User pointer for openmpt_error_func_errno. More...
 
double openmpt_could_open_probability (openmpt_stream_callbacks stream_callbacks, void *stream, double effort, openmpt_log_func logfunc, void *user)
 Roughly scan the input stream to find out whether libopenmpt might be able to open it. More...
 
double openmpt_could_open_propability (openmpt_stream_callbacks stream_callbacks, void *stream, double effort, openmpt_log_func logfunc, void *user)
 Roughly scan the input stream to find out whether libopenmpt might be able to open it. More...
 
double openmpt_could_open_probability2 (openmpt_stream_callbacks stream_callbacks, void *stream, double effort, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
 Roughly scan the input stream to find out whether libopenmpt might be able to open it. More...
 
size_t openmpt_probe_file_header_get_recommended_size (void)
 Get recommended header size for successfull format probing. More...
 
int openmpt_probe_file_header (uint64_t flags, const void *data, size_t size, uint64_t filesize, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
 Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it. More...
 
int openmpt_probe_file_header_without_filesize (uint64_t flags, const void *data, size_t size, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
 Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it. More...
 
int openmpt_probe_file_header_from_stream (uint64_t flags, openmpt_stream_callbacks stream_callbacks, void *stream, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
 Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it. More...
 
openmpt_moduleopenmpt_module_create (openmpt_stream_callbacks stream_callbacks, void *stream, openmpt_log_func logfunc, void *loguser, const openmpt_module_initial_ctl *ctls)
 Construct an openmpt_module. More...
 
openmpt_moduleopenmpt_module_create2 (openmpt_stream_callbacks stream_callbacks, void *stream, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message, const openmpt_module_initial_ctl *ctls)
 Construct an openmpt_module. More...
 
openmpt_moduleopenmpt_module_create_from_memory (const void *filedata, size_t filesize, openmpt_log_func logfunc, void *loguser, const openmpt_module_initial_ctl *ctls)
 Construct an openmpt_module. More...
 
openmpt_moduleopenmpt_module_create_from_memory2 (const void *filedata, size_t filesize, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message, const openmpt_module_initial_ctl *ctls)
 Construct an openmpt_module. More...
 
void openmpt_module_destroy (openmpt_module *mod)
 Unload a previously created openmpt_module from memory. More...
 
void openmpt_module_set_log_func (openmpt_module *mod, openmpt_log_func logfunc, void *loguser)
 Set logging function. More...
 
void openmpt_module_set_error_func (openmpt_module *mod, openmpt_error_func errfunc, void *erruser)
 Set error function. More...
 
int openmpt_module_error_get_last (openmpt_module *mod)
 Get last error. More...
 
const char * openmpt_module_error_get_last_message (openmpt_module *mod)
 Get last error message. More...
 
void openmpt_module_error_set_last (openmpt_module *mod, int error)
 Set last error. More...
 
void openmpt_module_error_clear (openmpt_module *mod)
 Clear last error. More...
 
int openmpt_module_select_subsong (openmpt_module *mod, int32_t subsong)
 Select a sub-song from a multi-song module. More...
 
int32_t openmpt_module_get_selected_subsong (openmpt_module *mod)
 Get currently selected sub-song from a multi-song module. More...
 
int openmpt_module_set_repeat_count (openmpt_module *mod, int32_t repeat_count)
 Set Repeat Count. More...
 
int32_t openmpt_module_get_repeat_count (openmpt_module *mod)
 Get Repeat Count. More...
 
double openmpt_module_get_duration_seconds (openmpt_module *mod)
 approximate song duration More...
 
double openmpt_module_set_position_seconds (openmpt_module *mod, double seconds)
 Set approximate current song position. More...
 
double openmpt_module_get_position_seconds (openmpt_module *mod)
 Get current song position. More...
 
double openmpt_module_set_position_order_row (openmpt_module *mod, int32_t order, int32_t row)
 Set approximate current song position. More...
 
int openmpt_module_get_render_param (openmpt_module *mod, int param, int32_t *value)
 Get render parameter. More...
 
int openmpt_module_set_render_param (openmpt_module *mod, int param, int32_t value)
 Set render parameter. More...
 
const char * openmpt_module_get_metadata_keys (openmpt_module *mod)
 Get the list of supported metadata item keys. More...
 
const char * openmpt_module_get_metadata (openmpt_module *mod, const char *key)
 Get a metadata item value. More...
 
int32_t openmpt_module_get_current_speed (openmpt_module *mod)
 Get the current speed. More...
 
int32_t openmpt_module_get_current_tempo (openmpt_module *mod)
 Get the current tempo. More...
 
int32_t openmpt_module_get_current_order (openmpt_module *mod)
 Get the current order. More...
 
int32_t openmpt_module_get_current_pattern (openmpt_module *mod)
 Get the current pattern. More...
 
int32_t openmpt_module_get_current_row (openmpt_module *mod)
 Get the current row. More...
 
int32_t openmpt_module_get_current_playing_channels (openmpt_module *mod)
 Get the current amount of playing channels. More...
 
float openmpt_module_get_current_channel_vu_mono (openmpt_module *mod, int32_t channel)
 Get an approximate indication of the channel volume. More...
 
float openmpt_module_get_current_channel_vu_left (openmpt_module *mod, int32_t channel)
 Get an approximate indication of the channel volume on the front-left speaker. More...
 
float openmpt_module_get_current_channel_vu_right (openmpt_module *mod, int32_t channel)
 Get an approximate indication of the channel volume on the front-right speaker. More...
 
float openmpt_module_get_current_channel_vu_rear_left (openmpt_module *mod, int32_t channel)
 Get an approximate indication of the channel volume on the rear-left speaker. More...
 
float openmpt_module_get_current_channel_vu_rear_right (openmpt_module *mod, int32_t channel)
 Get an approximate indication of the channel volume on the rear-right speaker. More...
 
int32_t openmpt_module_get_num_subsongs (openmpt_module *mod)
 Get the number of sub-songs. More...
 
int32_t openmpt_module_get_num_channels (openmpt_module *mod)
 Get the number of pattern channels. More...
 
int32_t openmpt_module_get_num_orders (openmpt_module *mod)
 Get the number of orders. More...
 
int32_t openmpt_module_get_num_patterns (openmpt_module *mod)
 Get the number of patterns. More...
 
int32_t openmpt_module_get_num_instruments (openmpt_module *mod)
 Get the number of instruments. More...
 
int32_t openmpt_module_get_num_samples (openmpt_module *mod)
 Get the number of samples. More...
 
const char * openmpt_module_get_subsong_name (openmpt_module *mod, int32_t index)
 Get a sub-song name. More...
 
const char * openmpt_module_get_channel_name (openmpt_module *mod, int32_t index)
 Get a channel name. More...
 
const char * openmpt_module_get_order_name (openmpt_module *mod, int32_t index)
 Get an order name. More...
 
const char * openmpt_module_get_pattern_name (openmpt_module *mod, int32_t index)
 Get a pattern name. More...
 
const char * openmpt_module_get_instrument_name (openmpt_module *mod, int32_t index)
 Get an instrument name. More...
 
const char * openmpt_module_get_sample_name (openmpt_module *mod, int32_t index)
 Get a sample name. More...
 
int32_t openmpt_module_get_order_pattern (openmpt_module *mod, int32_t order)
 Get pattern at order position. More...
 
int32_t openmpt_module_get_pattern_num_rows (openmpt_module *mod, int32_t pattern)
 Get the number of rows in a pattern. More...
 
uint8_t openmpt_module_get_pattern_row_channel_command (openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, int command)
 Get raw pattern content. More...
 
const char * openmpt_module_format_pattern_row_channel_command (openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, int command)
 Get formatted (human-readable) pattern content. More...
 
const char * openmpt_module_highlight_pattern_row_channel_command (openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, int command)
 Get highlighting information for formatted pattern content. More...
 
const char * openmpt_module_format_pattern_row_channel (openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, size_t width, int pad)
 Get formatted (human-readable) pattern content. More...
 
const char * openmpt_module_highlight_pattern_row_channel (openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, size_t width, int pad)
 Get highlighting information for formatted pattern content. More...
 
const char * openmpt_module_get_ctls (openmpt_module *mod)
 Retrieve supported ctl keys. More...
 
const char * openmpt_module_ctl_get (openmpt_module *mod, const char *ctl)
 Get current ctl value. More...
 
int openmpt_module_ctl_set (openmpt_module *mod, const char *ctl, const char *value)
 Set ctl value. More...
 
size_t openmpt_module_read_mono (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *mono)
 Render audio data. More...
 
size_t openmpt_module_read_stereo (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *left, int16_t *right)
 Render audio data. More...
 
size_t openmpt_module_read_quad (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *left, int16_t *right, int16_t *rear_left, int16_t *rear_right)
 Render audio data. More...
 
size_t openmpt_module_read_float_mono (openmpt_module *mod, int32_t samplerate, size_t count, float *mono)
 Render audio data. More...
 
size_t openmpt_module_read_float_stereo (openmpt_module *mod, int32_t samplerate, size_t count, float *left, float *right)
 Render audio data. More...
 
size_t openmpt_module_read_float_quad (openmpt_module *mod, int32_t samplerate, size_t count, float *left, float *right, float *rear_left, float *rear_right)
 Render audio data. More...
 
size_t openmpt_module_read_interleaved_stereo (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *interleaved_stereo)
 Render audio data. More...
 
size_t openmpt_module_read_interleaved_quad (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *interleaved_quad)
 Render audio data. More...
 
size_t openmpt_module_read_interleaved_float_stereo (openmpt_module *mod, int32_t samplerate, size_t count, float *interleaved_stereo)
 Render audio data. More...
 
size_t openmpt_module_read_interleaved_float_quad (openmpt_module *mod, int32_t samplerate, size_t count, float *interleaved_quad)
 Render audio data. More...
 

Detailed Description

Macro Definition Documentation

◆ OPENMPT_ERROR_ARGUMENT_NULL_POINTER

#define OPENMPT_ERROR_ARGUMENT_NULL_POINTER   ( OPENMPT_ERROR_BASE + 103 )

NULL pointer argument.

Since
0.3.0

◆ OPENMPT_ERROR_BASE

#define OPENMPT_ERROR_BASE   256

Lowest value libopenmpt will use for any of its own error codes.

Since
0.3.0

◆ OPENMPT_ERROR_DOMAIN

#define OPENMPT_ERROR_DOMAIN   ( OPENMPT_ERROR_BASE + 41 )

Value domain error.

Since
0.3.0

◆ OPENMPT_ERROR_EXCEPTION

#define OPENMPT_ERROR_EXCEPTION   ( OPENMPT_ERROR_BASE + 11 )

Unknown internal C++ exception.

Since
0.3.0

◆ OPENMPT_ERROR_FUNC_RESULT_DEFAULT

#define OPENMPT_ERROR_FUNC_RESULT_DEFAULT   ( OPENMPT_ERROR_FUNC_RESULT_LOG | OPENMPT_ERROR_FUNC_RESULT_STORE )

Log and store the error.

Since
0.3.0

◆ OPENMPT_ERROR_FUNC_RESULT_LOG

#define OPENMPT_ERROR_FUNC_RESULT_LOG   ( 1 << 0 )

Log the error.

Since
0.3.0

◆ OPENMPT_ERROR_FUNC_RESULT_NONE

#define OPENMPT_ERROR_FUNC_RESULT_NONE   0

Do not log or store the error.

Since
0.3.0

◆ OPENMPT_ERROR_FUNC_RESULT_STORE

#define OPENMPT_ERROR_FUNC_RESULT_STORE   ( 1 << 1 )

Store the error.

Since
0.3.0

◆ OPENMPT_ERROR_GENERAL

#define OPENMPT_ERROR_GENERAL   ( OPENMPT_ERROR_BASE + 101 )

General libopenmpt error.

Since
0.3.0

◆ OPENMPT_ERROR_INVALID_ARGUMENT

#define OPENMPT_ERROR_INVALID_ARGUMENT   ( OPENMPT_ERROR_BASE + 44 )

Invalid argument.

Since
0.3.0

◆ OPENMPT_ERROR_INVALID_MODULE_POINTER

#define OPENMPT_ERROR_INVALID_MODULE_POINTER   ( OPENMPT_ERROR_BASE + 102 )

openmpt_module * is invalid.

Since
0.3.0

◆ OPENMPT_ERROR_LENGTH

#define OPENMPT_ERROR_LENGTH   ( OPENMPT_ERROR_BASE + 42 )

Maximum supported size exceeded.

Since
0.3.0

◆ OPENMPT_ERROR_LOGIC

#define OPENMPT_ERROR_LOGIC   ( OPENMPT_ERROR_BASE + 40 )

Logic error.

Since
0.3.0

◆ OPENMPT_ERROR_OK

#define OPENMPT_ERROR_OK   0

No error.

Since
0.3.0

◆ OPENMPT_ERROR_OUT_OF_MEMORY

#define OPENMPT_ERROR_OUT_OF_MEMORY   ( OPENMPT_ERROR_BASE + 21 )

Out of memory.

Since
0.3.0

◆ OPENMPT_ERROR_OUT_OF_RANGE

#define OPENMPT_ERROR_OUT_OF_RANGE   ( OPENMPT_ERROR_BASE + 43 )

Argument out of range.

Since
0.3.0

◆ OPENMPT_ERROR_OVERFLOW

#define OPENMPT_ERROR_OVERFLOW   ( OPENMPT_ERROR_BASE + 32 )

Arithmetic overflow.

Since
0.3.0

◆ OPENMPT_ERROR_RANGE

#define OPENMPT_ERROR_RANGE   ( OPENMPT_ERROR_BASE + 31 )

Range error.

Since
0.3.0

◆ OPENMPT_ERROR_RUNTIME

#define OPENMPT_ERROR_RUNTIME   ( OPENMPT_ERROR_BASE + 30 )

Runtime error.

Since
0.3.0

◆ OPENMPT_ERROR_UNDERFLOW

#define OPENMPT_ERROR_UNDERFLOW   ( OPENMPT_ERROR_BASE + 33 )

Arithmetic underflow.

Since
0.3.0

◆ OPENMPT_ERROR_UNKNOWN

#define OPENMPT_ERROR_UNKNOWN   ( OPENMPT_ERROR_BASE + 1 )

Unknown internal error.

Since
0.3.0

◆ OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS

#define OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS   0x2ul

Probe for module-specific container formats in openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize().

Since
0.3.0

◆ OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT

#define OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT   ( OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES | OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS )

Probe for the default set of formats in openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize().

Since
0.3.0

◆ OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES

#define OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES   0x1ul

◆ OPENMPT_PROBE_FILE_HEADER_FLAGS_NONE

#define OPENMPT_PROBE_FILE_HEADER_FLAGS_NONE   0x0ul

◆ OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR

#define OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR   (-255)

◆ OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE

#define OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE   0

◆ OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS

#define OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS   1

◆ OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA

#define OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA   (-1)

◆ OPENMPT_STREAM_SEEK_CUR

#define OPENMPT_STREAM_SEEK_CUR   1

Seek to the given offset relative to the current position in the file.

◆ OPENMPT_STREAM_SEEK_END

#define OPENMPT_STREAM_SEEK_END   2

Seek to the given offset relative to the end of the file.

◆ OPENMPT_STREAM_SEEK_SET

#define OPENMPT_STREAM_SEEK_SET   0

Seek to the given offset relative to the beginning of the file.

◆ OPENMPT_STRING_BUILD

#define OPENMPT_STRING_BUILD   LIBOPENMPT_DEPRECATED_STRING( "build" )

Return information about the current build (e.g. the build date or compiler used) from openmpt_get_string().

Deprecated:
Please use "build" directly.

◆ OPENMPT_STRING_CONTACT

#define OPENMPT_STRING_CONTACT   LIBOPENMPT_DEPRECATED_STRING( "contact" )

Return contact information about libopenmpt from openmpt_get_string().

Deprecated:
Please use "contact" directly.

◆ OPENMPT_STRING_CORE_VERSION

#define OPENMPT_STRING_CORE_VERSION   LIBOPENMPT_DEPRECATED_STRING( "core_version" )

Return a verbose OpenMPT core version string from openmpt_get_string().

Deprecated:
Please use "core_version" directly.

◆ OPENMPT_STRING_CREDITS

#define OPENMPT_STRING_CREDITS   LIBOPENMPT_DEPRECATED_STRING( "credits" )

Return all contributors from openmpt_get_string().

Deprecated:
Please use "credits" directly.

◆ OPENMPT_STRING_LIBRARY_FEATURES

#define OPENMPT_STRING_LIBRARY_FEATURES   LIBOPENMPT_DEPRECATED_STRING( "library_features" )

Return a verbose library features string from openmpt_get_string().

Deprecated:
Please use "library_features" directly.

◆ OPENMPT_STRING_LIBRARY_VERSION

#define OPENMPT_STRING_LIBRARY_VERSION   LIBOPENMPT_DEPRECATED_STRING( "library_version" )

Return a verbose library version string from openmpt_get_string().

Deprecated:
Please use "library_version" directly.

◆ OPENMPT_STRING_LICENSE

#define OPENMPT_STRING_LICENSE   LIBOPENMPT_DEPRECATED_STRING( "license" )

Return the libopenmpt license from openmpt_get_string().

Deprecated:
Please use "license" directly.

Typedef Documentation

◆ openmpt_error_func

typedef int(* openmpt_error_func) (int error, void *user)

Error function.

Parameters
errorError code.
userUser context that was passed to openmpt_module_create2(), openmpt_module_create_from_memory2() or openmpt_could_open_probability2().
Returns
Mask of OPENMPT_ERROR_FUNC_RESULT_LOG and OPENMPT_ERROR_FUNC_RESULT_STORE.
Return values
OPENMPT_ERROR_FUNC_RESULT_NONEDo not log or store the error.
OPENMPT_ERROR_FUNC_RESULT_LOGLog the error.
OPENMPT_ERROR_FUNC_RESULT_STOREStore the error.
OPENMPT_ERROR_FUNC_RESULT_DEFAULTLog and store the error.
See also
OPENMPT_ERROR_FUNC_RESULT_NONE
OPENMPT_ERROR_FUNC_RESULT_LOG
OPENMPT_ERROR_FUNC_RESULT_STORE
OPENMPT_ERROR_FUNC_RESULT_DEFAULT
openmpt_error_func_default
openmpt_error_func_log
openmpt_error_func_store
openmpt_error_func_ignore
openmpt_error_func_errno
Since
0.3.0

◆ openmpt_log_func

typedef void(* openmpt_log_func) (const char *message, void *user)

Logging function.

Parameters
messageUTF-8 encoded log message.
userUser context that was passed to openmpt_module_create2(), openmpt_module_create_from_memory2() or openmpt_could_open_probability2().

◆ openmpt_module

Opaque type representing a libopenmpt module.

◆ openmpt_module_initial_ctl

◆ openmpt_stream_callbacks

Stream callbacks.

Stream callbacks used by libopenmpt for stream operations.

◆ openmpt_stream_read_func

typedef size_t(* openmpt_stream_read_func) (void *stream, void *dst, size_t bytes)

Read bytes from stream.

Read bytes data from stream to dst.

Parameters
streamStream to read data from
dstTarget where to copy data.
bytesNumber of bytes to read.
Returns
Number of bytes actually read and written to dst.
Return values
0End of stream or error.
Remarks
Short reads are allowed as long as they return at least 1 byte if EOF is not reached.

◆ openmpt_stream_seek_func

typedef int(* openmpt_stream_seek_func) (void *stream, int64_t offset, int whence)

Seek stream position.

Seek to stream position offset at whence.

Parameters
streamStream to operate on.
offsetOffset to seek to.
whenceOPENMPT_STREAM_SEEK_SET, OPENMPT_STREAM_SEEK_CUR, OPENMPT_STREAM_SEEK_END. See C89 documentation.
Returns
Returns 0 on success.
Return values
0Success.
-1Failure. Position does not get updated.
Remarks
libopenmpt will not try to seek beyond the file size, thus it is not important whether you allow for virtual positioning after the file end, or return an error in that case. The position equal to the file size needs to be seekable to.

◆ openmpt_stream_tell_func

typedef int64_t(* openmpt_stream_tell_func) (void *stream)

Tell stream position.

Tell position of stream.

Parameters
streamStream to operate on.
Returns
Current position in stream.
Return values
-1Failure.

Function Documentation

◆ openmpt_could_open_probability()

double openmpt_could_open_probability ( openmpt_stream_callbacks  stream_callbacks,
void *  stream,
double  effort,
openmpt_log_func  logfunc,
void *  user 
)

Roughly scan the input stream to find out whether libopenmpt might be able to open it.

Parameters
stream_callbacksInput stream callback operations.
streamInput stream to scan.
effortEffort to make when validating stream. Effort 0.0 does not even look at stream at all and effort 1.0 completely loads the file from stream. A lower effort requires less data to be loaded but only gives a rough estimate answer. Use an effort of 0.25 to only verify the header data of the module file.
logfuncLogging function where warning and errors are written. May be NULL.
userLogging function user context. Used to pass any user-defined data associated with this module to the logging function.
Returns
Probability between 0.0 and 1.0.
Remarks
openmpt_could_open_probability() can return any value between 0.0 and 1.0. Only 0.0 and 1.0 are definitive answers, all values in between are just estimates. In general, any return value >0.0 means that you should try loading the file, and any value below 1.0 means that loading may fail. If you want a threshold above which you can be reasonably sure that libopenmpt will be able to load the file, use >=0.5. If you see the need for a threshold below which you could reasonably outright reject a file, use <0.25 (Note: Such a threshold for rejecting on the lower end is not recommended, but may be required for better integration into some other framework's probe scoring.).
openmpt_could_open_probability() expects the complete file data to be eventually available to it, even if it is asked to just parse the header. Verification will be unreliable (both false positives and false negatives), if you pretend that the file is just some few bytes of initial data threshold in size. In order to really just access the first bytes of a file, check in your callback functions whether data or seeking is requested beyond your initial data threshold, and in that case, return an error. openmpt_could_open_probability() will treat this as any other I/O error and return 0.0. You must not expect the correct result in this case. You instead must remember that it asked for more data than you currently want to provide to it and treat this situation as if openmpt_could_open_probability() returned 0.5.
See also
File I/O
openmpt_stream_callbacks
Deprecated:
Please use openmpt_could_open_probability2().
Since
0.3.0

◆ openmpt_could_open_probability2()

double openmpt_could_open_probability2 ( openmpt_stream_callbacks  stream_callbacks,
void *  stream,
double  effort,
openmpt_log_func  logfunc,
void *  loguser,
openmpt_error_func  errfunc,
void *  erruser,
int *  error,
const char **  error_message 
)

Roughly scan the input stream to find out whether libopenmpt might be able to open it.

Parameters
stream_callbacksInput stream callback operations.
streamInput stream to scan.
effortEffort to make when validating stream. Effort 0.0 does not even look at stream at all and effort 1.0 completely loads the file from stream. A lower effort requires less data to be loaded but only gives a rough estimate answer. Use an effort of 0.25 to only verify the header data of the module file.
logfuncLogging function where warning and errors are written. May be NULL.
loguserLogging function user context. Used to pass any user-defined data associated with this module to the logging function.
errfuncError function to define error behaviour. May be NULL.
erruserError function user context. Used to pass any user-defined data associated with this module to the logging function.
errorPointer to an integer where an error may get stored. May be NULL.
error_messagePointer to a string pointer where an error message may get stored. May be NULL.
Returns
Probability between 0.0 and 1.0.
Remarks
openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize() provide a simpler and faster interface that fits almost all use cases better. It is recommended to use openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize() instead of openmpt_could_open_probability().
openmpt_could_open_probability2() can return any value between 0.0 and 1.0. Only 0.0 and 1.0 are definitive answers, all values in between are just estimates. In general, any return value >0.0 means that you should try loading the file, and any value below 1.0 means that loading may fail. If you want a threshold above which you can be reasonably sure that libopenmpt will be able to load the file, use >=0.5. If you see the need for a threshold below which you could reasonably outright reject a file, use <0.25 (Note: Such a threshold for rejecting on the lower end is not recommended, but may be required for better integration into some other framework's probe scoring.).
openmpt_could_open_probability2() expects the complete file data to be eventually available to it, even if it is asked to just parse the header. Verification will be unreliable (both false positives and false negatives), if you pretend that the file is just some few bytes of initial data threshold in size. In order to really just access the first bytes of a file, check in your callback functions whether data or seeking is requested beyond your initial data threshold, and in that case, return an error. openmpt_could_open_probability2() will treat this as any other I/O error and return 0.0. You must not expect the correct result in this case. You instead must remember that it asked for more data than you currently want to provide to it and treat this situation as if openmpt_could_open_probability2() returned 0.5.
/*
* libopenmpt_example_c_probe.c
* ----------------------------
* Purpose: libopenmpt C API probing example
* Notes : (currently none)
* Authors: OpenMPT Devs
* The OpenMPT source code is released under the BSD license. Read LICENSE for more details.
*/
/*
* Usage: libopenmpt_example_c_probe SOMEMODULE ...
* Returns 0 on successful probing for all files.
* Returns 1 on failed probing for 1 or more files.
* Returns 2 on error.
*/
#define LIBOPENMPT_EXAMPLE_PROBE_RESULT_BINARY 1
#define LIBOPENMPT_EXAMPLE_PROBE_RESULT_FLOAT 2
#define LIBOPENMPT_EXAMPLE_PROBE_RESULT LIBOPENMPT_EXAMPLE_PROBE_RESULT_BINARY
#include <memory.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
static void libopenmpt_example_logfunc( const char * message, void * userdata ) {
(void)userdata;
if ( message ) {
fprintf( stderr, "%s\n", message );
}
}
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
static int probe_file( const wchar_t * filename ) {
#else
static int probe_file( const char * filename ) {
#endif
int result = 0;
int mod_err = OPENMPT_ERROR_OK;
FILE * file = NULL;
#if ( LIBOPENMPT_EXAMPLE_PROBE_RESULT == LIBOPENMPT_EXAMPLE_PROBE_RESULT_BINARY )
int result_binary = 0;
const char * probe_file_header_result_str = NULL;
#endif
#if ( LIBOPENMPT_EXAMPLE_PROBE_RESULT == LIBOPENMPT_EXAMPLE_PROBE_RESULT_FLOAT )
double probability = 0.0;
#endif
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
if ( wcslen( filename ) == 0 ) {
fprintf( stderr, "Error: %s\n", "Wrong invocation. Use 'libopenmpt_example_c_probe SOMEMODULE'." );
goto fail;
}
#else
if ( strlen( filename ) == 0 ) {
fprintf( stderr, "Error: %s\n", "Wrong invocation. Use 'libopenmpt_example_c_probe SOMEMODULE'." );
goto fail;
}
#endif
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
file = _wfopen( filename, L"rb" );
#else
file = fopen( filename, "rb" );
#endif
if ( !file ) {
fprintf( stderr, "Error: %s\n", "fopen() failed." );
goto fail;
}
#if ( LIBOPENMPT_EXAMPLE_PROBE_RESULT == LIBOPENMPT_EXAMPLE_PROBE_RESULT_BINARY )
probe_file_header_result = openmpt_probe_file_header_from_stream( OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT, openmpt_stream_get_file_callbacks(), file, &libopenmpt_example_logfunc, NULL, &openmpt_error_func_default, NULL, &mod_err, NULL );
probe_file_header_result_str = NULL;
result_binary = 0;
switch ( probe_file_header_result ) {
probe_file_header_result_str = "Success ";
result_binary = 1;
break;
probe_file_header_result_str = "Failure ";
result_binary = 0;
break;
probe_file_header_result_str = "WantMoreData";
result_binary = 0;
break;
result_binary = 0;
fprintf( stderr, "Error: %s\n", "openmpt_probe_file_header() failed." );
goto fail;
break;
default:
result_binary = 0;
fprintf( stderr, "Error: %s\n", "openmpt_probe_file_header() failed." );
goto fail;
break;
}
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
fprintf( stdout, "%s - %ls\n", probe_file_header_result_str, filename );
#else
fprintf( stdout, "%s - %s\n", probe_file_header_result_str, filename );
#endif
if ( result_binary ) {
result = 0;
} else {
result = 1;
}
#elif ( LIBOPENMPT_EXAMPLE_PROBE_RESULT == LIBOPENMPT_EXAMPLE_PROBE_RESULT_FLOAT )
probability = openmpt_could_open_probability2( openmpt_stream_get_file_callbacks(), file, 0.25, &libopenmpt_example_logfunc, NULL, &openmpt_error_func_default, NULL, &mod_err, NULL );
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
fprintf( stdout, "%s: %f - %ls\n", "Result", probability, filename );
#else
fprintf( stdout, "%s: %f - %s\n", "Result", probability, filename );
#endif
if ( probability >= 0.5 ) {
result = 0;
} else {
result = 1;
}
#else
#error "LIBOPENMPT_EXAMPLE_PROBE_RESULT is wrong"
#endif
goto cleanup;
fail:
result = 2;
cleanup:
if ( file ) {
fclose( file );
file = 0;
}
return result;
}
#if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
int wmain( int argc, wchar_t * argv[] ) {
#else
int main( int argc, char * argv[] ) {
#endif
int global_result = 0;
if ( argc <= 1 ) {
fprintf( stderr, "Error: %s\n", "Wrong invocation. Use 'libopenmpt_example_c_probe SOMEMODULE ...'." );
goto fail;
}
for ( int i = 1; i < argc; ++i ) {
int result = probe_file( argv[i] );
if ( result > global_result ) {
global_result = result;
}
}
goto cleanup;
fail:
global_result = 2;
cleanup:
return global_result;
}
See also
File I/O
openmpt_stream_callbacks
openmpt_probe_file_header
openmpt_probe_file_header_without_filesize
Since
0.3.0

◆ openmpt_could_open_propability()

double openmpt_could_open_propability ( openmpt_stream_callbacks  stream_callbacks,
void *  stream,
double  effort,
openmpt_log_func  logfunc,
void *  user 
)

Roughly scan the input stream to find out whether libopenmpt might be able to open it.

Parameters
stream_callbacksInput stream callback operations.
streamInput stream to scan.
effortEffort to make when validating stream. Effort 0.0 does not even look at stream at all and effort 1.0 completely loads the file from stream. A lower effort requires less data to be loaded but only gives a rough estimate answer. Use an effort of 0.25 to only verify the header data of the module file.
logfuncLogging function where warning and errors are written. May be NULL.
userLogging function user context. Used to pass any user-defined data associated with this module to the logging function.
Returns
Probability between 0.0 and 1.0.
Remarks
openmpt_could_open_probability() can return any value between 0.0 and 1.0. Only 0.0 and 1.0 are definitive answers, all values in between are just estimates. In general, any return value >0.0 means that you should try loading the file, and any value below 1.0 means that loading may fail. If you want a threshold above which you can be reasonably sure that libopenmpt will be able to load the file, use >=0.5. If you see the need for a threshold below which you could reasonably outright reject a file, use <0.25 (Note: Such a threshold for rejecting on the lower end is not recommended, but may be required for better integration into some other framework's probe scoring.).
openmpt_could_open_probability() expects the complete file data to be eventually available to it, even if it is asked to just parse the header. Verification will be unreliable (both false positives and false negatives), if you pretend that the file is just some few bytes of initial data threshold in size. In order to really just access the first bytes of a file, check in your callback functions whether data or seeking is requested beyond your initial data threshold, and in that case, return an error. openmpt_could_open_probability() will treat this as any other I/O error and return 0.0. You must not expect the correct result in this case. You instead must remember that it asked for more data than you currently want to provide to it and treat this situation as if openmpt_could_open_probability() returned 0.5.
See also
File I/O
openmpt_stream_callbacks
Deprecated:
Please use openmpt_could_open_probability2().

◆ openmpt_error_func_default()

int openmpt_error_func_default ( int  error,
void *  user 
)

Default error function.

Causes all errors to be logged and stored.

Parameters
errorError code.
userIgnored.
Return values
OPENMPT_ERROR_FUNC_RESULT_DEFAULTAlways.
Since
0.3.0

◆ openmpt_error_func_errno()

int openmpt_error_func_errno ( int  error,
void *  user 
)

Errno error function.

Causes all errors to be stored in the pointer passed in as user.

Parameters
errorError code.
userPointer to an int as generated by openmpt_error_func_errno_userdata.
Return values
OPENMPT_ERROR_FUNC_RESULT_NONEuser is not NULL.
OPENMPT_ERROR_FUNC_RESULT_DEFAULTuser is NULL.
Since
0.3.0

◆ openmpt_error_func_errno_userdata()

void* openmpt_error_func_errno_userdata ( int *  error)

User pointer for openmpt_error_func_errno.

Provides a suitable user pointer argument for openmpt_error_func_errno.

Parameters
errorPointer to an integer value to be used as output by openmpt_error_func_errno.
Return values
(void*)error.
Since
0.3.0

◆ openmpt_error_func_ignore()

int openmpt_error_func_ignore ( int  error,
void *  user 
)

Ignore error function.

Causes all errors to be neither logged nor stored.

Parameters
errorError code.
userIgnored.
Return values
OPENMPT_ERROR_FUNC_RESULT_NONEAlways.
Since
0.3.0

◆ openmpt_error_func_log()

int openmpt_error_func_log ( int  error,
void *  user 
)

Log error function.

Causes all errors to be logged.

Parameters
errorError code.
userIgnored.
Return values
OPENMPT_ERROR_FUNC_RESULT_LOGAlways.
Since
0.3.0

◆ openmpt_error_func_store()

int openmpt_error_func_store ( int  error,
void *  user 
)

Store error function.

Causes all errors to be stored.

Parameters
errorError code.
userIgnored.
Return values
OPENMPT_ERROR_FUNC_RESULT_STOREAlways.
Since
0.3.0

◆ openmpt_error_is_transient()

int openmpt_error_is_transient ( int  error)

Check whether the error is transient.

Checks whether an error code represents a transient error which may not occur again in a later try if for example memory has been freed up after an out-of-memory error.

Parameters
errorError code.
Return values
0Error is not transient.
1Error is transient.
See also
OPENMPT_ERROR_OUT_OF_MEMORY
Since
0.3.0

◆ openmpt_error_string()

const char* openmpt_error_string ( int  error)

Convert error code to text.

Converts an error code into a text string describing the error.

Parameters
errorError code.
Returns
Allocated string describing the error.
Return values
NULLNot enough memory to allocate the string.
Since
0.3.0

◆ openmpt_free_string()

void openmpt_free_string ( const char *  str)

Free a string returned by libopenmpt.

Frees any string that got returned by libopenmpt.

◆ openmpt_get_core_version()

uint32_t openmpt_get_core_version ( void  )

Get the core version number.

Return the OpenMPT core version number.

Returns
The value represents (majormajor << 24 + major << 16 + minor << 8 + minorminor).

◆ openmpt_get_library_version()

uint32_t openmpt_get_library_version ( void  )

Get the libopenmpt version number.

Returns the libopenmpt version number.

Returns
The value represents (major << 24 + minor << 16 + patch << 0).
Remarks
libopenmpt < 0.3.0-pre used the following scheme: (major << 24 + minor << 16 + revision).

◆ openmpt_get_string()

const char* openmpt_get_string ( const char *  key)

Get library related metadata.

Parameters
keyKey to query. Possible keys are:
  • "library_version": verbose library version string
  • "library_version_is_release": "1" if the version is an officially released version
  • "library_features": verbose library features string
  • "core_version": verbose OpenMPT core version string
  • "source_url": original source code URL
  • "source_date": original source code date
  • "source_revision": original source code revision
  • "source_is_modified": "1" if the original source has been modified
  • "source_has_mixed_revisions": "1" if the original source has been compiled from different various revision
  • "source_is_package": "1" if the original source has been obtained from a source pacakge instead of source code version control
  • "build": information about the current build (e.g. the build date or compiler used)
  • "build_compiler": information about the compiler used to build libopenmpt
  • "credits": all contributors
  • "contact": contact information about libopenmpt
  • "license": the libopenmpt license
  • "url": libopenmpt website URL
  • "support_forum_url": libopenmpt support and discussions forum URL
  • "bugtracker_url": libopenmpt bug and issue tracker URL
Returns
A (possibly multi-line) string containing the queried information. If no information is available, the string is empty.

◆ openmpt_get_supported_extensions()

const char* openmpt_get_supported_extensions ( void  )

Get a list of supported file extensions.

Returns
The semicolon-separated list of extensions supported by this libopenmpt build. The extensions are returned lower-case without a leading dot.

◆ openmpt_is_extension_supported()

int openmpt_is_extension_supported ( const char *  extension)

Query whether a file extension is supported.

Parameters
extensionfile extension to query without a leading dot. The case is ignored.
Returns
1 if the extension is supported by libopenmpt, 0 otherwise.

◆ openmpt_log_func_default()

void openmpt_log_func_default ( const char *  message,
void *  user 
)

Default logging function.

Default logging function that logs anything to stderr.

◆ openmpt_log_func_silent()

void openmpt_log_func_silent ( const char *  message,
void *  user 
)

Silent logging function.

Silent logging function that throws any log message away.

◆ openmpt_module_create()

openmpt_module* openmpt_module_create ( openmpt_stream_callbacks  stream_callbacks,
void *  stream,
openmpt_log_func  logfunc,
void *  loguser,
const openmpt_module_initial_ctl ctls 
)

Construct an openmpt_module.

Parameters
stream_callbacksInput stream callback operations.
streamInput stream to load the module from.
logfuncLogging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module. May be NULL.
loguserUser-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
ctlsA map of initial ctl values. See openmpt_module_get_ctls()
Returns
A pointer to the constructed openmpt_module, or NULL on failure.
Remarks
The input data can be discarded after an openmpt_module has been constructed successfully.
See also
openmpt_stream_callbacks
File I/O
Deprecated:
Please use openmpt_module_create2().

◆ openmpt_module_create2()

openmpt_module* openmpt_module_create2 ( openmpt_stream_callbacks  stream_callbacks,
void *  stream,
openmpt_log_func  logfunc,
void *  loguser,
openmpt_error_func  errfunc,
void *  erruser,
int *  error,
const char **  error_message,
const openmpt_module_initial_ctl ctls 
)

Construct an openmpt_module.

Parameters
stream_callbacksInput stream callback operations.
streamInput stream to load the module from.
logfuncLogging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module. May be NULL.
loguserUser-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
errfuncError function to define error behaviour. May be NULL.
erruserError function user context. Used to pass any user-defined data associated with this module to the logging function.
errorPointer to an integer where an error may get stored. May be NULL.
error_messagePointer to a string pointer where an error message may get stored. May be NULL.
ctlsA map of initial ctl values. See openmpt_module_get_ctls()
Returns
A pointer to the constructed openmpt_module, or NULL on failure.
Remarks
The input data can be discarded after an openmpt_module has been constructed successfully.
See also
openmpt_stream_callbacks
File I/O
Since
0.3.0

◆ openmpt_module_create_from_memory()

openmpt_module* openmpt_module_create_from_memory ( const void *  filedata,
size_t  filesize,
openmpt_log_func  logfunc,
void *  loguser,
const openmpt_module_initial_ctl ctls 
)

Construct an openmpt_module.

Parameters
filedataData to load the module from.
filesizeAmount of data available.
logfuncLogging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module.
loguserUser-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
ctlsA map of initial ctl values. See openmpt_module_get_ctls()
Returns
A pointer to the constructed openmpt_module, or NULL on failure.
Remarks
The input data can be discarded after an openmpt_module has been constructed successfully.
See also
File I/O
Deprecated:
Please use openmpt_module_create_from_memory2().

◆ openmpt_module_create_from_memory2()

openmpt_module* openmpt_module_create_from_memory2 ( const void *  filedata,
size_t  filesize,
openmpt_log_func  logfunc,
void *  loguser,
openmpt_error_func  errfunc,
void *  erruser,
int *  error,
const char **  error_message,
const openmpt_module_initial_ctl ctls 
)

Construct an openmpt_module.

Parameters
filedataData to load the module from.
filesizeAmount of data available.
logfuncLogging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module.
loguserUser-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
errfuncError function to define error behaviour. May be NULL.
erruserError function user context. Used to pass any user-defined data associated with this module to the logging function.
errorPointer to an integer where an error may get stored. May be NULL.
error_messagePointer to a string pointer where an error message may get stored. May be NULL.
ctlsA map of initial ctl values. See openmpt_module_get_ctls()
Returns
A pointer to the constructed openmpt_module, or NULL on failure.
Remarks
The input data can be discarded after an openmpt_module has been constructed successfully.
See also
File I/O
Since
0.3.0

◆ openmpt_module_ctl_get()

const char* openmpt_module_ctl_get ( openmpt_module mod,
const char *  ctl 
)

Get current ctl value.

Parameters
modThe module handle to work on.
ctlThe ctl key whose value should be retrieved.
Returns
The associated ctl value, or NULL on failure.
See also
openmpt_module_get_ctls

◆ openmpt_module_ctl_set()

int openmpt_module_ctl_set ( openmpt_module mod,
const char *  ctl,
const char *  value 
)

Set ctl value.

Parameters
modThe module handle to work on.
ctlThe ctl key whose value should be set.
valueThe value that should be set.
Returns
1 if successful, 0 in case the value is not sensible (e.g. negative tempo factor) or the ctl is not recognized.
See also
openmpt_module_get_ctls

◆ openmpt_module_destroy()

void openmpt_module_destroy ( openmpt_module mod)

Unload a previously created openmpt_module from memory.

Parameters
modThe module to unload.

◆ openmpt_module_error_clear()

void openmpt_module_error_clear ( openmpt_module mod)

Clear last error.

Set the error currently stored in an openmpt_module to OPPENMPT_ERROR_OK.

Parameters
modThe module handle to work on.
See also
openmpt_module_error_get_last
openmpt_module_error_set_last
Since
0.3.0

◆ openmpt_module_error_get_last()

int openmpt_module_error_get_last ( openmpt_module mod)

Get last error.

Return the error currently stored in an openmpt_module. The stored error is not cleared.

Parameters
modThe module handle to work on.
Returns
The error currently stored.
See also
openmpt_module_error_get_last_message
openmpt_module_error_set_last
openmpt_module_error_clear
Since
0.3.0

◆ openmpt_module_error_get_last_message()

const char* openmpt_module_error_get_last_message ( openmpt_module mod)

Get last error message.

Return the error message currently stored in an openmpt_module. The stored error is not cleared.

Parameters
modThe module handle to work on.
Returns
The error message currently stored.
See also
openmpt_module_error_set_last
openmpt_module_error_clear
Since
0.3.0

◆ openmpt_module_error_set_last()

void openmpt_module_error_set_last ( openmpt_module mod,
int  error 
)

Set last error.

Set the error currently stored in an openmpt_module.

Parameters
modThe module handle to work on.
errorError to be stored.
See also
openmpt_module_error_get_last
openmpt_module_error_clear
Since
0.3.0

◆ openmpt_module_format_pattern_row_channel()

const char* openmpt_module_format_pattern_row_channel ( openmpt_module mod,
int32_t  pattern,
int32_t  row,
int32_t  channel,
size_t  width,
int  pad 
)

Get formatted (human-readable) pattern content.

Parameters
modThe module handle to work on.
patternThe pattern whose data should be retrieved.
rowThe row from which the data should be retrieved.
channelThe channel from which the data should be retrieved.
widthThe maximum number of characters the string should contain. 0 means no limit.
padIf true, the string will be resized to the exact length provided in the width parameter.
Returns
The formatted pattern data at the given pattern position.
See also
openmpt_module_highlight_pattern_row_channel

◆ openmpt_module_format_pattern_row_channel_command()

const char* openmpt_module_format_pattern_row_channel_command ( openmpt_module mod,
int32_t  pattern,
int32_t  row,
int32_t  channel,
int  command 
)

Get formatted (human-readable) pattern content.

Parameters
modThe module handle to work on.
patternThe pattern whose data should be retrieved.
rowThe row from which the data should be retrieved.
channelThe channel from which the data should be retrieved.
commandThe cell index at which the data should be retrieved.
Returns
The formatted pattern data at the given pattern position. See Pattern cell indices
See also
openmpt_module_highlight_pattern_row_channel_command

◆ openmpt_module_get_channel_name()

const char* openmpt_module_get_channel_name ( openmpt_module mod,
int32_t  index 
)

Get a channel name.

Parameters
modThe module handle to work on.
indexThe channel whose name should be retrieved
Returns
The channel name.
See also
openmpt_module_get_num_channels

◆ openmpt_module_get_ctls()

const char* openmpt_module_get_ctls ( openmpt_module mod)

Retrieve supported ctl keys.

Parameters
modThe module handle to work on.
Returns
A semicolon-separated list containing all supported ctl keys.
Remarks
Currently supported ctl values are:
  • load.skip_samples: Set to "1" to avoid loading samples into memory
  • load.skip_patterns: Set to "1" to avoid loading patterns into memory
  • load.skip_plugins: Set to "1" to avoid loading plugins
  • load.skip_subsongs_init: Set to "1" to avoid pre-initializing sub-songs. Skipping results in faster module loading but slower seeking.
  • seek.sync_samples: Set to "1" to sync sample playback when using openmpt_module_set_position_seconds or openmpt_module_set_position_order_row.
  • subsong: The current subsong. Setting it has identical semantics as openmpt_module_select_subsong(), getting it returns the currently selected subsong.
  • play.tempo_factor: Set a floating point tempo factor. "1.0" is the default tempo.
  • play.pitch_factor: Set a floating point pitch factor. "1.0" is the default pitch.
  • render.resampler.emulate_amiga: Set to "1" to enable the Amiga resampler for Amiga modules. This emulates the sound characteristics of the Paula chip and overrides the selected interpolation filter. Non-Amiga module formats are not affected by this setting.
  • dither: Set the dither algorithm that is used for the 16 bit versions of openmpt_module_read. Supported values are:
    • 0: No dithering.
    • 1: Default mode. Chosen by OpenMPT code, might change.
    • 2: Rectangular, 0.5 bit depth, no noise shaping (original ModPlug Tracker).
    • 3: Rectangular, 1 bit depth, simple 1st order noise shaping

◆ openmpt_module_get_current_channel_vu_left()

float openmpt_module_get_current_channel_vu_left ( openmpt_module mod,
int32_t  channel 
)

Get an approximate indication of the channel volume on the front-left speaker.

Parameters
modThe module handle to work on.
channelThe channel whose volume should be retrieved.
Returns
The approximate channel volume.
Remarks
The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

◆ openmpt_module_get_current_channel_vu_mono()

float openmpt_module_get_current_channel_vu_mono ( openmpt_module mod,
int32_t  channel 
)

Get an approximate indication of the channel volume.

Parameters
modThe module handle to work on.
channelThe channel whose volume should be retrieved.
Returns
The approximate channel volume.
Remarks
The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

◆ openmpt_module_get_current_channel_vu_rear_left()

float openmpt_module_get_current_channel_vu_rear_left ( openmpt_module mod,
int32_t  channel 
)

Get an approximate indication of the channel volume on the rear-left speaker.

Parameters
modThe module handle to work on.
channelThe channel whose volume should be retrieved.
Returns
The approximate channel volume.
Remarks
The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

◆ openmpt_module_get_current_channel_vu_rear_right()

float openmpt_module_get_current_channel_vu_rear_right ( openmpt_module mod,
int32_t  channel 
)

Get an approximate indication of the channel volume on the rear-right speaker.

Parameters
modThe module handle to work on.
channelThe channel whose volume should be retrieved.
Returns
The approximate channel volume.
Remarks
The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

◆ openmpt_module_get_current_channel_vu_right()

float openmpt_module_get_current_channel_vu_right ( openmpt_module mod,
int32_t  channel 
)

Get an approximate indication of the channel volume on the front-right speaker.

Parameters
modThe module handle to work on.
channelThe channel whose volume should be retrieved.
Returns
The approximate channel volume.
Remarks
The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

◆ openmpt_module_get_current_order()

int32_t openmpt_module_get_current_order ( openmpt_module mod)

Get the current order.

Parameters
modThe module handle to work on.
Returns
The current order at which the module is being played back.

◆ openmpt_module_get_current_pattern()

int32_t openmpt_module_get_current_pattern ( openmpt_module mod)

Get the current pattern.

Parameters
modThe module handle to work on.
Returns
The current pattern that is being played.

◆ openmpt_module_get_current_playing_channels()

int32_t openmpt_module_get_current_playing_channels ( openmpt_module mod)

Get the current amount of playing channels.

Parameters
modThe module handle to work on.
Returns
The amount of sample channels that are currently being rendered.

◆ openmpt_module_get_current_row()

int32_t openmpt_module_get_current_row ( openmpt_module mod)

Get the current row.

Parameters
modThe module handle to work on.
Returns
The current row at which the current pattern is being played.

◆ openmpt_module_get_current_speed()

int32_t openmpt_module_get_current_speed ( openmpt_module mod)

Get the current speed.

Parameters
modThe module handle to work on.
Returns
The current speed in ticks per row.

◆ openmpt_module_get_current_tempo()

int32_t openmpt_module_get_current_tempo ( openmpt_module mod)

Get the current tempo.

Parameters
modThe module handle to work on.
Returns
The current tempo in tracker units. The exact meaning of this value depends on the tempo mode being used.

◆ openmpt_module_get_duration_seconds()

double openmpt_module_get_duration_seconds ( openmpt_module mod)

approximate song duration

Parameters
modThe module handle to work on.
Returns
Approximate duration of current sub-song in seconds.

◆ openmpt_module_get_instrument_name()

const char* openmpt_module_get_instrument_name ( openmpt_module mod,
int32_t  index 
)

Get an instrument name.

Parameters
modThe module handle to work on.
indexThe instrument whose name should be retrieved
Returns
The instrument name.
See also
openmpt_module_get_num_instruments

◆ openmpt_module_get_metadata()

const char* openmpt_module_get_metadata ( openmpt_module mod,
const char *  key 
)

Get a metadata item value.

Parameters
modThe module handle to work on.
keyMetadata item key to query. Use openmpt_module_get_metadata_keys to check for available keys. Possible keys are:
  • type: Module format extension (e.g. it)
  • type_long: Tracker name associated with the module format (e.g. Impulse Tracker)
  • container: Container format the module file is embedded in, if any (e.g. umx)
  • container_long: Full container name if the module is embedded in a container (e.g. Unreal Music)
  • tracker: Tracker that was (most likely) used to save the module file, if known
  • artist: Author of the module
  • title: Module title
  • date: Date the module was last saved, in ISO-8601 format.
  • message: Song message. If the song message is empty or the module format does not support song messages, a list of instrument and sample names is returned instead.
  • message_raw: Song message. If the song message is empty or the module format does not support song messages, an empty string is returned.
  • warnings: A list of warnings that were generated while loading the module.
Returns
The associated value for key.
See also
openmpt_module_get_metadata_keys

◆ openmpt_module_get_metadata_keys()

const char* openmpt_module_get_metadata_keys ( openmpt_module mod)

Get the list of supported metadata item keys.

Parameters
modThe module handle to work on.
Returns
Metadata item keys supported by openmpt_module_get_metadata, as a semicolon-separated list.
See also
openmpt_module_get_metadata

◆ openmpt_module_get_num_channels()

int32_t openmpt_module_get_num_channels ( openmpt_module mod)

Get the number of pattern channels.

Parameters
modThe module handle to work on.
Returns
The number of pattern channels in the module. Not all channels do necessarily contain data.
Remarks
The number of pattern channels is completely independent of the number of output channels. libopenmpt can render modules in mono, stereo or quad surround, but the choice of which of the three modes to use must not be made based on the return value of this function, which may be any positive integer amount. Only use this function for informational purposes.

◆ openmpt_module_get_num_instruments()

int32_t openmpt_module_get_num_instruments ( openmpt_module mod)

Get the number of instruments.

Parameters
modThe module handle to work on.
Returns
The number of instrument slots in the module. Instruments are a layer on top of samples, and are not supported by all module formats.

◆ openmpt_module_get_num_orders()

int32_t openmpt_module_get_num_orders ( openmpt_module mod)

Get the number of orders.

Parameters
modThe module handle to work on.
Returns
The number of orders in the current sequence of the module.

◆ openmpt_module_get_num_patterns()

int32_t openmpt_module_get_num_patterns ( openmpt_module mod)

Get the number of patterns.

Parameters
modThe module handle to work on.
Returns
The number of distinct patterns in the module.

◆ openmpt_module_get_num_samples()

int32_t openmpt_module_get_num_samples ( openmpt_module mod)

Get the number of samples.

Parameters
modThe module handle to work on.
Returns
The number of sample slots in the module.

◆ openmpt_module_get_num_subsongs()

int32_t openmpt_module_get_num_subsongs ( openmpt_module mod)

Get the number of sub-songs.

Parameters
modThe module handle to work on.
Returns
The number of sub-songs in the module. This includes any "hidden" songs (songs that share the same sequence, but start at different order indices) and "normal" sub-songs or "sequences" (if the format supports them).
See also
openmpt_module_get_subsong_name, openmpt_module_select_subsong, openmpt_module_get_selected_subsong

◆ openmpt_module_get_order_name()

const char* openmpt_module_get_order_name ( openmpt_module mod,
int32_t  index 
)

Get an order name.

Parameters
modThe module handle to work on.
indexThe order whose name should be retrieved
Returns
The order name.
See also
openmpt_module_get_num_orders

◆ openmpt_module_get_order_pattern()

int32_t openmpt_module_get_order_pattern ( openmpt_module mod,
int32_t  order 
)

Get pattern at order position.

Parameters
modThe module handle to work on.
orderThe order item whose pattern index should be retrieved.
Returns
The pattern index found at the given order position of the current sequence.

◆ openmpt_module_get_pattern_name()

const char* openmpt_module_get_pattern_name ( openmpt_module mod,
int32_t  index 
)

Get a pattern name.

Parameters
modThe module handle to work on.
indexThe pattern whose name should be retrieved
Returns
The pattern name.
See also
openmpt_module_get_num_patterns

◆ openmpt_module_get_pattern_num_rows()

int32_t openmpt_module_get_pattern_num_rows ( openmpt_module mod,
int32_t  pattern 
)

Get the number of rows in a pattern.

Parameters
modThe module handle to work on.
patternThe pattern whose row count should be retrieved.
Returns
The number of rows in the given pattern. If the pattern does not exist, 0 is returned.

◆ openmpt_module_get_pattern_row_channel_command()

uint8_t openmpt_module_get_pattern_row_channel_command ( openmpt_module mod,
int32_t  pattern,
int32_t  row,
int32_t  channel,
int  command 
)

Get raw pattern content.

Parameters
modThe module handle to work on.
patternThe pattern whose data should be retrieved.
rowThe row from which the data should be retrieved.
channelThe channel from which the data should be retrieved.
commandThe cell index at which the data should be retrieved. See Pattern cell indices
Returns
The internal, raw pattern data at the given pattern position.

◆ openmpt_module_get_position_seconds()

double openmpt_module_get_position_seconds ( openmpt_module mod)

Get current song position.

Parameters
modThe module handle to work on.
Returns
Current song position in seconds.
See also
openmpt_module_set_position_seconds

◆ openmpt_module_get_render_param()

int openmpt_module_get_render_param ( openmpt_module mod,
int  param,
int32_t *  value 
)

Get render parameter.

Parameters
modThe module handle to work on.
paramParameter to query. See Render param indices
valuePointer to the variable that receives the current value of the parameter.
Returns
1 on success, 0 on failure (invalid param or value is NULL).
See also
OPENMPT_MODULE_RENDER_MASTERGAIN_MILLIBEL
OPENMPT_MODULE_RENDER_STEREOSEPARATION_PERCENT
OPENMPT_MODULE_RENDER_INTERPOLATIONFILTER_LENGTH
OPENMPT_MODULE_RENDER_VOLUMERAMPING_STRENGTH
openmpt_module_set_render_param

◆ openmpt_module_get_repeat_count()

int32_t openmpt_module_get_repeat_count ( openmpt_module mod)

Get Repeat Count.

Parameters
modThe module handle to work on.
Returns
Repeat Count
  • -1: repeat forever
  • 0: play once, repeat zero times (the default)
  • n>0: play once and repeat n times after that
See also
openmpt_module_set_repeat_count

◆ openmpt_module_get_sample_name()

const char* openmpt_module_get_sample_name ( openmpt_module mod,
int32_t  index 
)

Get a sample name.

Parameters
modThe module handle to work on.
indexThe sample whose name should be retrieved
Returns
The sample name.
See also
openmpt_module_get_num_samples

◆ openmpt_module_get_selected_subsong()

int32_t openmpt_module_get_selected_subsong ( openmpt_module mod)

Get currently selected sub-song from a multi-song module.

Parameters
modThe module handle to work on.
Returns
Currently selected sub-song. -1 for all subsongs consecutively, 0 or greater for the current sub-song index.
See also
openmpt_module_get_num_subsongs, openmpt_module_select_subsong, openmpt_module_get_subsong_name
Since
0.3.0

◆ openmpt_module_get_subsong_name()

const char* openmpt_module_get_subsong_name ( openmpt_module mod,
int32_t  index 
)

Get a sub-song name.

Parameters
modThe module handle to work on.
indexThe sub-song whose name should be retrieved
Returns
The sub-song name.
See also
openmpt_module_get_num_subsongs, openmpt_module_select_subsong, openmpt_module_get_selected_subsong

◆ openmpt_module_highlight_pattern_row_channel()

const char* openmpt_module_highlight_pattern_row_channel ( openmpt_module mod,
int32_t  pattern,
int32_t  row,
int32_t  channel,
size_t  width,
int  pad 
)

Get highlighting information for formatted pattern content.

Parameters
modThe module handle to work on.
patternThe pattern whose data should be retrieved.
rowThe row from which the data should be retrieved.
channelThe channel from which the data should be retrieved.
widthThe maximum number of characters the string should contain. 0 means no limit.
padIf true, the string will be resized to the exact length provided in the width parameter.
Returns
The highlighting string for the formatted pattern data as retrieved by openmpt_module_format_pattern_row_channel at the given pattern position.
See also
openmpt_module_format_pattern_row_channel

◆ openmpt_module_highlight_pattern_row_channel_command()

const char* openmpt_module_highlight_pattern_row_channel_command ( openmpt_module mod,
int32_t  pattern,
int32_t  row,
int32_t  channel,
int  command 
)

Get highlighting information for formatted pattern content.

Parameters
modThe module handle to work on.
patternThe pattern whose data should be retrieved.
rowThe row from which the data should be retrieved.
channelThe channel from which the data should be retrieved.
commandThe cell index at which the data should be retrieved. See Pattern cell indices
Returns
The highlighting string for the formatted pattern data as retrieved by openmpt_module_get_pattern_row_channel_command at the given pattern position.
Remarks
The returned string will map each character position of the string returned by openmpt_module_get_pattern_row_channel_command to a highlighting instruction. Possible highlighting characters are:
  • " " : empty/space
  • "." : empty/dot
  • "n" : generic note
  • "m" : special note
  • "i" : generic instrument
  • "u" : generic volume column effect
  • "v" : generic volume column parameter
  • "e" : generic effect column effect
  • "f" : generic effect column parameter
See also
openmpt_module_get_pattern_row_channel_command

◆ openmpt_module_read_float_mono()

size_t openmpt_module_read_float_mono ( openmpt_module mod,
int32_t  samplerate,
size_t  count,
float *  mono 
)

Render audio data.

Parameters
modThe module handle to work on.
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
monoPointer to a buffer of at least count elements that receives the mono/center output.
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.
See also
Output Format

◆ openmpt_module_read_float_quad()

size_t openmpt_module_read_float_quad ( openmpt_module mod,
int32_t  samplerate,
size_t  count,
float *  left,
float *  right,
float *  rear_left,
float *  rear_right 
)

Render audio data.

Parameters
modThe module handle to work on.
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
leftPointer to a buffer of at least count elements that receives the left output.
rightPointer to a buffer of at least count elements that receives the right output.
rear_leftPointer to a buffer of at least count elements that receives the rear left output.
rear_rightPointer to a buffer of at least count elements that receives the rear right output.
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.
See also
Output Format

◆ openmpt_module_read_float_stereo()

size_t openmpt_module_read_float_stereo ( openmpt_module mod,
int32_t  samplerate,
size_t  count,
float *  left,
float *  right 
)

Render audio data.

Parameters
modThe module handle to work on.
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
leftPointer to a buffer of at least count elements that receives the left output.
rightPointer to a buffer of at least count elements that receives the right output.
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.
See also
Output Format

◆ openmpt_module_read_interleaved_float_quad()

size_t openmpt_module_read_interleaved_float_quad ( openmpt_module mod,
int32_t  samplerate,
size_t  count,
float *  interleaved_quad 
)

Render audio data.

Parameters
modThe module handle to work on.
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
interleaved_quadPointer to a buffer of at least count*4 elements that receives the interleaved suad surround output in the order (L,R,RL,RR).
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.
See also
Output Format

◆ openmpt_module_read_interleaved_float_stereo()

size_t openmpt_module_read_interleaved_float_stereo ( openmpt_module mod,
int32_t  samplerate,
size_t  count,
float *  interleaved_stereo 
)

Render audio data.

Parameters
modThe module handle to work on.
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
interleaved_stereoPointer to a buffer of at least count*2 elements that receives the interleaved stereo output in the order (L,R).
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.
See also
Output Format

◆ openmpt_module_read_interleaved_quad()

size_t openmpt_module_read_interleaved_quad ( openmpt_module mod,
int32_t  samplerate,
size_t  count,
int16_t *  interleaved_quad 
)

Render audio data.

Parameters
modThe module handle to work on.
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
interleaved_quadPointer to a buffer of at least count*4 elements that receives the interleaved suad surround output in the order (L,R,RL,RR).
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.
See also
Output Format

◆ openmpt_module_read_interleaved_stereo()

size_t openmpt_module_read_interleaved_stereo ( openmpt_module mod,
int32_t  samplerate,
size_t  count,
int16_t *  interleaved_stereo 
)

Render audio data.

Parameters
modThe module handle to work on.
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
interleaved_stereoPointer to a buffer of at least count*2 elements that receives the interleaved stereo output in the order (L,R).
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.
See also
Output Format

◆ openmpt_module_read_mono()

size_t openmpt_module_read_mono ( openmpt_module mod,
int32_t  samplerate,
size_t  count,
int16_t *  mono 
)

Render audio data.

Parameters
modThe module handle to work on.
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
monoPointer to a buffer of at least count elements that receives the mono/center output.
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.
See also
Output Format

◆ openmpt_module_read_quad()

size_t openmpt_module_read_quad ( openmpt_module mod,
int32_t  samplerate,
size_t  count,
int16_t *  left,
int16_t *  right,
int16_t *  rear_left,
int16_t *  rear_right 
)

Render audio data.

Parameters
modThe module handle to work on.
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
leftPointer to a buffer of at least count elements that receives the left output.
rightPointer to a buffer of at least count elements that receives the right output.
rear_leftPointer to a buffer of at least count elements that receives the rear left output.
rear_rightPointer to a buffer of at least count elements that receives the rear right output.
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.
See also
Output Format

◆ openmpt_module_read_stereo()

size_t openmpt_module_read_stereo ( openmpt_module mod,
int32_t  samplerate,
size_t  count,
int16_t *  left,
int16_t *  right 
)

Render audio data.

Parameters
modThe module handle to work on.
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
leftPointer to a buffer of at least count elements that receives the left output.
rightPointer to a buffer of at least count elements that receives the right output.
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.
See also
Output Format

◆ openmpt_module_select_subsong()

int openmpt_module_select_subsong ( openmpt_module mod,
int32_t  subsong 
)

Select a sub-song from a multi-song module.

Parameters
modThe module handle to work on.
subsongIndex of the sub-song. -1 plays all sub-songs consecutively.
Returns
1 on success, 0 on failure.
See also
openmpt_module_get_num_subsongs, openmpt_module_get_selected_subsong, openmpt_module_get_subsong_name
Remarks
Whether subsong -1 (all subsongs consecutively), subsong 0 or some other subsong is selected by default, is an implementation detail and subject to change. If you do not want to care about subsongs, it is recommended to just not call openmpt_module_select_subsong() at all.

◆ openmpt_module_set_error_func()

void openmpt_module_set_error_func ( openmpt_module mod,
openmpt_error_func  errfunc,
void *  erruser 
)

Set error function.

Set the error function of an already constructed openmpt_module.

Parameters
modThe module handle to work on.
errfuncError function to define error behaviour. May be NULL.
erruserError function user context.
Since
0.3.0

◆ openmpt_module_set_log_func()

void openmpt_module_set_log_func ( openmpt_module mod,
openmpt_log_func  logfunc,
void *  loguser 
)

Set logging function.

Set the logging function of an already constructed openmpt_module.

Parameters
modThe module handle to work on.
logfuncLogging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module.
loguserUser-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
Since
0.3.0

◆ openmpt_module_set_position_order_row()

double openmpt_module_set_position_order_row ( openmpt_module mod,
int32_t  order,
int32_t  row 
)

Set approximate current song position.

If order or row are out of range, to position is not modified and the current position is returned.

Parameters
modThe module handle to work on.
orderPattern order number to seek to.
rowPattern row number to seek to.
Returns
Approximate new song position in seconds.
See also
openmpt_module_set_position_seconds
openmpt_module_get_position_seconds

◆ openmpt_module_set_position_seconds()

double openmpt_module_set_position_seconds ( openmpt_module mod,
double  seconds 
)

Set approximate current song position.

Parameters
modThe module handle to work on.
secondsSeconds to seek to. If seconds is out of range, the position gets set to song start or end respectively.
Returns
Approximate new song position in seconds.
See also
openmpt_module_get_position_seconds

◆ openmpt_module_set_render_param()

int openmpt_module_set_render_param ( openmpt_module mod,
int  param,
int32_t  value 
)

Set render parameter.

Parameters
modThe module handle to work on.
paramParameter to set. See Render param indices
valueThe value to set param to.
Returns
1 on success, 0 on failure (invalid param).
See also
OPENMPT_MODULE_RENDER_MASTERGAIN_MILLIBEL
OPENMPT_MODULE_RENDER_STEREOSEPARATION_PERCENT
OPENMPT_MODULE_RENDER_INTERPOLATIONFILTER_LENGTH
OPENMPT_MODULE_RENDER_VOLUMERAMPING_STRENGTH
openmpt_module_get_render_param

◆ openmpt_module_set_repeat_count()

int openmpt_module_set_repeat_count ( openmpt_module mod,
int32_t  repeat_count 
)

Set Repeat Count.

Parameters
modThe module handle to work on.
repeat_countRepeat Count
  • -1: repeat forever
  • 0: play once, repeat zero times (the default)
  • n>0: play once and repeat n times after that
Returns
1 on success, 0 on failure.
See also
openmpt_module_get_repeat_count

◆ openmpt_probe_file_header()

int openmpt_probe_file_header ( uint64_t  flags,
const void *  data,
size_t  size,
uint64_t  filesize,
openmpt_log_func  logfunc,
void *  loguser,
openmpt_error_func  errfunc,
void *  erruser,
int *  error,
const char **  error_message 
)

Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it.

Parameters
flagsOred mask of OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES and OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS, or OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT.
dataBeginning of the file data.
sizeSize of the beginning of the file data.
filesizeFull size of the file data on disk.
logfuncLogging function where warning and errors are written. May be NULL.
loguserLogging function user context. Used to pass any user-defined data associated with this module to the logging function.
errfuncError function to define error behaviour. May be NULL.
erruserError function user context. Used to pass any user-defined data associated with this module to the logging function.
errorPointer to an integer where an error may get stored. May be NULL.
error_messagePointer to a string pointer where an error message may get stored. May be NULL.
Remarks
It is recommended to provide openmpt_probe_file_header_get_recommended_size() bytes of data for data and size. If the file is smaller, only provide the filesize amount and set size and filesize to the file's size.
openmpt_could_open_probability2() provides a more elaborate interface that might be required for special use cases. It is recommended to use openmpt_probe_file_header() though, if possible.
Return values
OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESSThe file will most likely be supported by libopenmpt.
OPENMPT_PROBE_FILE_HEADER_RESULT_FAILUREThe file is not supported by libopenmpt.
OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATAAn answer could not be determined with the amount of data provided.
OPENMPT_PROBE_FILE_HEADER_RESULT_ERRORAn internal error occurred.
See also
openmpt_probe_file_header_get_recommended_size()
openmpt_probe_file_header_without_filesize()
openmpt_probe_file_header_from_stream()
openmpt_could_open_probability2()
Since
0.3.0

◆ openmpt_probe_file_header_from_stream()

int openmpt_probe_file_header_from_stream ( uint64_t  flags,
openmpt_stream_callbacks  stream_callbacks,
void *  stream,
openmpt_log_func  logfunc,
void *  loguser,
openmpt_error_func  errfunc,
void *  erruser,
int *  error,
const char **  error_message 
)

Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it.

Parameters
flagsOred mask of OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES and OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS, or OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT.
stream_callbacksInput stream callback operations.
streamInput stream to scan.
logfuncLogging function where warning and errors are written. May be NULL.
loguserLogging function user context. Used to pass any user-defined data associated with this module to the logging function.
errfuncError function to define error behaviour. May be NULL.
erruserError function user context. Used to pass any user-defined data associated with this module to the logging function.
errorPointer to an integer where an error may get stored. May be NULL.
error_messagePointer to a string pointer where an error message may get stored. May be NULL.
Remarks
The stream is left in an unspecified state when this function returns.
It is recommended to provide openmpt_probe_file_header_get_recommended_size() bytes of data for data and size. If the file is smaller, only provide the filesize amount and set size and filesize to the file's size.
openmpt_could_open_probability2() provides a more elaborate interface that might be required for special use cases. It is recommended to use openmpt_probe_file_header() though, if possible.
Return values
OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESSThe file will most likely be supported by libopenmpt.
OPENMPT_PROBE_FILE_HEADER_RESULT_FAILUREThe file is not supported by libopenmpt.
OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATAAn answer could not be determined with the amount of data provided.
OPENMPT_PROBE_FILE_HEADER_RESULT_ERRORAn internal error occurred.
See also
openmpt_probe_file_header_get_recommended_size()
openmpt_probe_file_header()
openmpt_probe_file_header_without_filesize()
openmpt_could_open_probability2()
Since
0.3.0

◆ openmpt_probe_file_header_get_recommended_size()

size_t openmpt_probe_file_header_get_recommended_size ( void  )

Get recommended header size for successfull format probing.

See also
openmpt_probe_file_header()
openmpt_probe_file_header_without_filesize()
Since
0.3.0

◆ openmpt_probe_file_header_without_filesize()

int openmpt_probe_file_header_without_filesize ( uint64_t  flags,
const void *  data,
size_t  size,
openmpt_log_func  logfunc,
void *  loguser,
openmpt_error_func  errfunc,
void *  erruser,
int *  error,
const char **  error_message 
)

Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it.

Parameters
flagsOred mask of OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES and OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS, or OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT.
dataBeginning of the file data.
sizeSize of the beginning of the file data.
logfuncLogging function where warning and errors are written. May be NULL.
loguserLogging function user context. Used to pass any user-defined data associated with this module to the logging function.
errfuncError function to define error behaviour. May be NULL.
erruserError function user context. Used to pass any user-defined data associated with this module to the logging function.
errorPointer to an integer where an error may get stored. May be NULL.
error_messagePointer to a string pointer where an error message may get stored. May be NULL.
Remarks
It is recommended to use openmpt_probe_file_header() and provide the acutal file's size as a parameter if at all possible. libopenmpt can provide more accurate answers if the filesize is known.
It is recommended to provide openmpt_probe_file_header_get_recommended_size() bytes of data for data and size. If the file is smaller, only provide the filesize amount and set size to the file's size.
openmpt_could_open_probability2() provides a more elaborate interface that might be required for special use cases. It is recommended to use openmpt_probe_file_header() though, if possible.
Return values
OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESSThe file will most likely be supported by libopenmpt.
OPENMPT_PROBE_FILE_HEADER_RESULT_FAILUREThe file is not supported by libopenmpt.
OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATAAn answer could not be determined with the amount of data provided.
OPENMPT_PROBE_FILE_HEADER_RESULT_ERRORAn internal error occurred.
See also
openmpt_probe_file_header_get_recommended_size()
openmpt_probe_file_header()
openmpt_probe_file_header_from_stream()
openmpt_could_open_probability2()
Since
0.3.0