libopenmpt 0.5.0-pre.5+r11801 cross-platform C++ and C library to decode tracked music files

Public Types | Public Member Functions | Friends | List of all members
openmpt::module Class Reference

`#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
| 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. More...
| 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())
| 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())
| 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())
| module (const std::vector< char > &data, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
| module (const char *beg, const char *end, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
| 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())
| 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 | ~module ()
void | select_subsong (std::int32_t subsong)
| Select a sub-song from a multi-song module. More...
std::int32_t | get_selected_subsong () const
| Get currently selected sub-song from a multi-song module. More...
void | set_repeat_count (std::int32_t repeat_count)
| Set Repeat Count. More...
std::int32_t | get_repeat_count () const
| Get Repeat Count. More...
double | get_duration_seconds () const
| Get approximate song duration. More...
double | set_position_seconds (double seconds)
| Set approximate current song position. More...
double | get_position_seconds () const
| Get current song position. More...
double | set_position_order_row (std::int32_t order, std::int32_t row)
| Set approximate current song position. More...
std::int32_t | get_render_param (int param) const
| Get render parameter. More...
void | set_render_param (int param, std::int32_t value)
| Set render parameter. More...
std::vector< std::string > | get_metadata_keys () const
| Get the list of supported metadata item keys. More...
std::string | get_metadata (const std::string &key) const
| Get a metadata item value. More...
std::int32_t | get_current_speed () const
| Get the current speed. More...
std::int32_t | get_current_tempo () const
| Get the current tempo. More...
std::int32_t | get_current_order () const
| Get the current order. More...
std::int32_t | get_current_pattern () const
| Get the current pattern. More...
std::int32_t | get_current_row () const
| Get the current row. More...
std::int32_t | get_current_playing_channels () const
| Get the current amount of playing channels. More...
float | get_current_channel_vu_mono (std::int32_t channel) const
| Get an approximate indication of the channel volume. More...
float | get_current_channel_vu_left (std::int32_t channel) const
| Get an approximate indication of the channel volume on the front-left speaker. More...
float | get_current_channel_vu_right (std::int32_t channel) const
| Get an approximate indication of the channel volume on the front-right speaker. More...
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. More...
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. More...
std::int32_t | get_num_subsongs () const
| Get the number of sub-songs. More...
std::int32_t | get_num_channels () const
| Get the number of pattern channels. More...
std::int32_t | get_num_orders () const
| Get the number of orders. More...
std::int32_t | get_num_patterns () const
| Get the number of patterns. More...
std::int32_t | get_num_instruments () const
| Get the number of instruments. More...
std::int32_t | get_num_samples () const
| Get the number of samples. More...
std::vector< std::string > | get_subsong_names () const
| Get a list of sub-song names. More...
std::vector< std::string > | get_channel_names () const
| Get a list of channel names. More...
std::vector< std::string > | get_order_names () const
| Get a list of order names. More...
std::vector< std::string > | get_pattern_names () const
| Get a list of pattern names. More...
std::vector< std::string > | get_instrument_names () const
| Get a list of instrument names. More...
std::vector< std::string > | get_sample_names () const
| Get a list of sample names. More...
std::int32_t | get_order_pattern (std::int32_t order) const
| Get pattern at order position. More...
std::int32_t | get_pattern_num_rows (std::int32_t pattern) const
| Get the number of rows in a pattern. More...
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. More...
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. More...
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. More...
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. More...
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. More...
std::vector< std::string > | get_ctls () const
| Retrieve supported ctl keys. More...
std::string | ctl_get (const std::string &ctl) const
| Get current ctl value. More...
void | ctl_set (const std::string &ctl, const std::string &value)
| Set ctl value. More...
std::size_t | read (std::int32_t samplerate, std::size_t count, std::int16_t *mono)
| Render audio data. More...
std::size_t | read (std::int32_t samplerate, std::size_t count, std::int16_t *left, std::int16_t *right)
| Render audio data. More...
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. More...
std::size_t | read (std::int32_t samplerate, std::size_t count, float *mono)
| Render audio data. More...
std::size_t | read (std::int32_t samplerate, std::size_t count, float *left, float *right)
| Render audio data. More...
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. More...
std::size_t | read_interleaved_stereo (std::int32_t samplerate, std::size_t count, std::int16_t *interleaved_stereo)
| Render audio data. More...
std::size_t | read_interleaved_quad (std::int32_t samplerate, std::size_t count, std::int16_t *interleaved_quad)
| Render audio data. More...
std::size_t | read_interleaved_stereo (std::int32_t samplerate, std::size_t count, float *interleaved_stereo)
| Render audio data. More...
std::size_t | read_interleaved_quad (std::int32_t samplerate, std::size_t count, float *interleaved_quad)
| Render audio data. More...

## 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/8]

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.

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/8]

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.

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() [3/8]

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() [4/8]

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() [5/8]

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() [6/8]

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() [7/8]

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() [8/8]

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 openmpt::module::~module | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ ctl_get()

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

## ◆ ctl_set()

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

## ◆ format_pattern_row_channel()

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()

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()

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()

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: 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.at_end: Chooses the behaviour when the end of song is 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 song start or loop start.
    - "stop": Returns 0 rendered frames when the song end is reached. Subsequent reads will return 0 rendered frames.
  - 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.
  - render.opl.volume_factor: Set volume factor applied to synthesized OPL sounds, relative to the default OPL volume.
  - 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

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()

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()

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()

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()

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()

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_order()

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()

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()

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()

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_speed()

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

Get the current speed.

Returns
  The current speed in ticks per row.

## ◆ get_current_tempo()

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.

## ◆ get_duration_seconds()

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

Get approximate song duration.

Returns
  Approximate duration of current sub-song in seconds.

## ◆ get_instrument_names()

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()

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) 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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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_position_seconds()

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()

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()

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_sample_names()

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()

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()

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

## ◆ highlight_pattern_row_channel()

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()

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

## ◆ read() [1/6]

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() [2/6]

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() [3/6]

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() [4/6]

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() [5/6]

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() [6/6]

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_interleaved_quad() [1/2]

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 suad 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_quad() [2/2]

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 suad 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_stereo() [1/2]

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

## ◆ read_interleaved_stereo() [2/2]

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

## ◆ select_subsong()

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()

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()

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()

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()

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 Function Documentation

## ◆ module_ext

friend class module_ext
| friend

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

- libopenmpt/libopenmpt.hpp