Notes for GBD Client PCM Plugin Writers - andy3471/GBD GitHub Wiki

PCM Plugins for Standalone Audio Players or Non-GNU/Linux OS'

The gbdclient.c program provides a template for PCM plugin writers. It is implemented as an ALSA external PCM filter plugin, but there is absolutely nothing that prevents the code flow from being ported to any other OS platform or audio application plugin framework.

Essentially, perform the GBD specific initialization in the following order:

  • Connect to the GBD server via gbd_connect() as shown in SND_PCM_PLUGIN_DEFINE_FUNC(gbdclient) and load the (remote) GBD Library by passing the GBD_LADSPA_LIB_INIT command.

  • Then follow the initialization process for the GDB server-side PCM plugin as shown in gbdclient_init().

  • At this point, the GBD server/library will be ready to receive the stream of audio signals from the audio player. See gbdclient_transfer(). NOTE: The GBD library requires special conversion of sample formats from standard PCM encodings to a special (ALSA-based) float sample format. This discussed in Section Sample formats for GBD below.

  • When done streaming, perform the GDB client cleanup as implemented in gbdclient_close().

GBD Client/Server Message Passing

Currently the following GBD commands and C struct for message passing is understood by the GBD framework:

#define GBD_ERROR    -1
#define GBD_SUCCESS   0
#define GBD_LADSPA_LIB_INIT      1
#define GBD_CLIENT_CHANNELS      2
#define GBD_AUDIO_SAMPLE_RATE    3
#define GBD_PCM_PLUGIN_INIT      4
#define GBD_BEAT_DETECTION_FUNC  5
#define GBD_PCM_PLUGIN_CLOSE     6

typedef struct __gbd_msg {
  int32_t cmd;
  int32_t data;
} gbd_msg_t;

It is important to note that strict types are declared in gbd_msg_t to avoid running into problems w.r.t message sizes exchanged between client and server. In particular, the GBD server binary is compiled for the official Raspbian OS (currently v9.4 a.k.a Stretch) which remains 32-bit even though the underlying SoC/CPU architecture for recent RPi models such as 3+ is ARMv8 64bit. So, for instance, in an economy GBD setup, the GBD client will quite likely be executing on a 64-bit host (PC/laptop). In such cases, assumptions about sizes of the integer members of the message structure can lead to unexpected problems.

Sample formats for GBD: PCM to (ALSA) Float

The supplied GBD client client is an ALSA external PCM filter plugin. The ALSA library's plugin mechanism converts the PCM signals from an audio application to ALSA float format before invoking the GBD client runtime function. See gbdclient.c:gbdclient_transfer().

So, if writing a PCM plugin for a standalone audio player or some other OS' sound system, perform conversions from PCM integer values to ALSA float values the following manner:

  • Assuming a signed N-bit PCM encoding for samples of a given channel in src[siglen]:

    float dst[siglen];
XXX_t src[siglen];
...
XXX_t peak_ampl = (1U << (N-1)) - 1;	
for (int i = 0; i < siglen; i++)
  dst[i] = (float)src[i]/peak_ampl;

    where:

    • XXX_t will be int32_t for 32-bit sample encodings, int16_t for 16-bit, etc.
    • N will be 32 (for 32-bit samples), 16 (for 16-bit samples), etc

  • At this point, dst[siglen] will contain a signal with samples in a "normalized float PCM" format that the GBD DSP library expects. Nevertheless, keep it in mind that GBD has mainly been tested with 16-bit PCM.