{"id":16546939,"url":"https://github.com/hainesr/ffi-openmpt","last_synced_at":"2025-10-28T15:32:00.705Z","repository":{"id":56846246,"uuid":"145225871","full_name":"hainesr/ffi-openmpt","owner":"hainesr","description":"A Ruby interface to libopenmpt.","archived":false,"fork":false,"pushed_at":"2022-04-14T21:11:20.000Z","size":6508,"stargazers_count":2,"open_issues_count":5,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-08-09T16:54:49.420Z","etag":null,"topics":["ffi","ffi-openmpt","hacktoberfest","libopenmpt","mod","ruby","ruby-ffi"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hainesr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-18T14:18:55.000Z","updated_at":"2022-04-14T21:11:23.000Z","dependencies_parsed_at":"2022-09-09T00:52:33.786Z","dependency_job_id":null,"html_url":"https://github.com/hainesr/ffi-openmpt","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hainesr%2Fffi-openmpt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hainesr%2Fffi-openmpt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hainesr%2Fffi-openmpt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hainesr%2Fffi-openmpt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hainesr","download_url":"https://codeload.github.com/hainesr/ffi-openmpt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219859168,"owners_count":16556037,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ffi","ffi-openmpt","hacktoberfest","libopenmpt","mod","ruby","ruby-ffi"],"created_at":"2024-10-11T19:13:05.699Z","updated_at":"2025-10-28T15:31:55.355Z","avatar_url":"https://github.com/hainesr.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ruby OpenMPT (ffi-openmpt)\n## Robert Haines\n\n### Synopsys\n\nA ruby interface to `libopenmpt` - part of [OpenMPT][mpt-home].\n\nSee the [libopenmpt homepage][lib-home] for more information.\n\n[![Gem Version](https://badge.fury.io/rb/ffi-openmpt.svg)](https://badge.fury.io/rb/ffi-openmpt)\n[![Tests](https://github.com/hainesr/ffi-openmpt/actions/workflows/test.yml/badge.svg)](https://github.com/hainesr/ffi-openmpt/actions/workflows/test.yml)\n[![Linter](https://github.com/hainesr/ffi-openmpt/actions/workflows/lint.yml/badge.svg)](https://github.com/hainesr/ffi-openmpt/actions/workflows/lint.yml)\n[![Maintainability](https://api.codeclimate.com/v1/badges/919bd8b421798dbd2719/maintainability)](https://codeclimate.com/github/hainesr/ffi-openmpt/maintainability)\n[![Coverage Status](https://coveralls.io/repos/github/hainesr/ffi-openmpt/badge.svg?branch=master)](https://coveralls.io/github/hainesr/ffi-openmpt)\n\n### Prerequisits\n\n#### libopenmpt\n\nYou must have `libopenmpt` installed. On Ubuntu this is done with:\n\n```shell\n$ sudo apt install libopenmpt0\n```\n\nYou do not need the `libopenmpt` development libraries to be installed. If this library fails to find `libopenmpt` on your platform it might be due to it being named something slightly different. Please [raise an issue][issues] to let me know.\n\nInstructions for installing `libopenmpt` from source are available on the [libopenmpt homepage][lib-home].\n\n#### Ruby FFI\n\nThis library uses [Ruby FFI][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][rubygems], otherwise:\n\n```shell\n$ gem install ffi\n```\n\nwill do the trick.\n\n### Installation\n\nAdd `ffi-openmpt` to your `.gemspec` or `Gemfile` as appropriate, or install directly from [Ruby Gems][rubygems]:\n\n```shell\n$ gem install ffi-openmpt\n```\n\n### Usage\n\nThe 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 also available, which hides the FFI details as much as possible.\n\nNot all `libopenmpt` methods are wrapped yet, but enough functionality is supplied to load a module, interogate it and render it to a PCM stream.\n\n#### A note on strings returned by `libopenmpt`\n\n`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 when using the C API. Such strings are returned to ruby as [`FFI::Pointer`][ffi-pointer] objects, so the string value can be copied to a ruby string as follows:\n\n```ruby\nbegin\n  ptr = FFI::OpenMPT::API.openmpt_get_string('url')\n  str = ptr.read_string\nensure\n  FFI::OpenMPT::API.openmpt_free_string(ptr)\nend\n\nputs str\n```\n\nThe ruby interface handles all this for you:\n\n```ruby\nstr = FFI::OpenMPT::String.get(:url)\nputs str\n```\n\n### Example scripts\n\nScripts in the `examples` directory show how to use both the C and ruby APIs. You will need to make sure that `ffi-openmpt` is on your `RUBYLIB` path, or run the examples with `bundle exec`.\n\n#### `mod-info` and `mod-info-api`\n\nDisplay information about a mod file, for example:\n\n```shell\n$ ./mod-info lastsun.mod\n\nRuby OpenMPT (ffi-openmpt) file interrogator.\n---------------------------------------------\n\nFilename...: lastsun.mod\nSize.......: 106k\nType.......: mod\nFormat.....: Generic Amiga / PC MOD file\nTracker....: Master Soundtracker 1.0\nTitle......: the last sun\nDuration...: 3:56.4\nSubsongs...: 1\nChannels...: 4\nOrders.....: 35\nPatterns...: 20\nIntruments.: 0\nSamples....: 15\n```\n\nBoth `mod-info` and `mod-info-api` output exactly the same data. `mod-info` uses the ruby interface, and `mod-info-api` uses the mapped `libopenmpt` C API directly.\n\n#### `mod-2-raw`\n\nRender a mod to a raw stereo PCM file. Use the `--float` switch to generate 32 bit float data, or omit for 16bit int data. For example:\n\n```shell\n$ ./mod-2-raw --float lastsun.mod\n\nRuby OpenMPT (ffi-openmpt) Mod to Raw PCM Converter.\n----------------------------------------------------\n\nFilename...: lastsun.mod\nSize.......: 106k\nType.......: mod\nOutput type: float.raw\nOutput size: 88687k\n```\n\nThe raw output format is simply a blob of `float` or `short` data. The left and right stereo channels are interleaved. The sample rate used is 48,000Hz.\n\n### Library versions\n\nUntil 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][semver] will be applied.\n\n### Licence\n\nThe Ruby OpenMPT code (ffi-openmpt) is released under the BSD licence.\n\nCopyright (c) 2018-2021, Robert Haines\nAll rights reserved.\n\nSee LICENCE for more details.\n\n### Acknowledgements\n\nFor testing purposes, this library uses and distributes ['The Last Sun'][lastsun] by Frederic Hahn. It is believed to be in the Public Domain, but if this is not the case please [raise an issue][issues] to let me know.\n\n[ffi-pointer]: https://www.rubydoc.info/github/ffi/ffi/FFI/Pointer\n[issues]: https://github.com/hainesr/ffi-openmpt/issues\n[lastsun]: https://modarchive.org/module.php?47521\n[lib-home]: https://lib.openmpt.org\n[mpt-home]: https://openmpt.org/\n[ruby-ffi]: https://rubygems.org/gems/ffi\n[rubygems]: https://rubygems.org\n[semver]: https://semver.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhainesr%2Fffi-openmpt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhainesr%2Fffi-openmpt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhainesr%2Fffi-openmpt/lists"}