Author Topic: [Ruby] FMOD Low-Level API Wrapper  (Read 444 times)

Offline ForeverZer0

  • CP's Pedophile
  • Global Moderator
  • Guardian of Chaos
  • ****
  • Posts: 3255
  • LV: 298
  • Gender: Male
  • Remember you are unique, just like everyone else.
    • View Profile
[Ruby] FMOD Low-Level API Wrapper
« on: March 22, 2018, 11:52:32 PM »
Introduction
I was in need of a good audio API when working on a C# application, and was unable to find an existing library that fit my needs, so I ended up making my own using the FMOD Low-Level API (the predecessor to the legacy FmodEx). After working with FMOD, and learning the ins-and-outs of how it worked, I saw the potential for making a Ruby port as well. Searching online turned up very little as far as any type of wrapper that could ever be considered close to complete, and only had the basic functionality of FMOD implemented. This including existing RPG Maker scripts that wrapped the basic functionality of the old FmodEx, but nothing more. This prompted me to write my own wrapper.

Being my programming experience begin with Chaos Project and old Ruby 1.8.2, I decided to write in a way that would remain compatible with old versions of Ruby, and foregoing using any Ruby gems or functionality that didn't exist in Ruby 1.8.2, and decided to stick with using Win32API to wrap the FMOD functions, and didn't allow myself the convenience of using a new library like Fiddle of FFI to make things simple.

Currently, the project is approaching the alpha stage. Nearly ALL core functions are implemented, but there has been no in-depth testing yet, and there are still a few mostly uncommon functionalities that need worked on. I have spent A LOT of time making documentation for it, as it is a huge API that definitely has a learning curve. If you don't believe me, see the spoiler.

(click to show/hide)

In the future, I will be releasing this as a gem, but as it stands now, the project can be loaded into RPG Maker with a simple "require", and built upon that. I may even create a basic Audio module rewrite with this codebase in the future, but if anyone else feels like doing it, feel free to check out the code and build upon it for RPG Maker Audio module.


Features
  • Support for 20+ audio formats "out of the box", including all the RPG Maker standards (.mp3, .ogg, .mid, .wma, ect.) with support for more via a plugin system using existing FMOD plugins libraries
  • All basic playback control (play, pause, resume, seek, volume, etc, etc.) that you would expect of any audio player.
  • 20+ built-in effects for sound, including pitch shifting, flange, advanced reverb environments, multi-band parametric equalizer, chorus, tremolo, oscillator,  and many, many more.
  • Streaming of all audio formats, not just MP3
  • Full 3D and 2D support, with distance/directional based sound, each with own reverb environment.
  • Support for custom speaker setups, full surround sound support for up to 12 speakers.
  • Driver selection.
  • Supports music tags (ID3, etc) if that's your thing...
  • Much, much more.

As I stated above, this project is still in its infancy, but already far surpasses any existing audio API that I could find for the Ruby language, and because I love you all, I kept it compatible with RPG Maker XP and above.

This post is meant to a preview for a full release, and I would recommend not to port it as it currently is in a completed project. As so much yet is untested to any passable standard, lacks complete protection against segmentation faults, etc.


Download

Scipts

FMOD DLL (Required)

Documentation

Source - Github


Getting Started

Download the scripts, place unzipped directory in RPG Maker project folder along with the downloaded FMOD dll.
Open script editor, add the line:
Code: [Select]
require File.expand_path('lib/fmod')
Just to give you idea to get started, snippet to play a sound:
Code: [Select]
sys = FMOD::System.create
sound = sys.create_sound('My Audio File.mp3')
sys.play_sound(sound)

Things to remember, the documentation, which is posted above, is currently lacking a lot of examples, so feel free to download the help file from FMOD's website, which can still be helpful on how to do things until the examples are created.

The documentation is not compiled, but can simply be unzipped and opening the "index" file within, which will open it in your browser.

FMOD object's need disposed! Once you are done using a sound, system, etc, call dispose or release on it to free the underlying handle. Obviously this behavior would be taken care of automatically when ported to RPG Maker. This is a developer's API, not an end-user product.

Below is generic audio module I wrote real quick just as an example as an example. It is already far more capable than the built-in Audio, but really more intended as just boiler-plate code.
(click to show/hide)








« Last Edit: March 23, 2018, 09:55:02 PM by ForeverZer0 »
I am done scripting for RMXP. I will likely not offer support for even my own scripts anymore, but feel free to ask on the forum, there are plenty of other talented scripters that can help you.

Offline G_G

  • Green Gmod Game_Guy AKA G4 AKA hyper-G AKA G-force
  • Global Moderator
  • Chaos Ultimate
  • ****
  • Posts: 6591
  • LV: 407
  • Gender: Male
    • View Profile
Re: [Ruby] FMOD Low-Level API Wrapper
« Reply #1 on: March 23, 2018, 12:11:39 AM »
Extremely impressive Zer0! I remember you talking about this awhile ago, cool to actually see it now. Can't wait to see KK20 be enslaved to make an RM script for it. You should definitely come back into discord every once in awhile too, its fun to catch up and we all share are programming rambles there.

