alemauri.eu/src/alsadoc.md

Unofficial ALSA API documentation

ALSA has to be the worst documented API in the whole FOSS world, so since I had to go trough the pain of reverse-engineering other programs I thought to save you form the same pain. So I present to you the most half-hassed description of the ALSA API on the interweb.

Functions

Interfaces

TODO

Hints

Hints are names, descriptions and other information about sound cards, interfaces and others. To get access to those hints there is a family of functions.

snd_device_name_hint

Get hints from a specified card of specified interface

int snd_device_name_hint (int card, const char *iface, void ***hints);

ARGS:

• (int)card: specifies the card index number, -1 means all cards
• (char *)iface: interface identification (like "pcm", "rawmidi", "timer", "seq")

RESULT:

• (void ***)hints: hints will receive a NULL-terminated array of device name hints, which can be passed to snd_device_name_get_hint() to extract usable values. When no longer needed, hints should be passed to snd_device_name_free_hint() to release resources.

RETURN: (int) 0 on success or negative error code

snd_device_name_get_hint

Extract selected hint form hints array

char* snd_device_name_get_hint (const void *hint, const char *id);

ARGS:

• (const void *)hint: a pointer to a hint which can be gotten by referencing hints[i] from snd_device_name_hint(), where i is the card index
• (const char *)id: hint value to extract, valid IDs are
  • NAME: name of device
  • DESC: description of device
  • IOID: input / output identification ("Input" or "Output"), NULL means both

RESULT: RETURN: (char *) gives a pointer to a string containing the requested hint or NULL on error, the result should be freed when done.

snd_device_name_free_hint

Free hints array

int snd_device_name_free_hint (void **hints);

ARGS:

• (void **)hints: hints array gotten from snd_device_name_hint

RETURN: (int) 0 on success or negative code on error

Example

Get hints from all pcms of all cards and print them out

#define _POSIX_C_SOURCE 200809L
#include <stdio.h>
#include <stdlib.h>

#include <alsa/asoundlib.h>

int main (int argc, char *argv[])
{
	void **hints, **n;
	char *name, *descr, *descr1, *io;

	if (snd_device_name_hint(-1, "pcm", &hints) < 0)
		return -1;
	n = hints;
	while (*n != NULL) {
		name = snd_device_name_get_hint(*n, "NAME");
		descr = snd_device_name_get_hint(*n, "DESC");
		io = snd_device_name_get_hint(*n, "IOID");
		printf("%s\n", name);
		if ((descr1 = descr) != NULL) {
			printf("    ");
			while (*descr1) {
				if (*descr1 == '\n')
					printf("\n    ");
				else
					putchar(*descr1);
				descr1++;
			}
			putchar('\n');
		}
	      	if (name != NULL)
	      		free(name);
		if (descr != NULL)
			free(descr);
		if (io != NULL)
			free(io);
		n++;
	}
	snd_device_name_free_hint(hints);
	return 0;
}