Public C API for the BeepingCore library. More...

#include "stdint.h"

Enumerations
enum	BEEPING_MODE { BEEPING_MODE_AUDIBLE = 2 , BEEPING_MODE_INAUDIBLE = 3 , BEEPING_MODE_ALL = 5 }
	Encoding / decoding mode selector. More...

Functions
Lifecycle
BEEPING_DLLEXPORT void *	BEEPING_Create ()
	Create a new BeepingCore instance.
BEEPING_DLLEXPORT void	BEEPING_Destroy (void *beepingObject)
	Destroy a BeepingCore instance.
Versioning
BEEPING_DLLEXPORT const char *	BEEPING_GetVersion ()
	Return the library version string.
BEEPING_DLLEXPORT int32_t	BEEPING_GetVersionInfo (char *versioninfo)
	Copy the library version string into a caller-provided buffer.
Configuration
BEEPING_DLLEXPORT int32_t	BEEPING_Configure (int mode, float samplingRate, int32_t bufferSize, void *beepingObject)
	Configure the library for a given mode and sample rate.
BEEPING_DLLEXPORT int32_t	BEEPING_SetAudioSignature (int32_t samplesSize, const float samplesBuffer, void beepingObject)
	Install a custom audio signature to mix with encoded output.
Encoding
BEEPING_DLLEXPORT int32_t	BEEPING_EncodeDataToAudioBuffer (const char stringToEncode, int32_t size, int32_t type, const char melodyString, int32_t melodySize, void *beepingObject)
	Encode a string payload into an internal audio buffer.
BEEPING_DLLEXPORT int32_t	BEEPING_GetEncodedAudioBuffer (float audioBuffer, void beepingObject)
	Read a chunk of encoded audio into the caller's buffer.
BEEPING_DLLEXPORT int32_t	BEEPING_ResetEncodedAudioBuffer (void *beepingObject)
	Reset the read index, allowing the encoded buffer to be re-read.
Decoding
BEEPING_DLLEXPORT int32_t	BEEPING_DecodeAudioBuffer (float audioBuffer, int size, void beepingObject)
	Feed an audio buffer to the decoder.
BEEPING_DLLEXPORT int32_t	BEEPING_GetDecodedData (char stringDecoded, void beepingObject)
	Retrieve the last decoded string.
Reception quality metrics
BEEPING_DLLEXPORT float	BEEPING_GetConfidence (void *beepingObject)
	Combined reception-quality score (0.0 poor — 1.0 ideal).
BEEPING_DLLEXPORT float	BEEPING_GetConfidenceError (void *beepingObject)
	Confidence derived from Reed-Solomon corrections (0.0 — 1.0).
BEEPING_DLLEXPORT float	BEEPING_GetConfidenceNoise (void *beepingObject)
	Confidence derived from signal-to-noise ratio (0.0 — 1.0).
BEEPING_DLLEXPORT float	BEEPING_GetReceivedBeepsVolume (void *beepingObject)
	Average received beep volume in dB for the last transmission.
BEEPING_DLLEXPORT int32_t	BEEPING_GetDecodedMode (void *beepingObject)
	Mode that was decoded when BEEPING_MODE_ALL is active.
Decoding frequency range
BEEPING_DLLEXPORT float	BEEPING_GetDecodingBeginFreq (void *beepingObject)
	Lower bound of the decoding frequency range (Hz).
BEEPING_DLLEXPORT float	BEEPING_GetDecodingEndFreq (void *beepingObject)
	Upper bound of the decoding frequency range (Hz).

Detailed Description

Public C API for the BeepingCore library.

BeepingCore encodes and decodes arbitrary data over sound using audible or inaudible multi-tone FSK. This header defines the complete C-compatible API that SDK wrappers (Flutter, Android, iOS, Web, etc.) call into.

Copyright: Copyright (C) Beeping, LLC. Apache-2.0.

Enumeration Type Documentation

◆ BEEPING_MODE

enum BEEPING_MODE

Encoding / decoding mode selector.

Selects the frequency band used for multi-tone FSK encoding. INAUDIBLE adapts its base frequency to fit under Nyquist at lower sample rates.

Enumerator
BEEPING_MODE_AUDIBLE	Audible tones in the 3.3-10 kHz range.
BEEPING_MODE_INAUDIBLE	Inaudible tones (17.8-21 kHz at 44.1k+, adaptive at lower rates).
BEEPING_MODE_ALL	Decode Audible + Inaudible simultaneously.

Function Documentation

◆ BEEPING_Configure()

BEEPING_DLLEXPORT int32_t BEEPING_Configure	(	int	mode,
		float	samplingRate,
		int32_t	bufferSize,
		void *	beepingObject )

Configure the library for a given mode and sample rate.

This must be called after BEEPING_Create() and before any encode/decode. Reconfiguring is allowed — it destroys the previous encoder/decoder and builds new ones.

Parameters

mode	One of BEEPING_MODE.
samplingRate	Sample rate in Hz (e.g. 44100, 48000, 96000).
bufferSize	Size of the audio buffers the caller will exchange.
beepingObject	Handle from BEEPING_Create().

Returns: 0 on success, negative on failure (e.g. unknown mode).

◆ BEEPING_Create()

BEEPING_DLLEXPORT void * BEEPING_Create ( )

Create a new BeepingCore instance.

