gm_bass3 - A cross plattform shared Lua API to BASS

[Grocel]

This module "gm_bass3" creates GLua bindings to the [URL="http://www.un4seen.com/"]BASS sound API[/URL].

[B]About:[/B]
It will make you able to stream various formats of sound and play them as 3D world sound. You can get the FFT spectrum and tag information of a stream on server and client, while the sound is always muted on servers. So far it is available for Windows and Linux.

Since [URL="http://facepunch.com/showthread.php?t=1159184"]gm_bass2[/URL] is mess and somehow broken, I decided to reprogram it from scratch and release it as gm_bass3.
It should be much more optimized and less prone to errors than the last version. All module functions are designed to behave as like as their counter parts in GMod or are even surpassing them.

Beside the usability on servers it brings new functions like sound balance changing, volume fading and a new function to receive the FFT spectrum as complex numbers. It has proper support for tag information, which I am planning to improve even more.

[B]Documentation and examples:[/B]
[URL="https://github.com/Grocel/GMod_Modules/blob/master/gm_bass3/README.md"]README.md[/URL]

[B]Downloads:[/B]
Windows binaries: [URL="https://github.com/Grocel/GMod_Modules/tree/master/gm_bass3/bin/win32"]GitHub[/URL] [URL="https://github.com/Grocel/GMod_Modules/trunk/gm_bass3/bin/win32"]SVN[/URL]
Linux binaries: [URL="https://github.com/Grocel/GMod_Modules/tree/master/gm_bass3/bin/linux"]GitHub[/URL] [URL="https://github.com/Grocel/GMod_Modules/trunk/gm_bass3/bin/linux"]SVN[/URL]
Source code: [URL="https://github.com/Grocel/GMod_Modules/tree/master/gm_bass3"]GitHub[/URL] [URL="https://github.com/Grocel/GMod_Modules/trunk/gm_bass3"]SVN[/URL]

[B]Filesystem Exporter Plugin download:[/B]
Windows and Linux binaries: [URL="https://github.com/Grocel/GMod_Modules/tree/master/filesys_export/install"]GitHub[/URL] [URL="https://github.com/Grocel/GMod_Modules/trunk/filesys_export/install"]SVN[/URL]
Source code: [URL="https://github.com/Grocel/GMod_Modules/tree/master/filesys_export"]GitHub[/URL] [URL="https://github.com/Grocel/GMod_Modules/trunk/filesys_export"]SVN[/URL]

[B]Installation:[/B]
You put the DLL files for your OS in to the garrysmod/lua/bin/ folder.

On dedicated servers you need the Filesystem Exporter Plugin if you want to use local and mounted content.
To install it you put the binary file for your OS (*.dll or *.so) and the *.vdt file in to the garrysmod/addons/ folder.

[B]Compiling:[/B]
At the first I run the premake script so the project files are generated. For windows I compile the code with Visual Studio 2013. For Linux I use gcc/g++/make on a Linux Mint VirtualBox. If you want to compile it yourself you could get some trouble on Linux, because I had to install like a ton of libraries and stuff I don't even remember to make the compiler work properly. You also need the Source SDK 2013 to compile.

[B]Requirements/Problems:[/B]
- Make sure your game and your server is up to date.
- Maybe you need to manually replace the bass.dll or libbass.so on the server with the latest versions of them. It is located at your_gmodserver/bin/. Only do it if it does not work otherwise.
- As it uses c++11 features you may need to install a c++11 runtime library on your operation system.
- For Linux you need to install [URL="https://wiki.archlinux.org/index.php/Advanced_Linux_Sound_Architecture#Installation"]ALSA[/URL] and give the user that is running the server or the client "rwx" access to the sound device/interface.
- For servers (especially Linux ones) that do not have sound hardware, you need to install a dummy driver. These links might be helpful: [URL="http://superuser.com/questions/344760/how-to-create-a-dummy-sound-card-device-in-linux-server"]1[/URL], [URL="http://www.alsa-project.org/main/index.php/Matrix%3aModule-dummy"]2[/URL]
- It could crash on Windows Server while loading, if a sound (dummy) driver or DirectX is missing. [U]Report this with the crash dump please, if you got one.[/U]
- For dedicated servers you need to install the Filesystem Exporter Plugin to access local and mounted sound files.

[B]Todo:[/B]
The todos are listed in the [URL="https://github.com/Grocel/GMod_Modules/labels/todo"]GitHub issues[/URL].

It is my first C++ GLua module I made from scratch and it is also my first project that runs on Linux too. So if you have problems using the module please let me know. I would like suggestions and feature requests too.

[thegrb93]

Does playing sounds only work if the client has the module?

[Grocel]

[QUOTE=thegrb93;48027210]Does playing sounds only work if the client has the module?[/QUOTE]
If the client doesn't have it, it would have to use [img]http://wiki.garrysmod.com/favicon.ico[/img] [url=http://wiki.garrysmod.com/page/sound/PlayURL]sound.PlayURL[/url] and stuff to play sounds. However the GMod stuff doesn't have the advanced/changed functionalities of this module.

[A Fghtr Pilot]

You are a great example of why German engineering is the best in the world.

[Grocel]

I just got the Valve Filesystem to work on dedicated server, so you can use mounted stuff.
Jcw87's Lua Debugger code put me in the right direction. However you would need to install a server plugin.

[Lebofly]

[QUOTE=Grocel;48291239]I just got the Valve Filesystem to work on dedicated server, so you can use mounted stuff.
Jcw87's Lua Debugger code put me in the right direction. However you would need to install a server plugin.[/QUOTE]

