TinyALSA is a small C shim over the ALSA kernel interface

The aims are a list of things the library refuses to do

TinyALSA is a small library to interface with ALSA in the Linux kernel, and the README states its aims before anything else, which is unusual and useful. The first aim is to provide a basic pcm and mixer API. The second is the one that shapes everything: if it's not absolutely needed, don't add it to the API. The third is to avoid supporting complex and unnecessary operations that could be dealt with at a higher level. The fourth is to provide comprehensive documentation. Read together, those are a specification of what this library is not, and for a project whose entire justification is being small, that is the correct emphasis. A user choosing TinyALSA is choosing to have fewer features in exchange for a much smaller dependency, and the aims are the contract that says which of the two you are getting. The library ships a PCM interface and a mixer interface, and nothing else.

Four build systems, because it ships on phones and boards

TinyALSA supports four build systems, and the list is a good clue to where this code runs. There is CMake, Make, Meson, and Soong for Android. The presence of Soong matters most, because Soong is the Android build system, and its presence alongside a METADATA file, an Android.bp file and an OWNERS file in the tree says that TinyALSA is used inside AOSP rather than only on desktops. That is also why the primary language is C and why the library is small enough to keep a footprint on a device. The Makefile is the simplest of the four to read, and it sets the install layout with PREFIX defaulting to /usr/local, headers under include/tinyalsa, libraries under lib, binaries under bin and man pages under share/man. The install target copies six headers individually, attributes.h, pcm.h, mixer.h, asoundlib.h, version.h and plugin.h, which tells you the public surface includes a compatibility header and a plugin header alongside the two real APIs.

Building and installing

With Make, the sequence is three commands:

make
sudo make install
sudo ldconfig

The ldconfig step is there because the library is shared and the loader needs to know about it. The library itself also has an install target, split into INCDIR, LIBDIR, BINDIR and MANDIR, with DESTDIR supported for packaging, and a version script under scripts/ that generates the version numbers, with TINYALSA_VERSION_MAJOR and TINYALSA_VERSION derived from it at build time. For Debian and Ubuntu there is a set of packages on launchpad, a personal package archive rather than a distribution repository, and the README gives the commands to add it:

sudo apt-add-repository ppa:taylorcholberton/tinyalsa
sudo apt-get update
sudo apt-get install tinyalsa
sudo apt-get install libtinyalsa-dev

The three packages split the project usefully. The tinyalsa package contains the command line tools, tinyplay, tinycap, tinymix and tinypcminfo, libtinyalsa contains the shared library, and libtinyalsa-dev contains the static library and the header files. Once installed, the man pages are available under those tool names and two library names, libtinyalsa-pcm and libtinyalsa-mixer, which is the documentation surface for the two APIs.

Testing needs a loopback device, not a sound card

The test section sets up a Bazel environment and then the one piece of hardware the tests need, which is not a sound card. The test program does pcm_* operations on loopback devices, so you have to insert loopback devices after your system boots up, and the commands are:

sudo modprobe snd-aloop
sudo chmod 777 /dev/snd/*

That modprobe loads the kernel module that provides ALSA loopback devices, and the chmod is needed because the test process writes to the device nodes. The test run itself is a Bazel target:

bazel test //:tinyalsa_tests --test_output=all

The default playback device is hw:2,0 and the default capture device is hw:2,1, and if your loopback devices are not those you can point the test at the right ones with three copt defines, TEST_LOOPBACK_CARD, TEST_LOOPBACK_PLAYBACK_DEVICE and TEST_LOOPBACK_CAPTURE_DEVICE. Coverage is generated with a second Bazel invocation producing an lcov report, which is then rendered to HTML with genhtml into a directory named tinyalsa_tests_coverage. So the test suite is self-contained and does not need physical audio hardware, only the kernel module, which is what makes it practical to run in CI.

Where the complexity was pushed, and where the API stops

Two things in the tree tell you where the difficulty went. The include/tinyalsa directory has plugin.h, and the examples/ directory has a plugins/ subdirectory, so the extension mechanism is a documented part of the design rather than an afterthought, and hardware specific behaviour is expected to be supplied that way. The asoundlib.h header is the other one, and it is a compatibility surface, which suggests some code written against ALSA's own headers can be built against TinyALSA with limited change. That is where the migration path lies for a project that already uses ALSA but cannot link libasound. The limit is the same one the aims describe. There is no complex mixing, no device routing, no the full feature set of the ALSA userspace library, and the answer to a question this library does not cover is to deal with it at a higher level, as the README puts it. For a phone or a device where the audio path is simple and the binary size is critical, that trade is the right one. For a desktop application with complicated audio routing, it is not, and the full library is the correct dependency.

Editorial conclusion

Adopt TinyALSA when you need to open a PCM or mixer device from a small binary, on a system where linking the full ALSA userspace library is impractical, and when you can work with a deliberately narrow API. Do not adopt it as a drop-in replacement for libasound, because the whole point of the design is to avoid the complex operations that a higher level library would handle. Verify first which build system your platform uses, since Android and embedded projects use Soong and Meson rather than the Makefile, that the loopback device your tests need exists, and that the plugin interface covers whatever hardware specific behaviour you depend on.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. tinyalsa/tinyalsa on GitHub