siudesu/soloudmodule

Solar2D Lua module to use with SoLoud plugin.

SoLoud Module

This Solar2D Lua module aims to be a drop-in replacement for the audio API using the SoLoud plugin.

Features

• Uses same API syntax as Solar2D's audio library
• Can play audio files that have been bundled using Binary Archive

Limitations

• Currently, SoLoud plugin is not available for Linux or Switch.
• stopWithDelay() is not implemented. The same effect can be accomplished outside this module with a timer and AUDIO.stop()
• fadeOut() is not implemented. The same effect can be accomplished outside this module with AUDIO.fade() and a timer to perform AUDIO.stop().

Requirements

• SoLoud plugin by Steven Johnson, must be added in build.settings.

build.settings (Plugins section)

	plugins =
	{
		["plugin.soloud"] = {publisherId = "com.xibalbastudios"},
	}

Usage

Load module and play audio sound:

-- You may replace the original audio library reference with this module without making additional changes to your project:

audio = require( "m_soloud_audio" )

local sfx1 = audio.loadSound( "soundFile.mp3" )
	audio.play( sfx1 )


-- or, load the module with any variable name without replacing the original audio library:

local AUDIO = require( "m_soloud_audio" )

local sfx1 = AUDIO.loadSound( "soundFile.mp3" )
	AUDIO.play( sfx1 )

Loading audio from archive:

-- Assumes a binary archive has been loaded with audio files used below.

-- Load SoLoud Module
local AUDIO = require( "m_soloud_audio" )

-- Fetch audio data from archive and insert it into a table (it's passed by reference)
local BGM_Data = { bin.fetch( "audio/BGM 01.mp3" )}
local SFX_Data = { bin.fetch( "audio/SFX/Ding.ogg" )}

-- Create audio stream object
local BGM1 = AUDIO.loadStreamFromArchive( "audio/BGM 01.mp3", BGM_Data )

-- Create audio sound object using the same filename and path as reference
local SFX1 = AUDIO.loadSoundFromArchive( "audio/SFX/Ding.ogg", SFX_Data )

-- Play BGM on channel 1
AUDIO.play( BGM1, { channel=1 })

-- Play SFX on any available channel
AUDIO.play( SFX1 )

Function List - same as Solar2D audio API:

MODULE.dispose( audioHandle )
MODULE.fade( { channel=num, time=num, volume=num } )
MODULE.findFreeChannel( startChannel )
MODULE.getDuration( audioHandle )
MODULE.getMaxVolume( { channel=num } )
MODULE.getMinVolume( { channel=num } )
MODULE.getVolume( { channel=num } )
MODULE.isChannelActive( channel )
MODULE.isChannelPaused( channel )
MODULE.isChannelPlaying( channel )
MODULE.loadSound( audioFileName )
MODULE.loadStream( audioFileName )
MODULE.pause( channel )
MODULE.play( audioHandle, { channel=num, loops=num, duration=num, fadein=num, onComplete=function, pitch=num } )
MODULE.reserveChannels( channels )
MODULE.resume( channel )
MODULE.rewind( audioHandle or { channel=num } )
MODULE.seek( time, audioHandle or { channel=num } )
MODULE.setMaxVolume( volume, { channel=num } )
MODULE.setMinVolume( volume, { channel=num } )
MODULE.setVolume( volume, { channel=num } )
MODULE.stop( channel )

Extra Audio Functions:

MODULE.setPitch( channel, pitchValue )
MODULE.setSpeed( channel, speedValue )

Binary Archive Functions

MODULE.loadSoundFromArchive( filename, data )
MODULE.loadStreamFromArchive( filename, data )

Properties (Read Only):

MODULE.freeChannels
MODULE.totalChannels
MODULE.unreservedFreeChannels
MODULE.unreservedUsedChannels
MODULE.usedChannels

---

License

Distributed under the MIT License. See LICENSE for more information.

soloudmodule's Issues

Typo error in AUDIO.dispose.

filename_ should be fileName_.

function M.dispose(fileName_)
-- Solar2D API: audio.dispose( audioHandle )
	
-- Note: Destroying the audio will also stop the audio.
-- !Unlike the audio API, it is possible to destroy (without errors) an audio while it's already playing.
	
	-- Destroy audio if it exists.
	if cache[fileName_] then cache[fileName_].wavObj:destroy() end
	
	-- All channels that were playing the audio will be clear.
	-- clearAllChannels(filename_)
        clearAllChannels(fileName_)
	
	-- Clear cache.
	cache[fileName_] = nil
end

`AUDIO.findFreeChannel` should start with 1 in Lua when `startChannel_` is nil.

findFreeChannel should start with 1 in Lua when startChannel_ is nil.

function M.findFreeChannel(startChannel_)
	-- Solar2D API: audio.findFreeChannel( [ startChannel ] )
	-- Search will increase upwards from this channel. 0 or no parameter begins searching at the lowest possible value.
	-- The search does not include reserved channels.

	-- Returns 0 if no available channel found, else it returns next available channel.
	-- return getNextAvailableChannel(startChannel_ or 0) or 0
	return getNextAvailableChannel(startChannel_ or 1) or 0
end

Missing solar2d audio api `audio.getSourceFromChannel`.

Hi!
I use this code to control sound speed:

local speed = 0.5
local source = audio.getSourceFromChannel(channel)
al.Source(source, al.PITCH, speed)

Is there something similar api in plugin.soloud?

AUDIO.play should return channel number, not a boolean.

According to the solar2d api document , audio.play should return current used channel number.

M.stop(channel) can not stop sound playing.

After #4 fixed, M.stop has no effect.

The sound played by the solar2d audio and this module for the same file sounds different in volume.

Hi, I got a weird bug when playing sound with this module compare to the solar2d audio api.
Here is the test example:
test_soloud_audio.zip
I tested it on MacOS-simulator-3690.

It seems that I can not use AUDIO.stop(channel) when this channel has not been used.

if I call audio.stop(channel) on a channel that has not been used, it will call an eror:
m_soloud_audio.lua:718: attempt to index field '?' (a nil value)