Do we need gm_bass3 for the visualiser to work? Installing gm_bass3 looks tedious (Linux server)

[Grocel]

Yes, on the server for the serverside and on the client for the clientside. It works like any other binary modules in GMod. However for the clientside you can still use GMod's functions too.

[Grocel]

I just released a small update, which makes IBASS3Channel:GetTag() a bit more useful. I also binded the EAX effects as planned, but I couldn't get them to work for me yet. It seems that these functions aren't recognizing my sound driver or something.

[Grocel]

I have got a new update done:
[QUOTE]
- Changed IBASS3Channel:GetLevel() to use BASS_ChannelGetLevelEx().
- Added the optional float TimeFrame, bool RMS, bool AsDecibel arguments
to IBASS3Channel:GetLevel().
- Added the optional bool AsDecibel argument to IBASS3Channel:FFT().
[/QUOTE]

It makes FFT() and GetLevel() a bit more useful. They include support for decibel returns of now.
If the AsDecibel argument is set to true it, the value will be converted as written below before it is returned.

output = 20 * log10(input)
if output < -1000 then output = -1000 end

[Grocel]

Since 3D sound is pretty quiet in BASS I decided to add a new function (IBASS3Channel:SetVolumeBoost()) to be able to boost the volume beyond 100%. It uses BASS_ChannelSetDSP() and a callback that multiplies every sample by the set factor. It works great, you can easily increase the volume by 1000% and still have no noticeable artifacts.

DSP functions affect the FFT output of BASS, so I compensated the boost out before exposing it to Lua.

[uRandomAlex]

[QUOTE=Grocel;51104576]Since 3D sound is pretty quiet in BASS I decided to add a new function (IBASS3Channel:SetVolumeBoost()) to be able to boost the volume beyond 100%. It uses BASS_ChannelSetDSP() and a callback that multiplies every sample by the set factor. It works great, you can easily increase the volume by 1000% and still have no noticeable artifacts.

DSP functions affects the FFT output of BASS, so I compensated the boost out before exposing it to Lua.[/QUOTE]
Does it work on clients without this module?

[Jvs]

[QUOTE=Grocel;51104576]Since 3D sound is pretty quiet in BASS I decided to add a new function (IBASS3Channel:SetVolumeBoost()) to be able to boost the volume beyond 100%. It uses BASS_ChannelSetDSP() and a callback that multiplies every sample by the set factor. It works great, you can easily increase the volume by 1000% and still have no noticeable artifacts.

DSP functions affects the FFT output of BASS, so I compensated the boost out before exposing it to Lua.[/QUOTE]

Totally forgot DSP was a thing for bass, I wonder how hard it would be for Willox or the likes to bridge source's DSP to bass'.

[Nockich]

[QUOTE=uRandomAlex;51106897]Does it work on clients without this module?[/QUOTE]

No, this module isn't shipped with GMod by default therefor clients must install it separately.

[uRandomAlex]

[QUOTE=Sudoxe;51108918]No, this module isn't shipped with GMod by default therefor clients must install it separately.[/QUOTE]
Sound can be modified by server and sent to clients. That's why I'm asking.

[c👌de_g🎷]

[QUOTE=uRandomAlex;51126896]Sound can be modified by server and sent to clients. That's why I'm asking.[/QUOTE]

No they can't

[Grocel]

There is an BASS.dll update (2.4.13) that able to amplify the volume to values greater than 1. This is especially usefull to fix the 3D sounds playback being so quiet.
Shotly after the BASS.dll update, I updated Gm_bass3 to also support this feature. You can use this feature when you manuelly update BASS in your GMod game by dropping the new version in.
After the next GMod update it will work out if the box, if the developer updates this file as requested here: Update Bass.dll to version 2.4.13 · Issue #1071 · Facepunch/garr..

[Grocel]

As BASS 2.4.13 is confirmed to be in the game and working as intended after the next update, I will declare IBASS3Channel:SetVolumeBoost() as deprecated as it is a dirty workaround for something that will work natively then.
I will add a deprecation message to that function when the update goes live and remove it about a month later.
I doubt that this module is used for anything serious, but just removing potential used function without warning is bad practice, isn't it?

[c👌de_g🎷]

I would recommend making it throw a non-halting error when used saying to use the native BASS method, and you can eventually remove the function when you feel developers have had ample time to adjust.

[Grocel]

OK with the latest update I marked the boost function as deprecated. They still work, but they will print a deprecation warning to the console. I will remove these function in around two months.
I plan to experiment a bit with the BASS_ChannelSetFX function and bind it to Lua soon. This would allow adding real time sound effects such as echos. It would also allow you to implement equalizers and other frequency depended filters.

[coolmax10]

I don't have a bin folder in steamapps/GarrysMod/garrysmod/lua
also can I have a download link for the c++ 11 runtime library
Windows 10

[Grocel]

OK, guys I finally got my long planned FX support done. In the latest update you can now apply all FX properties to a bass channel BASS supports.
If you want to play around with this I included an example addon in the GIT repository. It brings several usage examples/tests while the FX Test (seen below) is probably the most complex one.

https://files.facepunch.com/forum/upload/110792/f3ebfe32-7d5a-4263-8bcd-8c43846b50b0/gui_bassfxtest.png

I still have to write the documentation for the new objects and methods that this update brings. I will do that when I find some time for that. For now you can orient yourself on the BASS FX Docs. To create an FX object you use the IBASSChannel:AddFx(BASS3.ENUM.FX_*) methods, these work analog to their counter parts in the BASS library.