libopenmpt  0.6.3+release.autotools
cross-platform C++ and C library to decode tracked music files
libopenmpt.hpp
Go to the documentation of this file.
1 /*
2  * libopenmpt.hpp
3  * --------------
4  * Purpose: libopenmpt public c++ interface
5  * Notes : (currently none)
6  * Authors: OpenMPT Devs
7  * The OpenMPT source code is released under the BSD license. Read LICENSE for more details.
8  */
9 
10 #ifndef LIBOPENMPT_HPP
11 #define LIBOPENMPT_HPP
12 
13 #include "libopenmpt_config.h"
14 
15 #include <exception>
16 #include <iosfwd>
17 #include <iostream>
18 #include <map>
19 #include <string>
20 #include <string_view>
21 #include <vector>
22 
23 #include <cstddef>
24 #include <cstdint>
25 
130 namespace openmpt {
131 
136 #if defined(_MSC_VER)
137 #pragma warning(push)
138 #pragma warning(disable:4275)
139 #endif
141 
145 class LIBOPENMPT_CXX_API exception : public std::exception {
146 private:
147  char * text;
148 public:
149  exception( const std::string & text ) noexcept;
150  exception( const exception & other ) noexcept;
151  exception( exception && other ) noexcept;
152  exception & operator = ( const exception & other ) noexcept;
153  exception & operator = ( exception && other ) noexcept;
154  virtual ~exception() noexcept;
155  const char * what() const noexcept override;
156 }; // class exception
157 #if defined(_MSC_VER)
158 #pragma warning(pop)
159 #endif
160 
162 
167 LIBOPENMPT_CXX_API std::uint32_t get_library_version();
168 
170 
174 LIBOPENMPT_CXX_API std::uint32_t get_core_version();
175 
176 namespace string {
177 
179 static const char library_version LIBOPENMPT_ATTR_DEPRECATED [] = "library_version";
181 static const char library_features LIBOPENMPT_ATTR_DEPRECATED [] = "library_features";
183 static const char core_version LIBOPENMPT_ATTR_DEPRECATED [] = "core_version";
185 static const char build LIBOPENMPT_ATTR_DEPRECATED [] = "build";
187 static const char credits LIBOPENMPT_ATTR_DEPRECATED [] = "credits";
189 static const char contact LIBOPENMPT_ATTR_DEPRECATED [] = "contact";
191 static const char license LIBOPENMPT_ATTR_DEPRECATED [] = "license";
192 
194 
222 LIBOPENMPT_CXX_API std::string get( const std::string & key );
223 
224 } // namespace string
225 
227 
230 LIBOPENMPT_CXX_API std::vector<std::string> get_supported_extensions();
231 
233 
238 LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API bool is_extension_supported( const std::string & extension );
240 
245 LIBOPENMPT_CXX_API bool is_extension_supported2( std::string_view extension );
246 
248 
260 LIBOPENMPT_CXX_API double could_open_probability( std::istream & stream, double effort = 1.0, std::ostream & log = std::clog );
261 
263 
266 LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API double could_open_propability( std::istream & stream, double effort = 1.0, std::ostream & log = std::clog );
267 
269 
273 LIBOPENMPT_CXX_API std::size_t probe_file_header_get_recommended_size();
274 
276 static const std::uint64_t probe_file_header_flags_modules LIBOPENMPT_ATTR_DEPRECATED = 0x1ull;
277 
279 static const std::uint64_t probe_file_header_flags_containers LIBOPENMPT_ATTR_DEPRECATED = 0x2ull;
280 
282 static const std::uint64_t probe_file_header_flags_default LIBOPENMPT_ATTR_DEPRECATED = 0x1ull | 0x2ull;
283 
285 static const std::uint64_t probe_file_header_flags_none LIBOPENMPT_ATTR_DEPRECATED = 0x0ull;
286 
288 enum probe_file_header_flags : std::uint64_t {
297 };
298 
304 };
305 
307 
321 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::byte * data, std::size_t size, std::uint64_t filesize );
323 
337 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::uint8_t * data, std::size_t size, std::uint64_t filesize );
338 
340 
354 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::byte * data, std::size_t size );
356 
370 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::uint8_t * data, std::size_t size );
371 
373 
385 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, std::istream & stream );
386 
387 class module_impl;
388 
389 class module_ext;
390 
391 namespace detail {
392 
393 typedef std::map< std::string, std::string > initial_ctls_map;
394 
395 } // namespace detail
396 
397 class LIBOPENMPT_CXX_API module {
398 
399  friend class module_ext;
400 
401 public:
402 
406 
411  RENDER_MASTERGAIN_MILLIBEL = 1,
413 
418  RENDER_STEREOSEPARATION_PERCENT = 2,
420 
431  RENDER_INTERPOLATIONFILTER_LENGTH = 3,
433 
440  RENDER_VOLUMERAMPING_STRENGTH = 4
441  };
442 
445  command_note = 0,
446  command_instrument = 1,
447  command_volumeffect = 2,
448  command_effect = 3,
449  command_volume = 4,
450  command_parameter = 5
451  };
452 
453 private:
454  module_impl * impl;
455 private:
456  // non-copyable
457  module( const module & );
458  void operator = ( const module & );
459 private:
460  // for module_ext
461  module();
462  void set_impl( module_impl * i );
463 public:
465 
473  module( std::istream & stream, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
483  module( const std::vector<std::byte> & data, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
494  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() );
505  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() );
514  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() );
524  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() );
534  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() );
543  module( const std::vector<char> & data, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
553  module( const char * beg, const char * end, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
563  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() );
573  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() );
574  virtual ~module();
575 public:
576 
578 
584  void select_subsong( std::int32_t subsong );
586 
591  std::int32_t get_selected_subsong() const;
593 
600  void set_repeat_count( std::int32_t repeat_count );
602 
609  std::int32_t get_repeat_count() const;
610 
612 
616  double get_duration_seconds() const;
617 
619 
624  double set_position_seconds( double seconds );
626 
630  double get_position_seconds() const;
631 
633 
641  double set_position_order_row( std::int32_t order, std::int32_t row );
642 
644 
651  std::int32_t get_render_param( int param ) const;
653 
660  void set_render_param( int param, std::int32_t value );
661 
664 
675  std::size_t read( std::int32_t samplerate, std::size_t count, std::int16_t * mono );
677 
689  std::size_t read( std::int32_t samplerate, std::size_t count, std::int16_t * left, std::int16_t * right );
691 
705  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 );
707 
718  std::size_t read( std::int32_t samplerate, std::size_t count, float * mono );
720 
732  std::size_t read( std::int32_t samplerate, std::size_t count, float * left, float * right );
734 
748  std::size_t read( std::int32_t samplerate, std::size_t count, float * left, float * right, float * rear_left, float * rear_right );
750 
761  std::size_t read_interleaved_stereo( std::int32_t samplerate, std::size_t count, std::int16_t * interleaved_stereo );
763 
774  std::size_t read_interleaved_quad( std::int32_t samplerate, std::size_t count, std::int16_t * interleaved_quad );
776 
787  std::size_t read_interleaved_stereo( std::int32_t samplerate, std::size_t count, float * interleaved_stereo );
789 
800  std::size_t read_interleaved_quad( std::int32_t samplerate, std::size_t count, float * interleaved_quad );
804 
808  std::vector<std::string> get_metadata_keys() const;
810 
829  std::string get_metadata( const std::string & key ) const;
830 
832 
839 
842  std::int32_t get_current_speed() const;
844 
847  std::int32_t get_current_tempo() const;
849 
852  std::int32_t get_current_order() const;
854 
857  std::int32_t get_current_pattern() const;
859 
862  std::int32_t get_current_row() const;
864 
867  std::int32_t get_current_playing_channels() const;
868 
870 
875  float get_current_channel_vu_mono( std::int32_t channel ) const;
877 
882  float get_current_channel_vu_left( std::int32_t channel ) const;
884 
889  float get_current_channel_vu_right( std::int32_t channel ) const;
891 
896  float get_current_channel_vu_rear_left( std::int32_t channel ) const;
898 
903  float get_current_channel_vu_rear_right( std::int32_t channel ) const;
904 
906 
910  std::int32_t get_num_subsongs() const;
912 
916  std::int32_t get_num_channels() const;
918 
921  std::int32_t get_num_orders() const;
923 
926  std::int32_t get_num_patterns() const;
928 
931  std::int32_t get_num_instruments() const;
933 
936  std::int32_t get_num_samples() const;
937 
939 
943  std::vector<std::string> get_subsong_names() const;
945 
949  std::vector<std::string> get_channel_names() const;
951 
955  std::vector<std::string> get_order_names() const;
957 
961  std::vector<std::string> get_pattern_names() const;
963 
967  std::vector<std::string> get_instrument_names() const;
969 
973  std::vector<std::string> get_sample_names() const;
974 
976 
980  std::int32_t get_order_pattern( std::int32_t order ) const;
981 
983 
987  std::int32_t get_pattern_num_rows( std::int32_t pattern ) const;
988 
990 
997  std::uint8_t get_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const;
998 
1000 
1008  std::string format_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const;
1009 
1011 
1030  std::string highlight_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const;
1031 
1033 
1042  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;
1044 
1053  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;
1054 
1056 
1086  std::vector<std::string> get_ctls() const;
1087 
1089 
1095  LIBOPENMPT_ATTR_DEPRECATED std::string ctl_get( const std::string & ctl ) const;
1097 
1103  bool ctl_get_boolean( std::string_view ctl ) const;
1105 
1111  std::int64_t ctl_get_integer( std::string_view ctl ) const;
1113 
1119  double ctl_get_floatingpoint( std::string_view ctl ) const;
1121 
1127  std::string ctl_get_text( std::string_view ctl ) const;
1128 
1130 
1137  LIBOPENMPT_ATTR_DEPRECATED void ctl_set( const std::string & ctl, const std::string & value );
1139 
1146  void ctl_set_boolean( std::string_view ctl, bool value );
1148 
1155  void ctl_set_integer( std::string_view ctl, std::int64_t value );
1157 
1164  void ctl_set_floatingpoint( std::string_view ctl, double value );
1166 
1173  void ctl_set_text( std::string_view ctl, std::string_view value );
1174 
1175  // remember to add new functions to both C and C++ interfaces and to increase OPENMPT_API_VERSION_MINOR
1176 
1177 }; // class module
1178 
1183 } // namespace openmpt
1184 
1185 #endif // LIBOPENMPT_HPP
libopenmpt exception base class
Definition: libopenmpt.hpp:145
exception(exception &&other) noexcept
exception(const std::string &text) noexcept
exception(const exception &other) noexcept
virtual ~exception() noexcept
Definition: libopenmpt_ext.hpp:37
Definition: libopenmpt.hpp:397
void set_repeat_count(std::int32_t repeat_count)
Set Repeat Count.
std::vector< std::string > get_subsong_names() const
Get a list of sub-song names.
std::int32_t get_current_row() const
Get the current row.
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.
double set_position_seconds(double seconds)
Set approximate current song position.
std::int32_t get_repeat_count() const
Get Repeat Count.
double get_position_seconds() const
Get current song position.
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.
void ctl_set_floatingpoint(std::string_view ctl, double value)
Set ctl floatingpoint value.
module(const std::vector< std::byte > &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())
std::size_t read(std::int32_t samplerate, std::size_t count, std::int16_t *left, std::int16_t *right)
Render audio data.
virtual ~module()
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.
std::size_t read(std::int32_t samplerate, std::size_t count, std::int16_t *mono)
Render audio data.
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.
std::int32_t get_current_speed() const
Get the current speed.
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.
module(const char *beg, const char *end, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
std::vector< std::string > get_pattern_names() const
Get a list of pattern names.
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())
std::size_t read_interleaved_quad(std::int32_t samplerate, std::size_t count, float *interleaved_quad)
Render audio data.
void ctl_set_integer(std::string_view ctl, std::int64_t value)
Set ctl integer value.
std::vector< std::string > get_order_names() const
Get a list of order names.
std::size_t read_interleaved_stereo(std::int32_t samplerate, std::size_t count, float *interleaved_stereo)
Render audio data.
std::int32_t get_num_subsongs() const
Get the number of sub-songs.
double get_current_estimated_bpm() const
Get the current estimated beats per minute (BPM).
std::int32_t get_num_orders() const
Get the number of orders.
std::int32_t get_num_samples() const
Get the number of samples.
module(const std::vector< char > &data, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
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.
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.
std::int32_t get_current_playing_channels() const
Get the current amount of playing channels.
std::int32_t get_current_order() const
Get the current order.
float get_current_channel_vu_mono(std::int32_t channel) const
Get an approximate indication of the channel volume.
float get_current_channel_vu_right(std::int32_t channel) const
Get an approximate indication of the channel volume on the front-right speaker.
std::int32_t get_current_pattern() const
Get the current pattern.
float get_current_channel_vu_left(std::int32_t channel) const
Get an approximate indication of the channel volume on the front-left speaker.
std::int32_t get_order_pattern(std::int32_t order) const
Get pattern at order position.
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.
std::int32_t get_selected_subsong() const
Get currently selected sub-song from a multi-song module.
std::size_t read(std::int32_t samplerate, std::size_t count, float *mono)
Render audio data.
std::int32_t get_pattern_num_rows(std::int32_t pattern) const
Get the number of rows in a pattern.
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())
std::int32_t get_num_instruments() const
Get the number of instruments.
void set_render_param(int param, std::int32_t value)
Set render parameter.
std::int32_t get_num_patterns() const
Get the number of patterns.
LIBOPENMPT_ATTR_DEPRECATED std::string ctl_get(const std::string &ctl) const
Get current ctl value.
render_param
Parameter index to use with openmpt::module::get_render_param and openmpt::module::set_render_param.
Definition: libopenmpt.hpp:404
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())
double ctl_get_floatingpoint(std::string_view ctl) const
Get current ctl floatingpoint value.
std::int32_t get_num_channels() const
Get the number of pattern channels.
std::size_t read_interleaved_quad(std::int32_t samplerate, std::size_t count, std::int16_t *interleaved_quad)
Render audio data.
command_index
Parameter index to use with openmpt::module::get_pattern_row_channel_command, openmpt::module::format...
Definition: libopenmpt.hpp:444
void ctl_set_boolean(std::string_view ctl, bool value)
Set ctl boolean value.
std::size_t read(std::int32_t samplerate, std::size_t count, float *left, float *right)
Render audio data.
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.
double get_duration_seconds() const
Get approximate song duration.
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())
std::string ctl_get_text(std::string_view ctl) const
Get current ctl text value.
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())
std::int32_t get_current_tempo() const
Get the current tempo.
std::size_t read_interleaved_stereo(std::int32_t samplerate, std::size_t count, std::int16_t *interleaved_stereo)
Render audio data.
std::vector< std::string > get_sample_names() const
Get a list of sample names.
bool ctl_get_boolean(std::string_view ctl) const
Get current ctl boolean value.
std::vector< std::string > get_metadata_keys() const
Get the list of supported metadata item keys.
double set_position_order_row(std::int32_t order, std::int32_t row)
Set approximate current song position.
std::int32_t get_render_param(int param) const
Get render parameter.
std::vector< std::string > get_instrument_names() const
Get a list of instrument names.
std::vector< std::string > get_ctls() const
Retrieve supported ctl keys.
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())
std::vector< std::string > get_channel_names() const
Get a list of channel names.
std::string get_metadata(const std::string &key) const
Get a metadata item value.
void ctl_set_text(std::string_view ctl, std::string_view value)
Set ctl text value.
LIBOPENMPT_ATTR_DEPRECATED void ctl_set(const std::string &ctl, const std::string &value)
Set ctl value.
void select_subsong(std::int32_t subsong)
Select a sub-song from a multi-song module.
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.
std::int64_t ctl_get_integer(std::string_view ctl) const
Get current ctl integer value.
probe_file_header_flags
Possible values for openmpt::probe_file_header() flags parameter.
Definition: libopenmpt.hpp:288
LIBOPENMPT_CXX_API bool is_extension_supported2(std::string_view extension)
Query whether a file extension is supported.
probe_file_header_result
Possible return values for openmpt::probe_file_header().
Definition: libopenmpt.hpp:300
LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API bool is_extension_supported(const std::string &extension)
Query whether a file extension is supported.
static const std::uint64_t probe_file_header_flags_modules LIBOPENMPT_ATTR_DEPRECATED
Probe for module formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:276
LIBOPENMPT_CXX_API double could_open_probability(std::istream &stream, double effort=1.0, std::ostream &log=std::clog)
Roughly scan the input stream to find out whether libopenmpt might be able to open it.
LIBOPENMPT_CXX_API std::vector< std::string > get_supported_extensions()
Get a list of supported file extensions.
LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API double could_open_propability(std::istream &stream, double effort=1.0, std::ostream &log=std::clog)
Roughly scan the input stream to find out whether libopenmpt might be able to open it.
LIBOPENMPT_CXX_API std::uint32_t get_core_version()
Get the core version number.
LIBOPENMPT_CXX_API int probe_file_header(std::uint64_t flags, const std::byte *data, std::size_t size, std::uint64_t filesize)
Probe the provided bytes from the beginning of a file for supported file format headers to find out w...
LIBOPENMPT_CXX_API std::uint32_t get_library_version()
Get the libopenmpt version number.
LIBOPENMPT_CXX_API std::size_t probe_file_header_get_recommended_size()
Get recommended header size for successfull format probing.
@ probe_file_header_flags_none2
Probe for no formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:296
@ probe_file_header_flags_default2
Probe for the default set of formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:294
@ probe_file_header_flags_containers2
Probe for module-specific container formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:292
@ probe_file_header_flags_modules2
Probe for module formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:290
@ probe_file_header_result_success
Definition: libopenmpt.hpp:301
@ probe_file_header_result_failure
Definition: libopenmpt.hpp:302
@ probe_file_header_result_wantmoredata
Definition: libopenmpt.hpp:303
LIBOPENMPT_CXX_API std::string get(const std::string &key)
Get library related metadata.
Definition: libopenmpt.hpp:130