libopenmpt: openmpt::module Class Reference

libopenmpt 0.9.0-pre.12+r25552 cross-platform C++ and C library to decode tracked music files

Loading...
Searching...
No Matches
openmpt::module Class Reference
libopenmpt C++

`#include <libopenmpt/libopenmpt.hpp>`

Inheritance diagram for openmpt::module:

## Public Types
enum | render_param { RENDER_MASTERGAIN_MILLIBEL = 1 , RENDER_STEREOSEPARATION_PERCENT = 2 , RENDER_INTERPOLATIONFILTER_LENGTH = 3 , RENDER_VOLUMERAMPING_STRENGTH = 4 }
| Parameter index to use with openmpt::module::get_render_param and openmpt::module::set_render_param. More...
enum | command_index { command_note = 0 , command_instrument = 1 , command_volumeffect = 2 , command_effect = 3 , command_volume = 4 , command_parameter = 5 }
| 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. More...

## Public Member Functions
LIBOPENMPT_CXX_API_MEMBER | module (std::istream &stream, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
| Construct an openmpt::module.
LIBOPENMPT_CXX_API_MEMBER | module (const std::vector< std::byte > &data, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
LIBOPENMPT_CXX_API_MEMBER | module (const std::byte *beg, const std::byte *end, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
LIBOPENMPT_CXX_API_MEMBER | module (const std::byte *data, std::size_t size, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
LIBOPENMPT_CXX_API_MEMBER | module (const std::vector< std::uint8_t > &data, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
LIBOPENMPT_CXX_API_MEMBER | module (const std::uint8_t *beg, const std::uint8_t *end, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
LIBOPENMPT_CXX_API_MEMBER | module (const std::uint8_t *data, std::size_t size, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
LIBOPENMPT_CXX_API_MEMBER | module (const std::vector< char > &data, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
LIBOPENMPT_CXX_API_MEMBER | module (const char *beg, const char *end, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
LIBOPENMPT_CXX_API_MEMBER | module (const char *data, std::size_t size, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
LIBOPENMPT_CXX_API_MEMBER | module (const void *data, std::size_t size, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
virtual LIBOPENMPT_CXX_API_MEMBER | ~module ()
LIBOPENMPT_CXX_API_MEMBER void | select_subsong (std::int32_t subsong)
| Select a sub-song from a multi-song module.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_selected_subsong () const
| Get currently selected sub-song from a multi-song module.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_restart_order (std::int32_t subsong) const
| Get the restart order of the specified sub-song.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_restart_row (std::int32_t subsong) const
| Get the restart row of the specified sub-song.
LIBOPENMPT_CXX_API_MEMBER void | set_repeat_count (std::int32_t repeat_count)
| Set Repeat Count.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_repeat_count () const
| Get Repeat Count.
LIBOPENMPT_CXX_API_MEMBER double | get_duration_seconds () const
| Get approximate song duration.
LIBOPENMPT_CXX_API_MEMBER double | get_time_at_position (std::int32_t order, std::int32_t row) const
| Get approximate playback time in seconds at given position.
LIBOPENMPT_CXX_API_MEMBER double | set_position_seconds (double seconds)
| Set approximate current song position.
LIBOPENMPT_CXX_API_MEMBER double | get_position_seconds () const
| Get current song position.
LIBOPENMPT_CXX_API_MEMBER double | set_position_order_row (std::int32_t order, std::int32_t row)
| Set approximate current song position.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_render_param (int param) const
| Get render parameter.
LIBOPENMPT_CXX_API_MEMBER void | set_render_param (int param, std::int32_t value)
| Set render parameter.
LIBOPENMPT_CXX_API_MEMBER std::size_t | read (std::int32_t samplerate, std::size_t count, std::int16_t *mono)
| Render audio data.
LIBOPENMPT_CXX_API_MEMBER std::size_t | read (std::int32_t samplerate, std::size_t count, std::int16_t *left, std::int16_t *right)
| Render audio data.
LIBOPENMPT_CXX_API_MEMBER std::size_t | read (std::int32_t samplerate, std::size_t count, std::int16_t *left, std::int16_t *right, std::int16_t *rear_left, std::int16_t *rear_right)
| Render audio data.
LIBOPENMPT_CXX_API_MEMBER std::size_t | read (std::int32_t samplerate, std::size_t count, float *mono)
| Render audio data.
LIBOPENMPT_CXX_API_MEMBER std::size_t | read (std::int32_t samplerate, std::size_t count, float *left, float *right)
| Render audio data.
LIBOPENMPT_CXX_API_MEMBER std::size_t | read (std::int32_t samplerate, std::size_t count, float *left, float *right, float *rear_left, float *rear_right)
| Render audio data.
LIBOPENMPT_CXX_API_MEMBER std::size_t | read_interleaved_stereo (std::int32_t samplerate, std::size_t count, std::int16_t *interleaved_stereo)
| Render audio data.
LIBOPENMPT_CXX_API_MEMBER std::size_t | read_interleaved_quad (std::int32_t samplerate, std::size_t count, std::int16_t *interleaved_quad)
| Render audio data.
LIBOPENMPT_CXX_API_MEMBER std::size_t | read_interleaved_stereo (std::int32_t samplerate, std::size_t count, float *interleaved_stereo)
| Render audio data.
LIBOPENMPT_CXX_API_MEMBER std::size_t | read_interleaved_quad (std::int32_t samplerate, std::size_t count, float *interleaved_quad)
| Render audio data.
LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > | get_metadata_keys () const
| Get the list of supported metadata item keys.
LIBOPENMPT_CXX_API_MEMBER std::string | get_metadata (const std::string &key) const
| Get a metadata item value.
LIBOPENMPT_CXX_API_MEMBER double | get_current_estimated_bpm () const
| Get the current estimated beats per minute (BPM).
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_current_speed () const
| Get the current speed.
LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_current_tempo () const
| Get the current tempo.
LIBOPENMPT_CXX_API_MEMBER double | get_current_tempo2 () const
| Get the current tempo.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_current_sequence () const
| Get the current sequence.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_current_order () const
| Get the current order.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_current_pattern () const
| Get the current pattern.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_current_row () const
| Get the current row.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_current_playing_channels () const
| Get the current amount of playing channels.
LIBOPENMPT_CXX_API_MEMBER float | get_current_channel_vu_mono (std::int32_t channel) const
| Get an approximate indication of the channel volume.
LIBOPENMPT_CXX_API_MEMBER float | get_current_channel_vu_left (std::int32_t channel) const
| Get an approximate indication of the channel volume on the front-left speaker.
LIBOPENMPT_CXX_API_MEMBER float | get_current_channel_vu_right (std::int32_t channel) const
| Get an approximate indication of the channel volume on the front-right speaker.
LIBOPENMPT_CXX_API_MEMBER float | get_current_channel_vu_rear_left (std::int32_t channel) const
| Get an approximate indication of the channel volume on the rear-left speaker.
LIBOPENMPT_CXX_API_MEMBER float | get_current_channel_vu_rear_right (std::int32_t channel) const
| Get an approximate indication of the channel volume on the rear-right speaker.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_num_subsongs () const
| Get the number of sub-songs.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_num_channels () const
| Get the number of pattern channels.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_num_orders () const
| Get the number of orders.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_num_patterns () const
| Get the number of patterns.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_num_instruments () const
| Get the number of instruments.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_num_samples () const
| Get the number of samples.
LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > | get_subsong_names () const
| Get a list of sub-song names.
LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > | get_channel_names () const
| Get a list of channel names.
LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > | get_order_names () const
| Get a list of order names.
LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > | get_pattern_names () const
| Get a list of pattern names.
LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > | get_instrument_names () const
| Get a list of instrument names.
LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > | get_sample_names () const
| Get a list of sample names.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_order_pattern (std::int32_t order) const
| Get pattern at order position.
LIBOPENMPT_CXX_API_MEMBER bool | is_order_skip_entry (std::int32_t order) const
| Check if specified order is a skip ("+++") item.
LIBOPENMPT_CXX_API_MEMBER bool | is_pattern_skip_item (std::int32_t pattern) const
| Check if specified pattern index is a skip ("+++") item.
LIBOPENMPT_CXX_API_MEMBER bool | is_order_stop_entry (std::int32_t order) const
| Check if specified order is a stop ("---") item.
LIBOPENMPT_CXX_API_MEMBER bool | is_pattern_stop_item (std::int32_t pattern) const
| Check if specified pattern index is a stop ("---") item.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_pattern_num_rows (std::int32_t pattern) const
| Get the number of rows in a pattern.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_pattern_rows_per_beat (std::int32_t pattern) const
| Get the rows per beat of a pattern.
LIBOPENMPT_CXX_API_MEMBER std::int32_t | get_pattern_rows_per_measure (std::int32_t pattern) const
| Get the rows per measure of a pattern.
LIBOPENMPT_CXX_API_MEMBER std::uint8_t | get_pattern_row_channel_command (std::int32_t pattern, std::int32_t row, std::int32_t channel, int command) const
| Get raw pattern content.
LIBOPENMPT_CXX_API_MEMBER std::string | format_pattern_row_channel_command (std::int32_t pattern, std::int32_t row, std::int32_t channel, int command) const
| Get formatted (human-readable) pattern content.
LIBOPENMPT_CXX_API_MEMBER std::string | highlight_pattern_row_channel_command (std::int32_t pattern, std::int32_t row, std::int32_t channel, int command) const
| Get highlighting information for formatted pattern content.
LIBOPENMPT_CXX_API_MEMBER std::string | format_pattern_row_channel (std::int32_t pattern, std::int32_t row, std::int32_t channel, std::size_t width=0, bool pad=true) const
| Get formatted (human-readable) pattern content.
LIBOPENMPT_CXX_API_MEMBER std::string | highlight_pattern_row_channel (std::int32_t pattern, std::int32_t row, std::int32_t channel, std::size_t width=0, bool pad=true) const
| Get highlighting information for formatted pattern content.
LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > | get_ctls () const
| Retrieve supported ctl keys.
LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API_MEMBER std::string | ctl_get (const std::string &ctl) const
| Get current ctl value.
LIBOPENMPT_CXX_API_MEMBER bool | ctl_get_boolean (std::string_view ctl) const
| Get current ctl boolean value.
LIBOPENMPT_CXX_API_MEMBER std::int64_t | ctl_get_integer (std::string_view ctl) const
| Get current ctl integer value.
LIBOPENMPT_CXX_API_MEMBER double | ctl_get_floatingpoint (std::string_view ctl) const
| Get current ctl floatingpoint value.
LIBOPENMPT_CXX_API_MEMBER std::string | ctl_get_text (std::string_view ctl) const
| Get current ctl text value.
LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API_MEMBER void | ctl_set (const std::string &ctl, const std::string &value)
| Set ctl value.
LIBOPENMPT_CXX_API_MEMBER void | ctl_set_boolean (std::string_view ctl, bool value)
| Set ctl boolean value.
LIBOPENMPT_CXX_API_MEMBER void | ctl_set_integer (std::string_view ctl, std::int64_t value)
| Set ctl integer value.
LIBOPENMPT_CXX_API_MEMBER void | ctl_set_floatingpoint (std::string_view ctl, double value)
| Set ctl floatingpoint value.
LIBOPENMPT_CXX_API_MEMBER void | ctl_set_text (std::string_view ctl, std::string_view value)
| Set ctl text value.

## Friends
class | module_ext

## Member Enumeration Documentation

## ◆ command_index

enum openmpt::module::command_index

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.

Enumerator
command_note |
command_instrument |
command_volumeffect |
command_effect |
command_volume |
command_parameter |

## ◆ render_param

enum openmpt::module::render_param

Parameter index to use with openmpt::module::get_render_param and openmpt::module::set_render_param.

Enumerator
RENDER_MASTERGAIN_MILLIBEL | Master Gain. The related value represents a relative gain in milliBel. The default value is 0. The supported value range is unlimited.
RENDER_STEREOSEPARATION_PERCENT | Stereo Separation. The related value represents the stereo separation generated by the libopenmpt mixer in percent. The default value is 100. The supported value range is [0,200].
RENDER_INTERPOLATIONFILTER_LENGTH | Interpolation Filter. The related value represents the interpolation filter length used by the libopenmpt mixer. The default value is 0, which indicates a recommended default value. The supported value range is [0,inf). Values greater than the implementation limit are clamped to the maximum supported value. Currently supported values: 0: internal default 1: no interpolation (zero order hold) 2: linear interpolation 4: cubic interpolation 8: windowed sinc with 8 taps
RENDER_VOLUMERAMPING_STRENGTH | Volume Ramping Strength. The related value represents the amount of volume ramping done by the libopenmpt mixer. The default value is -1, which indicates a recommended default value. The meaningful value range is [-1..10]. A value of 0 completely disables volume ramping. This might cause clicks in sound output. Higher values imply slower/softer volume ramps.

## Constructor & Destructor Documentation

## ◆ module() [1/11]

LIBOPENMPT_CXX_API_MEMBER openmpt::module::module | ( | std::istream & | stream,
|  | std::ostream & | log = std::clog,
|  | const std::map< std::string, std::string > & | ctls = detail::initial_ctls_map() )

Construct an openmpt::module.

Parameters

  stream | Input stream from which the module is loaded. After the constructor has finished successfully, the input position of stream is set to the byte after the last byte that has been read. If the constructor fails, the state of the input position of stream is undefined.
  log | Log where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
  ctls | A map of initial ctl values, see openmpt::module::get_ctls and openmpt::module::ctl_set.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the provided file cannot be opened.

Remarks
  The input data can be discarded after an openmpt::module has been constructed successfully.

See also
  File I/O

## ◆ module() [2/11]

LIBOPENMPT_CXX_API_MEMBER openmpt::module::module | ( | const std::vector< std::byte > & | data,
|  | std::ostream & | log = std::clog,
|  | const std::map< std::string, std::string > & | ctls = detail::initial_ctls_map() )

Parameters

  data | Data to load the module from.
  log | Log where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
  ctls | A map of initial ctl values, see openmpt::module::get_ctls and openmpt::module::ctl_set.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the provided file cannot be opened.

Remarks
  The input data can be discarded after an openmpt::module has been constructed successfully.

See also
  File I/O

Since
  0.5.0

## ◆ module() [3/11]

LIBOPENMPT_CXX_API_MEMBER openmpt::module::module | ( | const std::byte * | beg,
|  | const std::byte * | end,
|  | std::ostream & | log = std::clog,
|  | const std::map< std::string, std::string > & | ctls = detail::initial_ctls_map() )

Parameters

  beg | Begin of data to load the module from.
  end | End of data to load the module from.
  log | Log where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
  ctls | A map of initial ctl values, see openmpt::module::get_ctls and openmpt::module::ctl_set.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the provided file cannot be opened.

Remarks
  The input data can be discarded after an openmpt::module has been constructed successfully.

See also
  File I/O

Since
  0.5.0

## ◆ module() [4/11]

LIBOPENMPT_CXX_API_MEMBER openmpt::module::module | ( | const std::byte * | data,
|  | std::size_t | size,
|  | std::ostream & | log = std::clog,
|  | const std::map< std::string, std::string > & | ctls = detail::initial_ctls_map() )

Parameters

  data | Data to load the module from.
  size | Amount of data available.
  log | Log where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
  ctls | A map of initial ctl values, see openmpt::module::get_ctls.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the provided file cannot be opened.

Remarks
  The input data can be discarded after an openmpt::module has been constructed successfully.

See also
  File I/O

Since
  0.5.0

## ◆ module() [5/11]

LIBOPENMPT_CXX_API_MEMBER openmpt::module::module | ( | const std::vector< std::uint8_t > & | data,
|  | std::ostream & | log = std::clog,
|  | const std::map< std::string, std::string > & | ctls = detail::initial_ctls_map() )

Parameters

  data | Data to load the module from.
  log | Log where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
  ctls | A map of initial ctl values, see openmpt::module::get_ctls and openmpt::module::ctl_set.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the provided file cannot be opened.

Remarks
  The input data can be discarded after an openmpt::module has been constructed successfully.

See also
  File I/O

## ◆ module() [6/11]

LIBOPENMPT_CXX_API_MEMBER openmpt::module::module | ( | const std::uint8_t * | beg,
|  | const std::uint8_t * | end,
|  | std::ostream & | log = std::clog,
|  | const std::map< std::string, std::string > & | ctls = detail::initial_ctls_map() )

Parameters

  beg | Begin of data to load the module from.
  end | End of data to load the module from.
  log | Log where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
  ctls | A map of initial ctl values, see openmpt::module::get_ctls.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the provided file cannot be opened.

Remarks
  The input data can be discarded after an openmpt::module has been constructed successfully.

See also
  File I/O

## ◆ module() [7/11]

LIBOPENMPT_CXX_API_MEMBER openmpt::module::module | ( | const std::uint8_t * | data,
|  | std::size_t | size,
|  | std::ostream & | log = std::clog,
|  | const std::map< std::string, std::string > & | ctls = detail::initial_ctls_map() )

Parameters

  data | Data to load the module from.
  size | Amount of data available.
  log | Log where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
  ctls | A map of initial ctl values, see openmpt::module::get_ctls.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the provided file cannot be opened.

Remarks
  The input data can be discarded after an openmpt::module has been constructed successfully.

See also
  File I/O

## ◆ module() [8/11]

LIBOPENMPT_CXX_API_MEMBER openmpt::module::module | ( | const std::vector< char > & | data,
|  | std::ostream & | log = std::clog,
|  | const std::map< std::string, std::string > & | ctls = detail::initial_ctls_map() )

Parameters

  data | Data to load the module from.
  log | Log where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
  ctls | A map of initial ctl values, see openmpt::module::get_ctls.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the provided file cannot be opened.

Remarks
  The input data can be discarded after an openmpt::module has been constructed successfully.

See also
  File I/O

## ◆ module() [9/11]

LIBOPENMPT_CXX_API_MEMBER openmpt::module::module | ( | const char * | beg,
|  | const char * | end,
|  | std::ostream & | log = std::clog,
|  | const std::map< std::string, std::string > & | ctls = detail::initial_ctls_map() )

Parameters

  beg | Begin of data to load the module from.
  end | End of data to load the module from.
  log | Log where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
  ctls | A map of initial ctl values, see openmpt::module::get_ctls.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the provided file cannot be opened.

Remarks
  The input data can be discarded after an openmpt::module has been constructed successfully.

See also
  File I/O

## ◆ module() [10/11]

LIBOPENMPT_CXX_API_MEMBER openmpt::module::module | ( | const char * | data,
|  | std::size_t | size,
|  | std::ostream & | log = std::clog,
|  | const std::map< std::string, std::string > & | ctls = detail::initial_ctls_map() )

Parameters

  data | Data to load the module from.
  size | Amount of data available.
  log | Log where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
  ctls | A map of initial ctl values, see openmpt::module::get_ctls.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the provided file cannot be opened.

Remarks
  The input data can be discarded after an openmpt::module has been constructed successfully.

See also
  File I/O

## ◆ module() [11/11]

LIBOPENMPT_CXX_API_MEMBER openmpt::module::module | ( | const void * | data,
|  | std::size_t | size,
|  | std::ostream & | log = std::clog,
|  | const std::map< std::string, std::string > & | ctls = detail::initial_ctls_map() )

Parameters

  data | Data to load the module from.
  size | Amount of data available.
  log | Log where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
  ctls | A map of initial ctl values, see openmpt::module::get_ctls.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the provided file cannot be opened.

Remarks
  The input data can be discarded after an openmpt::module has been constructed successfully.

See also
  File I/O

## ◆ ~module()

virtual LIBOPENMPT_CXX_API_MEMBER openmpt::module::~module | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ ctl_get()

LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API_MEMBER std::string openmpt::module::ctl_get | ( | const std::string & | ctl | ) | const

Get current ctl value.

Parameters

  ctl | The ctl key whose value should be retrieved.

Returns
  The associated ctl value.

See also
  openmpt::module::get_ctls

Deprecated
  Please use openmpt::module::ctl_get_boolean(), openmpt::module::ctl_get_integer(), openmpt::module::ctl_get_floatingpoint(), or openmpt::module::ctl_get_text().

## ◆ ctl_get_boolean()

LIBOPENMPT_CXX_API_MEMBER bool openmpt::module::ctl_get_boolean | ( | std::string_view | ctl | ) | const

Get current ctl boolean value.

Parameters

  ctl | The ctl key whose value should be retrieved.

Returns
  The associated ctl value.

See also
  openmpt::module::get_ctls

Since
  0.5.0

## ◆ ctl_get_floatingpoint()

LIBOPENMPT_CXX_API_MEMBER double openmpt::module::ctl_get_floatingpoint | ( | std::string_view | ctl | ) | const

Get current ctl floatingpoint value.

Parameters

  ctl | The ctl key whose value should be retrieved.

Returns
  The associated ctl value.

See also
  openmpt::module::get_ctls

Since
  0.5.0

## ◆ ctl_get_integer()

LIBOPENMPT_CXX_API_MEMBER std::int64_t openmpt::module::ctl_get_integer | ( | std::string_view | ctl | ) | const

Get current ctl integer value.

Parameters

  ctl | The ctl key whose value should be retrieved.

Returns
  The associated ctl value.

See also
  openmpt::module::get_ctls

Since
  0.5.0

## ◆ ctl_get_text()

LIBOPENMPT_CXX_API_MEMBER std::string openmpt::module::ctl_get_text | ( | std::string_view | ctl | ) | const

Get current ctl text value.

Parameters

  ctl | The ctl key whose value should be retrieved.

Returns
  The associated ctl value.

See also
  openmpt::module::get_ctls

Since
  0.5.0

## ◆ ctl_set()

LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API_MEMBER void openmpt::module::ctl_set | ( | const std::string & | ctl,
|  | const std::string & | value )

Set ctl value.

Parameters

  ctl | The ctl key whose value should be set.
  value | The value that should be set.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the value is not sensible (e.g. negative tempo factor) or under the circumstances outlined in openmpt::module::get_ctls.

See also
  openmpt::module::get_ctls

Deprecated
  Please use openmpt::module::ctl_set_boolean(), openmpt::module::ctl_set_integer(), openmpt::module::ctl_set_floatingpoint(), or openmpt::module::ctl_set_text().

## ◆ ctl_set_boolean()

LIBOPENMPT_CXX_API_MEMBER void openmpt::module::ctl_set_boolean | ( | std::string_view | ctl,
|  | bool | value )

Set ctl boolean value.

Parameters

  ctl | The ctl key whose value should be set.
  value | The value that should be set.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the value is not sensible (e.g. negative tempo factor) or under the circumstances outlined in openmpt::module::get_ctls.

See also
  openmpt::module::get_ctls

Since
  0.5.0

## ◆ ctl_set_floatingpoint()

LIBOPENMPT_CXX_API_MEMBER void openmpt::module::ctl_set_floatingpoint | ( | std::string_view | ctl,
|  | double | value )

Set ctl floatingpoint value.

Parameters

  ctl | The ctl key whose value should be set.
  value | The value that should be set.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the value is not sensible (e.g. negative tempo factor) or under the circumstances outlined in openmpt::module::get_ctls.

See also
  openmpt::module::get_ctls

Since
  0.5.0

## ◆ ctl_set_integer()

LIBOPENMPT_CXX_API_MEMBER void openmpt::module::ctl_set_integer | ( | std::string_view | ctl,
|  | std::int64_t | value )

Set ctl integer value.

Parameters

  ctl | The ctl key whose value should be set.
  value | The value that should be set.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the value is not sensible (e.g. negative tempo factor) or under the circumstances outlined in openmpt::module::get_ctls.

See also
  openmpt::module::get_ctls

Since
  0.5.0

## ◆ ctl_set_text()

LIBOPENMPT_CXX_API_MEMBER void openmpt::module::ctl_set_text | ( | std::string_view | ctl,
|  | std::string_view | value )

Set ctl text value.

Parameters

  ctl | The ctl key whose value should be set.
  value | The value that should be set.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception in case the value is not sensible (e.g. negative tempo factor) or under the circumstances outlined in openmpt::module::get_ctls.

See also
  openmpt::module::get_ctls

Since
  0.5.0

## ◆ format_pattern_row_channel()

LIBOPENMPT_CXX_API_MEMBER std::string openmpt::module::format_pattern_row_channel | ( | std::int32_t | pattern,
|  | std::int32_t | row,
|  | std::int32_t | channel,
|  | std::size_t | width = 0,
|  | bool | pad = true ) const

Get formatted (human-readable) pattern content.

Parameters

  pattern | The pattern whose data should be retrieved.
  row | The row from which the data should be retrieved.
  channel | The channel from which the data should be retrieved.
  width | The maximum number of characters the string should contain. 0 means no limit.
  pad | If 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

## ◆ format_pattern_row_channel_command()

LIBOPENMPT_CXX_API_MEMBER std::string openmpt::module::format_pattern_row_channel_command | ( | std::int32_t | pattern,
|  | std::int32_t | row,
|  | std::int32_t | channel,
|  | int | command ) const

Get formatted (human-readable) pattern content.

Parameters

  pattern | The pattern whose data should be retrieved.
  row | The row from which the data should be retrieved.
  channel | The channel from which the data should be retrieved.
  command | The cell index at which the data should be retrieved.

Returns
  The formatted pattern data at the given pattern position. See openmpt::module::command_index

See also
  openmpt::module::highlight_pattern_row_channel_command

## ◆ get_channel_names()

LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > openmpt::module::get_channel_names | ( |  | ) | const

Get a list of channel names.

Returns
  All channel names.

See also
  openmpt::module::get_num_channels

## ◆ get_ctls()

LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > openmpt::module::get_ctls | ( |  | ) | const

Retrieve supported ctl keys.

Returns
  A vector containing all supported ctl keys.

Remarks
  Currently supported ctl values are:
  - load.skip_samples (boolean): Set to "1" to avoid loading samples into memory
  - load.skip_patterns (boolean): Set to "1" to avoid loading patterns into memory
  - load.skip_plugins (boolean): Set to "1" to avoid loading plugins
  - load.skip_subsongs_init (boolean): Set to "1" to avoid pre-initializing sub-songs. Skipping results in faster module loading but slower seeking.
  - seek.sync_samples (boolean): Set to "0" to not sync sample playback when using openmpt::module::set_position_seconds or openmpt::module::set_position_order_row.
  - subsong (integer): The current subsong. Setting it has identical semantics as openmpt::module::select_subsong(), getting it returns the currently selected subsong.
  - play.at_end (text): Chooses the behaviour when the end of song is reached. The song end is considered to be reached after the number of reptitions set by openmpt::module::set_repeat_count was played, so if the song is set to repeat infinitely, its end is never considered to be reached.
    - "fadeout": Fades the module out for a short while. Subsequent reads after the fadeout will return 0 rendered frames.
    - "continue": Returns 0 rendered frames when the song end is reached. Subsequent reads will continue playing from the loop start (if the song is not programmed to loop, playback resumed from the song start).
    - "stop": Returns 0 rendered frames when the song end is reached. Subsequent reads will return 0 rendered frames.
  - play.tempo_factor (floatingpoint): Set a floating point tempo factor. "1.0" is the default tempo.
  - play.pitch_factor (floatingpoint): Set a floating point pitch factor. "1.0" is the default pitch.
  - render.resampler.emulate_amiga (boolean): 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.
  - render.resampler.emulate_amiga_type (string): Configures the filter type to use for the Amiga resampler. Supported values are:
    - "auto": Filter type is chosen by the library and might change. This is the default.
    - "a500": Amiga A500 filter.
    - "a1200": Amiga A1200 filter.
    - "unfiltered": BLEP synthesis without model-specific filters. The LED filter is ignored by this setting. This filter mode is considered to be experimental and might change in the future.
  - render.opl.volume_factor (floatingpoint): Set volume factor applied to synthesized OPL sounds, relative to the default OPL volume.
  - dither (integer): 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

An exclamation mark ("!") or a question mark ("?") can be appended to any ctl key in order to influence the behaviour in case of an unknown ctl key. "!" causes an exception to be thrown; "?" causes the ctl to be silently ignored. In case neither is appended to the key name, unknown init_ctls are ignored by default and other ctls throw an exception by default.

## ◆ get_current_channel_vu_left()

LIBOPENMPT_CXX_API_MEMBER float openmpt::module::get_current_channel_vu_left | ( | std::int32_t | channel | ) | const

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

Parameters

  channel | The 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.

## ◆ get_current_channel_vu_mono()

LIBOPENMPT_CXX_API_MEMBER float openmpt::module::get_current_channel_vu_mono | ( | std::int32_t | channel | ) | const

Get an approximate indication of the channel volume.

Parameters

  channel | The 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.

## ◆ get_current_channel_vu_rear_left()

LIBOPENMPT_CXX_API_MEMBER float openmpt::module::get_current_channel_vu_rear_left | ( | std::int32_t | channel | ) | const

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

Parameters

  channel | The 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.

## ◆ get_current_channel_vu_rear_right()

LIBOPENMPT_CXX_API_MEMBER float openmpt::module::get_current_channel_vu_rear_right | ( | std::int32_t | channel | ) | const

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

Parameters

  channel | The 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.

## ◆ get_current_channel_vu_right()

LIBOPENMPT_CXX_API_MEMBER float openmpt::module::get_current_channel_vu_right | ( | std::int32_t | channel | ) | const

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

Parameters

  channel | The 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.

## ◆ get_current_estimated_bpm()

LIBOPENMPT_CXX_API_MEMBER double openmpt::module::get_current_estimated_bpm | ( |  | ) | const

Get the current estimated beats per minute (BPM).

Remarks
  Many module formats lack time signature metadata. It is common that this estimate is off by a factor of two, but other multipliers are also possible.
  Due to the nature of how module tempo works, the estimate may change slightly after switching libopenmpt's output to a different sample rate.

Returns
  The current estimated BPM.

## ◆ get_current_order()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_current_order | ( |  | ) | const

Get the current order.

Returns
  The current order at which the module is being played back.

## ◆ get_current_pattern()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_current_pattern | ( |  | ) | const

Get the current pattern.

Returns
  The current pattern that is being played.

## ◆ get_current_playing_channels()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_current_playing_channels | ( |  | ) | const

Get the current amount of playing channels.

Returns
  The amount of sample channels that are currently being rendered.

## ◆ get_current_row()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_current_row | ( |  | ) | const

Get the current row.

Returns
  The current row at which the current pattern is being played.

## ◆ get_current_sequence()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_current_sequence | ( |  | ) | const

Get the current sequence.

Returns
  The sequence (order list) in which the currently playing subsong is located.

Remarks
  There is no corresponding setter function. The current sequence is adjusted automatically by selecting a different subsong.
  One sequence can contain multiple subsongs. Most module formats only support a single sequence, hence the return value of this function will often be 0 even in modules that contain multiple subsongs.

Since
  0.9.0

## ◆ get_current_speed()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_current_speed | ( |  | ) | const

Get the current speed.

Returns
  The current speed in ticks per row.

## ◆ get_current_tempo()

LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_current_tempo | ( |  | ) | const

Get the current tempo.

Returns
  The current tempo in tracker units. The exact meaning of this value depends on the tempo mode being used.

Deprecated
  Please use openmpt::module::get_current_tempo2().

## ◆ get_current_tempo2()

LIBOPENMPT_CXX_API_MEMBER double openmpt::module::get_current_tempo2 | ( |  | ) | const

Get the current tempo.

Returns
  The current tempo in tracker units. The exact meaning of this value depends on the tempo mode being used.

Since
  0.7.0

## ◆ get_duration_seconds()

LIBOPENMPT_CXX_API_MEMBER double openmpt::module::get_duration_seconds | ( |  | ) | const

Get approximate song duration.

Returns
  Approximate duration of current sub-song in seconds.

Remarks
  The function may return infinity if the pattern data is too complex to evaluate.

## ◆ get_instrument_names()

LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > openmpt::module::get_instrument_names | ( |  | ) | const

Get a list of instrument names.

Returns
  All instrument names.

See also
  openmpt::module::get_num_instruments

## ◆ get_metadata()

LIBOPENMPT_CXX_API_MEMBER std::string openmpt::module::get_metadata | ( | const std::string & | key | ) | const

Get a metadata item value.

Parameters

  key | Metadata 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) or another similar identifier for modules formats that typically do not use a file extension type_long: Format name associated with the module format (e.g. Impulse Tracker) originaltype: Module format extension (e.g. it) of the original module in case the actual type is a converted format (e.g. mo3 or gdm) originaltype_long: Format name associated with the module format (e.g. Impulse Tracker) of the original module in case the actual type is a converted format (e.g. mo3 or gdm) 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

## ◆ get_metadata_keys()

LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > openmpt::module::get_metadata_keys | ( |  | ) | const

Get the list of supported metadata item keys.

Returns
  Metadata item keys supported by openmpt::module::get_metadata

See also
  openmpt::module::get_metadata

## ◆ get_num_channels()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_num_channels | ( |  | ) | const

Get the number of pattern channels.

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.

## ◆ get_num_instruments()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_num_instruments | ( |  | ) | const

Get the number of instruments.

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.

## ◆ get_num_orders()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_num_orders | ( |  | ) | const

Get the number of orders.

Returns
  The number of orders in the current sequence of the module.

## ◆ get_num_patterns()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_num_patterns | ( |  | ) | const

Get the number of patterns.

Returns
  The number of distinct patterns in the module.

## ◆ get_num_samples()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_num_samples | ( |  | ) | const

Get the number of samples.

Returns
  The number of sample slots in the module.

## ◆ get_num_subsongs()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_num_subsongs | ( |  | ) | const

Get the number of sub-songs.

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_names, openmpt::module::select_subsong, openmpt::module::get_selected_subsong

## ◆ get_order_names()

LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > openmpt::module::get_order_names | ( |  | ) | const

Get a list of order names.

Returns
  All order names.

See also
  openmpt::module::get_num_orders

## ◆ get_order_pattern()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_order_pattern | ( | std::int32_t | order | ) | const

Get pattern at order position.

Parameters

  order | The order item whose pattern index should be retrieved.

Returns
  The pattern index found at the given order position of the current sequence.

## ◆ get_pattern_names()

LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > openmpt::module::get_pattern_names | ( |  | ) | const

Get a list of pattern names.

Returns
  All pattern names.

See also
  openmpt::module::get_num_patterns

## ◆ get_pattern_num_rows()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_pattern_num_rows | ( | std::int32_t | pattern | ) | const

Get the number of rows in a pattern.

Parameters

  pattern | The 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.

## ◆ get_pattern_row_channel_command()

LIBOPENMPT_CXX_API_MEMBER std::uint8_t openmpt::module::get_pattern_row_channel_command | ( | std::int32_t | pattern,
|  | std::int32_t | row,
|  | std::int32_t | channel,
|  | int | command ) const

Get raw pattern content.

Parameters

  pattern | The pattern whose data should be retrieved.
  row | The row from which the data should be retrieved.
  channel | The channel from which the data should be retrieved.
  command | The cell index at which the data should be retrieved. See openmpt::module::command_index

Returns
  The internal, raw pattern data at the given pattern position.

## ◆ get_pattern_rows_per_beat()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_pattern_rows_per_beat | ( | std::int32_t | pattern | ) | const

Get the rows per beat of a pattern.

Parameters

  pattern | The pattern whose time signature should be retrieved.

Returns
  The rows per beat of the given pattern. If the pattern does not exist or the time signature is not defined, 0 is returned.

Remarks
  Many module formats lack time signature metadata. In this case, the returned value may be an incorrect estimation.

Since
  0.8.0

## ◆ get_pattern_rows_per_measure()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_pattern_rows_per_measure | ( | std::int32_t | pattern | ) | const

Get the rows per measure of a pattern.

Parameters

  pattern | The pattern whose time signature should be retrieved.

Returns
  The rows per measure of the given pattern. If the pattern does not exist or the time signature is not defined, 0 is returned.

Remarks
  Many module formats lack time signature metadata. In this case, the returned value may be an incorrect estimation.

Since
  0.8.0

## ◆ get_position_seconds()

LIBOPENMPT_CXX_API_MEMBER double openmpt::module::get_position_seconds | ( |  | ) | const

Get current song position.

Returns
  Current song position in seconds.

See also
  openmpt::module::set_position_seconds

## ◆ get_render_param()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_render_param | ( | int | param | ) | const

Get render parameter.

Parameters

  param | Parameter to query. See openmpt::module::render_param.

Returns
  The current value of the parameter.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception if param is invalid.

See also
  openmpt::module::render_param
  openmpt::module::set_render_param

## ◆ get_repeat_count()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_repeat_count | ( |  | ) | const

Get Repeat Count.

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

## ◆ get_restart_order()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_restart_order | ( | std::int32_t | subsong | ) | const

Get the restart order of the specified sub-song.

Parameters

  subsong | Index of the sub-song to retrieve the restart position from.

Returns
  The restart order of the specified sub-song. This is the order to which playback returns after the last pattern row of the song has been played.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception if sub-song is not in range [0,openmpt::module::get_num_subsongs()[

See also
  openmpt::module::get_restart_row

Since
  0.8.0

## ◆ get_restart_row()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_restart_row | ( | std::int32_t | subsong | ) | const

Get the restart row of the specified sub-song.

Parameters

  subsong | Index of the sub-song to retrieve the restart position from.

Returns
  The restart row of the specified sub-song. This is the first played row of the order to which playback returns after the last pattern row of the song has been played.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception if sub-song is not in range [0,openmpt::module::get_num_subsongs()[

See also
  openmpt::module::get_restart_order

Since
  0.8.0

## ◆ get_sample_names()

LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > openmpt::module::get_sample_names | ( |  | ) | const

Get a list of sample names.

Returns
  All sample names.

See also
  openmpt::module::get_num_samples

## ◆ get_selected_subsong()

LIBOPENMPT_CXX_API_MEMBER std::int32_t openmpt::module::get_selected_subsong | ( |  | ) | const

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

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_names

Since
  0.3.0

## ◆ get_subsong_names()

LIBOPENMPT_CXX_API_MEMBER std::vector< std::string > openmpt::module::get_subsong_names | ( |  | ) | const

Get a list of sub-song names.

Returns
  All sub-song names.

See also
  openmpt::module::get_num_subsongs, openmpt::module::select_subsong, openmpt::module::get_selected_subsong

## ◆ get_time_at_position()

LIBOPENMPT_CXX_API_MEMBER double openmpt::module::get_time_at_position | ( | std::int32_t | order,
|  | std::int32_t | row ) const

Get approximate playback time in seconds at given position.

Parameters

  order | The order position at which the time should be retrieved.
  row | The pattern row number at which the time should be retrieved.

Returns
  Approximate playback time in seconds of current sub-song at the start of the given order and row combination. Negative if the position does not exist, or the pattern data is too complex to evaluate.

Remarks
  If an order / row combination is played multiple times (e.g. due the pattern loops), the first occurence of this position is returned.

Since
  0.8.0

## ◆ highlight_pattern_row_channel()

LIBOPENMPT_CXX_API_MEMBER std::string openmpt::module::highlight_pattern_row_channel | ( | std::int32_t | pattern,
|  | std::int32_t | row,
|  | std::int32_t | channel,
|  | std::size_t | width = 0,
|  | bool | pad = true ) const

Get highlighting information for formatted pattern content.

Parameters

  pattern | The pattern whose data should be retrieved.
  row | The row from which the data should be retrieved.
  channel | The channel from which the data should be retrieved.
  width | The maximum number of characters the string should contain. 0 means no limit.
  pad | If 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

## ◆ highlight_pattern_row_channel_command()

LIBOPENMPT_CXX_API_MEMBER std::string openmpt::module::highlight_pattern_row_channel_command | ( | std::int32_t | pattern,
|  | std::int32_t | row,
|  | std::int32_t | channel,
|  | int | command ) const

Get highlighting information for formatted pattern content.

Parameters

  pattern | The pattern whose data should be retrieved.
  row | The row from which the data should be retrieved.
  channel | The channel from which the data should be retrieved.
  command | The cell index at which the data should be retrieved. See openmpt::module::command_index

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

## ◆ is_order_skip_entry()

LIBOPENMPT_CXX_API_MEMBER bool openmpt::module::is_order_skip_entry | ( | std::int32_t | order | ) | const

Check if specified order is a skip ("+++") item.

Parameters

  order | The order index to check.

Returns
  Returns true if the pattern index at the given order position represents a skip item. During playback, this item is ignored and playback resumes at the next order list item.

See also
  openmpt::module::is_order_stop_entry, openmpt::module::is_pattern_skip_item

Since
  0.8.0

## ◆ is_order_stop_entry()

LIBOPENMPT_CXX_API_MEMBER bool openmpt::module::is_order_stop_entry | ( | std::int32_t | order | ) | const

Check if specified order is a stop ("---") item.

Parameters

  order | The order index to check.

Returns
  Returns true if the pattern index at the given order position represents a stop item. When this item is reached, playback continues at the restart position of the current sub-song.

See also
  openmpt::module::is_order_skip_entry, openmpt::module::is_pattern_stop_item

Since
  0.8.0

## ◆ is_pattern_skip_item()

LIBOPENMPT_CXX_API_MEMBER bool openmpt::module::is_pattern_skip_item | ( | std::int32_t | pattern | ) | const

Check if specified pattern index is a skip ("+++") item.

Parameters

  pattern | The pattern index to check.

Returns
  Returns true if the pattern index represents a skip item. During playback, this item is ignored and playback resumes at the next order list item.

See also
  openmpt::module::is_pattern_stop_item, openmpt::module::is_order_skip_entry, openmpt::module::get_order_pattern

Since
  0.8.0

## ◆ is_pattern_stop_item()

LIBOPENMPT_CXX_API_MEMBER bool openmpt::module::is_pattern_stop_item | ( | std::int32_t | pattern | ) | const

Check if specified pattern index is a stop ("---") item.

Parameters

  pattern | The pattern index to check.

Returns
  Returns true if the pattern index represents a stop item. When this item is reached, playback continues at the restart position of the current sub-song.

See also
  openmpt::module::is_pattern_skip_item, openmpt::module::is_order_stop_entry, openmpt::module::get_order_pattern

Since
  0.8.0

## ◆ read() [1/6]

LIBOPENMPT_CXX_API_MEMBER std::size_t openmpt::module::read | ( | std::int32_t | samplerate,
|  | std::size_t | count,
|  | float * | left,
|  | float * | right )

Render audio data.

Parameters

  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  left | Pointer to a buffer of at least count elements that receives the left output.
  right | Pointer to a buffer of at least count elements that receives the right output.

Returns
  The number of frames actually rendered.

Return values

  0 | The 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 "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

## ◆ read() [2/6]

LIBOPENMPT_CXX_API_MEMBER std::size_t openmpt::module::read | ( | std::int32_t | samplerate,
|  | std::size_t | count,
|  | float * | left,
|  | float * | right,
|  | float * | rear_left,
|  | float * | rear_right )

Render audio data.

Parameters

  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  left | Pointer to a buffer of at least count elements that receives the left output.
  right | Pointer to a buffer of at least count elements that receives the right output.
  rear_left | Pointer to a buffer of at least count elements that receives the rear left output.
  rear_right | Pointer to a buffer of at least count elements that receives the rear right output.

Returns
  The number of frames actually rendered.

Return values

  0 | The 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 "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

## ◆ read() [3/6]

LIBOPENMPT_CXX_API_MEMBER std::size_t openmpt::module::read | ( | std::int32_t | samplerate,
|  | std::size_t | count,
|  | float * | mono )

Render audio data.

Parameters

  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  mono | Pointer to a buffer of at least count elements that receives the mono/center output.

Returns
  The number of frames actually rendered.

Return values

  0 | The 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 "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

## ◆ read() [4/6]

LIBOPENMPT_CXX_API_MEMBER std::size_t openmpt::module::read | ( | std::int32_t | samplerate,
|  | std::size_t | count,
|  | std::int16_t * | left,
|  | std::int16_t * | right )

Render audio data.

Parameters

  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  left | Pointer to a buffer of at least count elements that receives the left output.
  right | Pointer to a buffer of at least count elements that receives the right output.

Returns
  The number of frames actually rendered.

Return values

  0 | The 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 "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

## ◆ read() [5/6]

LIBOPENMPT_CXX_API_MEMBER std::size_t openmpt::module::read | ( | std::int32_t | samplerate,
|  | std::size_t | count,
|  | std::int16_t * | left,
|  | std::int16_t * | right,
|  | std::int16_t * | rear_left,
|  | std::int16_t * | rear_right )

Render audio data.

Parameters

  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  left | Pointer to a buffer of at least count elements that receives the left output.
  right | Pointer to a buffer of at least count elements that receives the right output.
  rear_left | Pointer to a buffer of at least count elements that receives the rear left output.
  rear_right | Pointer to a buffer of at least count elements that receives the rear right output.

Returns
  The number of frames actually rendered.

Return values

  0 | The 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 "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

## ◆ read() [6/6]

LIBOPENMPT_CXX_API_MEMBER std::size_t openmpt::module::read | ( | std::int32_t | samplerate,
|  | std::size_t | count,
|  | std::int16_t * | mono )

Render audio data.

Parameters

  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  mono | Pointer to a buffer of at least count elements that receives the mono/center output.

Returns
  The number of frames actually rendered.

Return values

  0 | The 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 "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

## ◆ read_interleaved_quad() [1/2]

LIBOPENMPT_CXX_API_MEMBER std::size_t openmpt::module::read_interleaved_quad | ( | std::int32_t | samplerate,
|  | std::size_t | count,
|  | float * | interleaved_quad )

Render audio data.

Parameters

  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  interleaved_quad | Pointer to a buffer of at least count*4 elements that receives the interleaved quad surround output in the order (L,R,RL,RR).

Returns
  The number of frames actually rendered.

Return values

  0 | The 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 "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

## ◆ read_interleaved_quad() [2/2]

LIBOPENMPT_CXX_API_MEMBER std::size_t openmpt::module::read_interleaved_quad | ( | std::int32_t | samplerate,
|  | std::size_t | count,
|  | std::int16_t * | interleaved_quad )

Render audio data.

Parameters

  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  interleaved_quad | Pointer to a buffer of at least count*4 elements that receives the interleaved quad surround output in the order (L,R,RL,RR).

Returns
  The number of frames actually rendered.

Return values

  0 | The 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 "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

## ◆ read_interleaved_stereo() [1/2]

LIBOPENMPT_CXX_API_MEMBER std::size_t openmpt::module::read_interleaved_stereo | ( | std::int32_t | samplerate,
|  | std::size_t | count,
|  | float * | interleaved_stereo )

Render audio data.

Parameters

  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  interleaved_stereo | Pointer 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

  0 | The 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 "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

## ◆ read_interleaved_stereo() [2/2]

LIBOPENMPT_CXX_API_MEMBER std::size_t openmpt::module::read_interleaved_stereo | ( | std::int32_t | samplerate,
|  | std::size_t | count,
|  | std::int16_t * | interleaved_stereo )

Render audio data.

Parameters

  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  interleaved_stereo | Pointer 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

  0 | The 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 "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

## ◆ select_subsong()

LIBOPENMPT_CXX_API_MEMBER void openmpt::module::select_subsong | ( | std::int32_t | subsong | ) |

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

Parameters

  subsong | Index of the sub-song. -1 plays all sub-songs consecutively.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception if sub-song is not in range [-1,openmpt::module::get_num_subsongs()[

See also
  openmpt::module::get_num_subsongs, openmpt::module::get_selected_subsong, openmpt::module::get_subsong_names

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.

## ◆ set_position_order_row()

LIBOPENMPT_CXX_API_MEMBER double openmpt::module::set_position_order_row | ( | std::int32_t | order,
|  | std::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

  order | Pattern order number to seek to.
  row | Pattern row number to seek to.

Returns
  Approximate new song position in seconds.

See also
  openmpt::module::set_position_seconds
  openmpt::module::get_position_seconds

## ◆ set_position_seconds()

LIBOPENMPT_CXX_API_MEMBER double openmpt::module::set_position_seconds | ( | double | seconds | ) |

Set approximate current song position.

Parameters

  seconds | Seconds 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

## ◆ set_render_param()

LIBOPENMPT_CXX_API_MEMBER void openmpt::module::set_render_param | ( | int | param,
|  | std::int32_t | value )

Set render parameter.

Parameters

  param | Parameter to set. See openmpt::module::render_param.
  value | The value to set param to.

Exceptions

  openmpt::exception | Throws an exception derived from openmpt::exception if param is invalid or value is out of range.

See also
  openmpt::module::render_param
  openmpt::module::get_render_param

## ◆ set_repeat_count()

LIBOPENMPT_CXX_API_MEMBER void openmpt::module::set_repeat_count | ( | std::int32_t | repeat_count | ) |

Set Repeat Count.

Parameters

  repeat_count | 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::get_repeat_count

## Friends And Related Symbol Documentation

## ◆ module_ext

friend class module_ext
| friend

The documentation for this class was generated from the following file:

- libopenmpt/libopenmpt.hpp