Ruby OpenMPT (ffi-openmpt)

Robert Haines

Synopsys

A ruby interface to libopenmpt - part of OpenMPT.

See the libopenmpt homepage for more information.

Prerequisits

libopenmpt

You must have libopenmpt installed. On Ubuntu this is done with:

$ sudo apt install libopenmpt0

You do not need the libopenmpt development libraries to be installed.

Instructions for installing libopenmpt from source are available on the libopenmpt homepage.

Ruby FFI

This library uses Ruby FFI (foreign function interface) to wrap the C API for libopenmpt. It will be installed automatically if you install this package via Ruby Gems, otherwise:

$ gem install ffi

will do the trick.

Installation

Add ffi-openmpt to your .gemspec or Gemfile as appropriate, or install directly from Ruby Gems:

$ gem install ffi-openmpt

Usage

The library wraps the C libopenmpt API directly: methods have the same name and signature as their C counterparts. A more friendly ruby-like interface is in development, which will hide the FFI details as much as possible.

Not all libopenmpt methods are wrapped yet, but enough functionality is supplied to load a module, interogate it and render it to a PCM stream.

A note on strings returned by `libopenmpt`

libopenmpt manages the memory of any strings it returns. This means that you must free up such memory explicitly after you have finished with them. Such strings are returned to ruby as FFI::Pointer objects, so the string value can be copied to a ruby string as follows:

include FFI::OpenMPT::API
ptr = openmpt_get_string('url')
str = ptr.read_string
openmpt_free_string(ptr)
puts str

Library versions

Until this library reaches version 1.0.0 the API may be subject to breaking changes. When version 1.0.0 is released, then the principles of semantic versioning will be applied.

Licence

The Ruby OpenMPT code (ffi-openmpt) is released under the BSD licence.

See LICENCE for more details.

Acknowledgements

For testing purposes, this library uses and distributes 'The Last Sun' by Frederic Hahn. It is believed to be in the Public Domain, but if this is not the case please raise an issue to let me know.