Awesome job man.

Offline ForeverZer0

  • CP's Pedophile
  • Global Moderator
  • Guardian of Chaos
  • ****
  • Posts: 3255
  • LV: 298
  • Gender: Male
  • Remember you are unique, just like everyone else.
    • View Profile
Re: [Ruby] FMOD Low-Level API Wrapper
« Reply #2 on: March 23, 2018, 12:24:18 AM »
I am not really pleased with the structs or enum implementation.

For structs, inheriting from Struct.new(:whatever) is a little bit of a no-no, since you are also creating an anonymous class that never gets used. I used it as a bit of shortcut to writing all the attr_accessors and initializers manually, but it is not really the best practice to do that.

As far as the Enum class goes, I had a perfect idea to implement that better, using simple symbols or integers, without the need of enclosing it within the parent enum class, but now that it is so far integrated, it is going to be a painful change to alter all of the methods that use en enum, which is a few hundred.

And still more documentation with examples. I have spent far more time documenting than even writing code, getting really sick of it, lol.
I am done scripting for RMXP. I will likely not offer support for even my own scripts anymore, but feel free to ask on the forum, there are plenty of other talented scripters that can help you.

Offline Blizzard

  • This sexy
  • Administrator
  • has over 9000 posts
  • *****
  • Posts: 19998
  • LV: 651
  • Gender: Male
  • Magic midgets.
    • View Profile
    • You're already on it. (-_-')
Re: [Ruby] FMOD Low-Level API Wrapper
« Reply #3 on: March 23, 2018, 07:45:19 PM »
<3

What MIDI synthesizer are you using?
Check out Daygames and our games:

King of Booze      King of Booze: Never Ever      Pet Bots
Drinking Game for Android      Never have I ever for Android      Pet Bots for Android
Drinking Game for iOS      Never have I ever for iOS      Pet Bots for iOS
Drinking Game on Steam


Quote from: winkio
I do not speak to bricks, either as individuals or in wall form.

Quote from: Barney Stinson
When I get sad, I stop being sad and be awesome instead. True story.

Offline ForeverZer0

  • CP's Pedophile
  • Global Moderator
  • Guardian of Chaos
  • ****
  • Posts: 3255
  • LV: 298
  • Gender: Male
  • Remember you are unique, just like everyone else.
    • View Profile
Re: [Ruby] FMOD Low-Level API Wrapper
« Reply #4 on: March 23, 2018, 08:06:15 PM »
MIDI control is native to FMOD, I am not 100% sure if uses its own, or just chooses based on the platform. Considering FMOD is used on about every kind of hardware and video game console out there, I imagine it probably uses its own for consistency. The documentation is a little light on the actual internal codecs, etc. and how they work.

It does have great MIDI support built-in, though, per MIDI channel gain, sound fonts, etc.

These methods in the Sound class deal with MIDI volumes, etc.
(click to show/hide)
I am done scripting for RMXP. I will likely not offer support for even my own scripts anymore, but feel free to ask on the forum, there are plenty of other talented scripters that can help you.

Offline Blizzard

  • This sexy
  • Administrator
  • has over 9000 posts
  • *****
  • Posts: 19998
  • LV: 651
  • Gender: Male
  • Magic midgets.
    • View Profile
    • You're already on it. (-_-')
Re: [Ruby] FMOD Low-Level API Wrapper
« Reply #5 on: March 23, 2018, 09:39:16 PM »
Nice. If now somebody could pull the samples out of XP, we'd finally have a worthy MIDI audio replacement. xD
Check out Daygames and our games:

King of Booze      King of Booze: Never Ever      Pet Bots
Drinking Game for Android      Never have I ever for Android      Pet Bots for Android
Drinking Game for iOS      Never have I ever for iOS      Pet Bots for iOS
Drinking Game on Steam


Quote from: winkio
I do not speak to bricks, either as individuals or in wall form.

Quote from: Barney Stinson
When I get sad, I stop being sad and be awesome instead. True story.

Offline ForeverZer0

  • CP's Pedophile
  • Global Moderator
  • Guardian of Chaos
  • ****
  • Posts: 3255
  • LV: 298
  • Gender: Male
  • Remember you are unique, just like everyone else.
    • View Profile
Re: [Ruby] FMOD Low-Level API Wrapper
« Reply #6 on: March 23, 2018, 09:59:51 PM »
Nice. If now somebody could pull the samples out of XP, we'd finally have a worthy MIDI audio replacement. xD

Added a generic Audio module as an example to get started with. Even in its basic form, already far more capable than RMXP.
  • Backwards compatible
  • Tempo changing
  • Adding DSP effects
  • Frequency changing
  • Pause, seek, etc. functions

I did not yet implement checking if sound is disabled via the properties of RMXP. I can add that snippet as well soon, as it is little complicated reading the registry keys.
I am done scripting for RMXP. I will likely not offer support for even my own scripts anymore, but feel free to ask on the forum, there are plenty of other talented scripters that can help you.