The returned opaque handle must be passed to all other API functions and released with BEEPING_Destroy().

Returns: Opaque handle, or nullptr on allocation failure.

◆ BEEPING_DecodeAudioBuffer()

BEEPING_DLLEXPORT int32_t BEEPING_DecodeAudioBuffer	(	float *	audioBuffer,
		int	size,
		void *	beepingObject )

Feed an audio buffer to the decoder.

Parameters

audioBuffer	Float PCM samples to decode.
size	Number of samples in audioBuffer.
beepingObject	Handle from BEEPING_Create().

Returns: -1 if no data found yet, -2 if start token detected, -3 if a complete word has been decoded, or a positive token index if a single token was decoded.

◆ BEEPING_Destroy()

BEEPING_DLLEXPORT void BEEPING_Destroy ( void * beepingObject )

Destroy a BeepingCore instance.

Releases all resources associated with the instance.

Parameters

beepingObject Handle from BEEPING_Create().

◆ BEEPING_EncodeDataToAudioBuffer()

BEEPING_DLLEXPORT int32_t BEEPING_EncodeDataToAudioBuffer	(	const char *	stringToEncode,
		int32_t	size,
		int32_t	type,
		const char *	melodyString,
		int32_t	melodySize,
		void *	beepingObject )

Encode a string payload into an internal audio buffer.

The resulting audio must be drained via BEEPING_GetEncodedAudioBuffer().

Parameters

stringToEncode	Payload characters to encode.
size	Number of characters to encode.
type	0 = pure tones, 1 = tones + R2D2 sounds, 2 = melody mode.
melodyString	Melody characters (only used when type == 2).
melodySize	Length of the melody (0 for type 0 or 1).
beepingObject	Handle from BEEPING_Create().

Returns: Total number of audio samples generated.

◆ BEEPING_GetDecodedData()

BEEPING_DLLEXPORT int32_t BEEPING_GetDecodedData	(	char *	stringDecoded,
		void *	beepingObject )

Retrieve the last decoded string.

Parameters

[out]	stringDecoded	Buffer for the decoded characters (caller provides — recommended size 30).
	beepingObject	Handle from BEEPING_Create().

Returns: 0 if no data available, positive with length on valid data, negative with length magnitude if the data failed integrity checks.

◆ BEEPING_GetDecodedMode()

BEEPING_DLLEXPORT int32_t BEEPING_GetDecodedMode ( void * beepingObject )

Mode that was decoded when BEEPING_MODE_ALL is active.

Returns: 0 = AUDIBLE, 1 = INAUDIBLE.

◆ BEEPING_GetEncodedAudioBuffer()

BEEPING_DLLEXPORT int32_t BEEPING_GetEncodedAudioBuffer	(	float *	audioBuffer,
		void *	beepingObject )

Read a chunk of encoded audio into the caller's buffer.

Call repeatedly until a return value less than bufferSize is returned.

Parameters

[out]	audioBuffer	Float array of bufferSize samples (as passed to BEEPING_Configure()).
	beepingObject	Handle from BEEPING_Create().

Returns: Number of samples written. Zero or less than bufferSize means the end of the encoded buffer has been reached.

◆ BEEPING_GetVersion()

BEEPING_DLLEXPORT const char * BEEPING_GetVersion ( )

Return the library version string.

Returns: Static null-terminated version string (do not free).

◆ BEEPING_GetVersionInfo()

BEEPING_DLLEXPORT int32_t BEEPING_GetVersionInfo ( char * versioninfo )

Copy the library version string into a caller-provided buffer.

Parameters

[out] versioninfo Buffer of at least 100 bytes.

Returns: Number of bytes written (excluding terminator).

◆ BEEPING_ResetEncodedAudioBuffer()

BEEPING_DLLEXPORT int32_t BEEPING_ResetEncodedAudioBuffer ( void * beepingObject )

Reset the read index, allowing the encoded buffer to be re-read.

Parameters

beepingObject Handle from BEEPING_Create().

Returns: 0 on success, negative on failure.

◆ BEEPING_SetAudioSignature()

BEEPING_DLLEXPORT int32_t BEEPING_SetAudioSignature	(	int32_t	samplesSize,
		const float *	samplesBuffer,
		void *	beepingObject )

Install a custom audio signature to mix with encoded output.

The signature is mixed on top of the tones during playback, useful to add a branded sound.

Parameters

samplesSize	Number of samples in samplesBuffer. Pass 0 and nullptr to clear a previously-set signature.
samplesBuffer	Float PCM samples (44.1 kHz, mono). Maximum 2 s (44100 * 2 samples).
beepingObject	Handle from BEEPING_Create().

Returns: 0 on success, negative on failure.

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ BEEPING_MODE

Function Documentation

◆ BEEPING_Configure()

◆ BEEPING_Create()

◆ BEEPING_DecodeAudioBuffer()

◆ BEEPING_Destroy()

◆ BEEPING_EncodeDataToAudioBuffer()

◆ BEEPING_GetDecodedData()

◆ BEEPING_GetDecodedMode()

◆ BEEPING_GetEncodedAudioBuffer()

◆ BEEPING_GetVersion()

◆ BEEPING_GetVersionInfo()

◆ BEEPING_ResetEncodedAudioBuffer()

◆ BEEPING_SetAudioSignature()