ffaudio

ffaudio is a fast cross-platform interface for Audio Input/Output for C and C++.

It provides advanced features for complex apps like phiola audio player/recorder, or it can be used by tiny programs like wav player example.

Contents:

• Features
• How to use
  • List all available playback devices
  • Record data from audio device
• How to build
  • Makefile helper
  • Build information for each audio API
• How to test

Features

• List available playback/capture devices
• Play audio
• Capture audio
• Blocking or non-blocking behaviour for write/drain/read functions
• The most simple API as it can be

Supports:

• AAudio (Android>=26)
  • formats: int16/float
  • mode: shared/exclusive
  • perf mode: power-save/low-latency
  • use "High Priority Callback"
• ALSA (Linux):
  • "hw" and "plughw" modes
• CoreAudio (macOS)
• DirectSound (Windows)
• JACK (Linux)
• OSS (FreeBSD)
• PulseAudio (Linux)
• WASAPI (Windows):
  • shared and exclusive modes
  • loopback mode (record what you hear)

Note: JACK playback is not implemented.

How to use

Write your cross-platform code using ffaudio_interface interface.

List all available playback devices

	#include <ffaudio/audio.h>

	// get API
	const ffaudio_interface *audio = ffaudio_default_interface();

	// initialize audio subsystem
	ffaudio_init_conf initconf = {};
	int r = audio->init(&initconf);
	if (r < 0)
		exit(1);

	// enumerate devices one by one
	ffaudio_dev *d = audio->dev_alloc(FFAUDIO_DEV_PLAYBACK);
	for (;;) {
		int r = audio->dev_next(d);
		if (r > 0) {
			break;
		} else if (r < 0) {
			printf("error: %s\n", audio->dev_error(d));
			break;
		}

		printf("device: name: '%s'\n", audio->dev_info(d, FFAUDIO_DEV_NAME));
	}
	audio->dev_free(d);

	audio->uninit();

Record data from audio device

	#include <ffaudio/audio.h>

	// get API
	const ffaudio_interface *audio = ffaudio_default_interface();

	// initialize audio subsystem
	ffaudio_init_conf initconf = {};
	int r = audio->init(&initconf);
	if (r < 0)
		exit(1);

	// create audio buffer
	ffaudio_buf *buf = audio->alloc();

	// open audio buffer for recording
	ffaudio_conf bufconf = {};
	bufconf.format = FFAUDIO_F_INT16;
	bufconf.sample_rate = 44100;
	bufconf.channels = 2;
	r = audio->open(buf, &bufconf, FFAUDIO_CAPTURE);
	if (r == FFAUDIO_EFORMAT)
		r = audio->open(buf, &bufconf, FFAUDIO_CAPTURE); // open with the supported format
	if (r < 0)
		exit(1);

	// read data from audio buffer and write it to stderr
	for (;;) {
		const void *data;
		r = audio->read(buf, &data);
		if (r < 0)
			exit(1);

		write(2, data.ptr, data.len);
	}

	audio->free(buf);
	audio->uninit();

In order for ffaudio_default_interface() function to work you should define FFAUDIO_INTERFACE_DEFAULT_PTR with the API you want to use, either in code:

#define FFAUDIO_INTERFACE_DEFAULT_PTR  &ffalsa
#include <ffaudio/audio.h>

or in Makefile:

CFLAGS += -DFFAUDIO_INTERFACE_DEFAULT_PTR="&ffalsa"

But instead of calling ffaudio_default_interface() you can just use an API directly, e.g. ffalsa.

How to build

Include the necessary ffaudio C files into your project's build script, e.g.:

	./ffaudio-alsa.o: $(FFAUDIO_DIR)/ffaudio/alsa.c $(FFAUDIO_DIR)/ffaudio/audio.h
		gcc -c $(CFLAGS) $< -o $@

Use the neceessary linker flags for the audio API, described below.

Build information for each audio API

Configure your building script to compile particular C file and use appropriate link flags.

API	Package Dependency	Compile	Linker Flags
AAudio	-	ffaudio/aaudio.c	-laaudio
ALSA	libalsa-devel	ffaudio/alsa.c	-lasound
PulseAudio	libpulse-devel	ffaudio/pulse.c	-lpulse
JACK	jack-audio-connection-kit-devel	ffaudio/jack.c	-ljack
WASAPI	-	ffaudio/wasapi.c	-lole32
DirectSound	-	ffaudio/dsound.c	-ldsound -ldxguid
CoreAudio	-	ffaudio/coreaudio.c	-framework CoreFoundation -framework CoreAudio
OSS	-	ffaudio/oss.c	-lm

How to test

git clone https://github.com/stsaz/ffbase
git clone https://github.com/stsaz/ffaudio
cd ffaudio/test

• Linux:

make -B FFAUDIO_API=alsa
./ffaudio-alsa list
./ffaudio-alsa record 2>file.raw
./ffaudio-alsa play <file.raw

make -B FFAUDIO_API=pulse
./ffaudio-pulse list
./ffaudio-pulse record 2>file.raw
./ffaudio-pulse play <file.raw

make -B FFAUDIO_API=jack
./ffaudio-jack list
./ffaudio-jack record 2>file.raw
# [not implemented] ./ffaudio-jack play <file.raw

• Android:

Install Android SDK & NDK; then cross-build for Android:

make FFAUDIO_API=aaudio \
	SYS=android \
	ROOT_DIR=../.. \
	SDK_DIR=/home/USER/Android/Sdk \
	NDK_VER=YOUR_NDK_VERSION

Run the executable on Android:

./ffaudio-aaudio record 2>file.raw
./ffaudio-aaudio play <file.raw

• Windows:

make -B FFAUDIO_API=wasapi
.\ffaudio-wasapi.exe list
.\ffaudio-wasapi.exe record 2>file.raw
.\ffaudio-wasapi.exe play <file.raw

make -B FFAUDIO_API=dsound
.\ffaudio-dsound.exe list
.\ffaudio-dsound.exe record 2>file.raw
.\ffaudio-dsound.exe play <file.raw

• macOS:

make FFAUDIO_API=coreaudio
./ffaudio-coreaudio list
./ffaudio-coreaudio record 2>file.raw
./ffaudio-coreaudio play <file.raw

• FreeBSD:

make FFAUDIO_API=oss
./ffaudio-oss list
./ffaudio-oss record 2>file.raw
./ffaudio-oss play <file.raw

There are more additional arguments that you can pass to these executable files.

License

ffaudio is in the public-domain.