lua-fensteraudio

The most minimal cross-platform audio playback library - now in Lua!

Warning

WORK IN PROGRESS

Installation

From LuaRocks server:

luarocks install fensteraudio

From source:

git clone https://github.com/jonasgeiler/lua-fensteraudio.git
cd lua-fensteraudio
luarocks make

Simple Example

Here is a simple example that plays random noise:

-- noise.lua
local fensteraudio = require('fensteraudio')

local audiodevice = fensteraudio.open()
local volume = 0.01 -- BE CAREFUL! High volume can damage your ears or equipment.

local samples = {}
while true do
	local available = audiodevice:available()
	if available > 0 then
		for i = 1, available do
			samples[i] = math.random(-1, 1) * volume
		end

		audiodevice:write(samples, available)
	end
end

To run the example:

lua noise.lua

You should hear a bunch of random noise. If not, carefully turn up the system volume until you hear something. If you still don't hear anything, try carefully increasing the volume variable in the script.

Demos

Check out the ./demos folder for more elaborate example applications!
To run a demo use:

lua demos/<demo>.lua

Some of the demos are user-contributed. If you have a demo you'd like to share, feel free to create a pull request!

Type Definitions

Work in progress.

API Documentation

Work in progress.

Development

I am developing on Linux, so I will only be able to provide a guide for Linux.

Building

Building the library from the source code requires:

• GCC or similar (f.e. apt install build-essential)
• ALSA Development Files (f.e. apt install libasound2-dev)
• Lua (f.e. apt install lua5.4)
• Lua Development Files (f.e. apt install liblua5.4-dev)
• LuaRocks (f.e. apt install luarocks)

To build the library from the source code, use:

luarocks make

Tip

If you have multiple Lua versions installed on your system, you can specify the version to build for with the --lua-version LuaRocks flag. For example, to build for Lua 5.4, use:

luarocks --lua-version=5.4 make

Testing

Before you can run the test you should build the library first.

Afterward, to run the tests, use:

luarocks test

Tip

If you have multiple Lua versions installed on your system, you can specify the version to use for testing with the --lua-version LuaRocks flag. For example, to test with Lua 5.4, use:

luarocks --lua-version=5.4 test

Testing using Docker

If you don't want to install the dependencies above on your system, or want to test on all Lua versions simultaneously in a clean environment, you can use Docker with Docker Compose.

Just run the following command to build the Docker images for all Lua versions and run the tests on each:

docker compose up --build --force-recreate --abort-on-container-failure

Credits

Many thanks to Serge Zaitsev (@zserge) for creating the original fenster_audio library and making it available to the public. This Lua binding wouldn't have been possible without their work.

License

This project is licensed under the MIT License. Feel free to use it in your own proprietary or open-source projects. If you have any questions, please open an issue or discussion!