faun.h File Reference

The Faun programmer interface. More...

#include <stdint.h>
#include <stdio.h>

Go to the source code of this file.

Data Structures
struct	FaunSignal
	This struct is used for faun_pollSignals() & faun_waitSignal(). More...

Macros
#define	FAUN_VERSION_STR   "0.2.5"
	A printable string of the library version.
#define	FAUN_VERSION   0x000205
	Three packed bytes containing the major, minor, & fix version numbers.
#define	FAUN_PROGRAM_MAX   64
	The maximum number of bytes for the faun_program() length.
#define	FAUN_PAIR(a, b)
	Used with faun_playSource() to queue two buffers that will be played sequentially.
#define	FAUN_TRIO(a, b, c)
	Used with faun_playSource() to queue three buffers that will be played sequentially.
#define	FAUN_PID_SOURCE(pid)
	Get the source index from a playback identifier.

Enumerations
enum	FaunCommand {   FC_START , FC_STOP , FC_PAUSE , FC_RESUME ,   FC_FADE_OUT , FC_COUNT }
enum	FaunOpcode {   FO_END , FO_WAIT , FO_SOURCE , FO_QUEUE ,   FO_PLAY_BUF , FO_START_STREAM , FO_RESERVED0 , FO_SET_VOL ,   FO_SET_FADE , FO_SET_END , FO_LOOP_ON , FO_LOOP_OFF ,   FO_FADE_IN , FO_FADE_OUT , FO_VOL_LR , FO_PAN ,   FO_SIGNAL , FO_CAPTURE , FO_COUNT }
enum	FaunFormat {   FAUN_FMT_S16 = 1 , FAUN_FMT_F32 = 2 , FAUN_FMT_MONO = 0 , FAUN_FMT_STEREO = 8 ,   FAUN_FMT_22050 = 0x10 , FAUN_FMT_44100 = 0x20 }
enum	FaunPlayMode {   FAUN_PLAY_ONCE = 0x0001 , FAUN_PLAY_LOOP = 0x0002 , FAUN_PLAY_FADE_IN = 0x0010 , FAUN_PLAY_FADE_OUT = 0x0020 ,   FAUN_SIGNAL_DONE = 0x0040 , FAUN_SIGNAL_PROG = 0x0080 , FAUN_PLAY_FADE = FAUN_PLAY_FADE_IN | FAUN_PLAY_FADE_OUT }
enum	FaunParameter {   FAUN_VOLUME , FAUN_VOLUME_APPLY , FAUN_FADE_PERIOD , FAUN_END_TIME ,   FAUN_PARAM_COUNT }

Functions
const char *	faun_startup (int bufferLimit, int sourceLimit, int streamLimit, int progLimit, const char *appName)
	Called once at program startup.
void	faun_shutdown ()
	Called once when the program exits.
void	faun_suspend (int halt)
	Pause or resume mixing.
void	faun_setErrorStream (FILE *)
	Redirect error messages from stderr.
int	faun_pollSignals (FaunSignal *sigbuf, int count)
	Check for signals from sources and streams.
void	faun_waitSignal (FaunSignal *sigbuf)
	Block calling thread until a signal is emitted.
void	faun_control (int si, int count, int command)
	Send a single command to sources or streams.
void	faun_setParameter (int si, int count, uint8_t param, float value)
	Set source or stream parameter.
void	faun_pan (int si, float finalVolL, float finalVolR, float period)
	Change volume of stereo channels over a period of time.
void	faun_program (int ei, const uint8_t *bytecode, int len)
	Execute a Faun program.
float	faun_loadBuffer (int bi, const char *file, uint32_t offset, uint32_t size)
	Load a file into a PCM buffer.
float	faun_loadBufferF (int bi, FILE *file, uint32_t size)
	Load audio data from FILE into a PCM buffer.
float	faun_loadBufferPcm (int bi, int format, const void *samples, uint32_t frames)
	Load PCM audio data from memory into a buffer.
float	faun_loadBufferSfx (int bi, const void *sfxParam)
	Load audio data generated from SfxParams into a PCM buffer.
void	faun_freeBuffers (int bi, int count)
	Free the memory used by a contiguous group of buffers.
uint32_t	faun_playSource (int si, int bi, int mode)
	Begin playback of a buffer from a source.
uint32_t	faun_playSourceVol (int si, int bi, int mode, float volL, float volR)
	Begin playback of a buffer from a source and set channel volumes.
uint32_t	faun_playStream (int si, const char *file, uint32_t offset, uint32_t size, int mode)
	Open a file and optionally begin streaming.
void	faun_playStreamPart (int si, double start, double duration, int mode)
	Begin playing a segment from a stream.
uint32_t	faun_feedStream (int si, int(*func)(float *, int, void *), void *user)
	Begin streaming user generated samples via a callback function.
int	faun_isPlaying (uint32_t pid)
	Check if a source or stream is still playing.
int	faun_idleSource (int start, int end, int it)
	Find a source that is not playing.

Detailed Description

The Faun programmer interface.

Macro Definition Documentation

FAUN_PAIR

#define FAUN_PAIR	(		a,
			b )

Value:

(((b+1) << 10) | a)

Used with faun_playSource() to queue two buffers that will be played sequentially.

FAUN_PID_SOURCE

#define FAUN_PID_SOURCE

(

pid

)

Value:

(pid & 0xff)

Get the source index from a playback identifier.

Examples

feed.c.

FAUN_TRIO

#define FAUN_TRIO	(		a,
			b,
			c )

Value:

(((c+1) << 20) | ((b+1) << 10) | a)

Used with faun_playSource() to queue three buffers that will be played sequentially.

Enumeration Type Documentation

FaunCommand

enum FaunCommand

Enumerator
FC_START	Start playing from the beginning of the source buffer or stream.
FC_STOP	Halt playback and deactivate source.
FC_PAUSE	Halt playback but keep source active to resume later.
FC_RESUME	Continue playback from the point when FC_PAUSE was last used.
FC_FADE_OUT	Fade volume to zero from the current play position over the FAUN_FADE_PERIOD.

FaunParameter

enum FaunParameter

Enumerator
FAUN_VOLUME	This is the volume (or fade in target) used when playback begins. The value ranges from 0.0 to 1.0. The default value is 1.0.
FAUN_VOLUME_APPLY	This sets the volume parameter like FAUN_VOLUME and also immediately changes the current volume.
FAUN_FADE_PERIOD	Duration in seconds for fading in & out. The default value is 1.5 seconds.
FAUN_END_TIME	Used to end playback of a source or stream before the buffer or stream file ends. The value is the number of seconds from the start when the sound will be stopped.

FaunPlayMode

enum FaunPlayMode

Enumerator
FAUN_PLAY_ONCE	Used to initiate playback of a source or stream a single time.
FAUN_PLAY_LOOP	Used to initiate playback of a source or stream and repeat it forever.
FAUN_PLAY_FADE_IN	Increase gain from 0.0 gradually when playing begins. The target gain is set by FAUN_VOLUME and the fade period is set by FAUN_FADE_PERIOD.
FAUN_PLAY_FADE_OUT	Decreases gain to 0.0 gradually just before the source or stream ends. The fade period is set by FAUN_FADE_PERIOD.
FAUN_SIGNAL_DONE	Used to generate a FaunSignal when the source or stream is finished playing.
FAUN_SIGNAL_PROG	The FaunSignal::signal identifier of a signal generated by the FO_SIGNAL program opcode.
FAUN_PLAY_FADE	Used to set both FAUN_PLAY_FADE_IN & FAUN_PLAY_FADE_OUT.

Function Documentation

faun_control()

void faun_control	(	int	si,
		int	count,
		int	command )

Send a single command to sources or streams.

Parameters

si	Source or stream index.
count	Number of sources or streams to command.
command	FaunCommand enum.

faun_feedStream()

uint32_t faun_feedStream	(	int	si,
		int(*	func )(float *, int, void *),
		void *	user )

Begin streaming user generated samples via a callback function.

The callback is run in the Faun mixer thread. The user is responsible for protecting against concurrent thread access to data.

The function must entirely fill the buffer with the requested number of stereo frames and return 0, or return 1 to end the stream.

Parameters

si	Stream index.
func	Callback function to fill buffer.
user	Pointer passed as third callback argument.

Returns

Unique play identifier or zero if streaming could not start.

faun_freeBuffers()

void faun_freeBuffers	(	int	bi,
		int	count )

Free the memory used by a contiguous group of buffers.

Parameters

bi	First buffer index.
count	Number of buffers to free.

faun_idleSource()

int faun_idleSource	(	int	start,
		int	end,
		int	it )

Find a source that is not playing.

Parameters

start	Beginning index of range.
end	Ending index of range.
it	Position in range from which to begin checking.

Returns

Source index or -1 if all in range are being used.

faun_isPlaying()

int faun_isPlaying

(

uint32_t

pid

)

Check if a source or stream is still playing.

Parameters

pid	Playback identifier returned by faun_playSource(), faun_playSourceVol(), or faun_playStream().

Returns

Non-zero if source is playing.

faun_loadBuffer()

float faun_loadBuffer	(	int	bi,
		const char *	file,
		uint32_t	offset,
		uint32_t	size )

Load a file into a PCM buffer.

Parameters

bi	Buffer index.
file	Path to audio file.
offset	Byte offset to the start of data in the file.
size	Bytes to read from file. Pass zero to read to the file end.

Returns

Duration in seconds or zero upon failure.

See also

faun_loadBufferF(), faun_loadBufferPcm(), faun_loadBufferSfx()

faun_loadBufferF()

float faun_loadBufferF	(	int	bi,
		FILE *	fp,
		uint32_t	size )

Load audio data from FILE into a PCM buffer.

Parameters

bi	Buffer index.
fp	FILE pointer positioned at the start of audio data.
size	Bytes to read from file. Pass zero to read to the file end.

Returns

Duration in seconds or zero upon failure.

See also

faun_loadBuffer()

faun_loadBufferPcm()

float faun_loadBufferPcm	(	int	bi,
		int	format,
		const void *	samples,
		uint32_t	frames )

Load PCM audio data from memory into a buffer.

Parameters

bi	Buffer index.
format	FaunFormat mask of word size, channels, & sample rate.
samples	Pointer to PCM samples.
frames	Number of frames in samples.

Returns

Duration in seconds or zero upon failure.

See also

faun_loadBuffer()

faun_loadBufferSfx()

float faun_loadBufferSfx	(	int	bi,
		const void *	sfxParam )

Load audio data generated from SfxParams into a PCM buffer.

Parameters

bi	Buffer index.
sfxParam	SfxParams/WaveParams struct.

Returns

Duration in seconds or zero upon failure.

See also

faun_loadBuffer()

faun_pan()

void faun_pan	(	int	si,
		float	finalVolL,
		float	finalVolR,
		float	period )

Change volume of stereo channels over a period of time.

Parameters

si	Source or stream index.
finalVolL	Target volume for left channel.
finalVolR	Target volume for right channel.
period	Number of seconds for transition.

faun_playSource()

uint32_t faun_playSource	(	int	si,
		int	bi,
		int	mode )

Begin playback of a buffer from a source.

The volume is set to either the current FAUN_VOLUME parameter or 0.0 if mode includes FAUN_PLAY_FADE_IN. To change the volume after playing has started use faun_pan().

Parameters

si	Source index.
bi	Buffer indices. Use the FAUN_PAIR() & FAUN_TRIO() macros to queue two or three buffers.
mode	The FaunPlayMode (FAUN_PLAY_ONCE or FAUN_PLAY_LOOP).

Returns

Unique play identifier or zero if playback could not start.

See also

faun_playSourceVol()

faun_playSourceVol()

uint32_t faun_playSourceVol	(	int	si,
		int	bi,
		int	mode,
		float	volL,
		float	volR )

Begin playback of a buffer from a source and set channel volumes.

This is similar to faun_playSource(), but the volume arguments override the FAUN_VOLUME parameter setting.

Parameters

si	Source index.
bi	Buffer indices. Use the FAUN_PAIR() & FAUN_TRIO() macros to queue two or three buffers.
mode	The FaunPlayMode (FAUN_PLAY_ONCE or FAUN_PLAY_LOOP).
volL	Volume of left channel (0.0 to 1.0).
volR	Volume of right channel (0.0 to 1.0).

Returns

Unique play identifier or zero if playback could not start.

See also

faun_playSource()

faun_playStream()

uint32_t faun_playStream	(	int	si,
		const char *	file,
		uint32_t	offset,
		uint32_t	size,
		int	mode )

Open a file and optionally begin streaming.

Reading can be limited to a specific chunk of the file if the size argument is non-zero.

To begin playback the mode must include either FAUN_PLAY_ONCE or FAUN_PLAY_LOOP. If it does not, then a FC_START command or a call to faun_playStreamPart() must be used to initiate play.

Parameters

si	Stream index.
file	File path.
offset	Byte offset to start of stream data in file.
size	Byte size of stream data in file, or zero if the entire file is to be used.
mode	The FaunPlayMode (FAUN_PLAY_ONCE, FAUN_PLAY_LOOP, etc.).

Returns

Unique play identifier or zero if streaming could not start.

faun_playStreamPart()

void faun_playStreamPart	(	int	si,
		double	start,
		double	duration,
		int	mode )

Begin playing a segment from a stream.

The stream must have been previously initialized by faun_playStream().

Parameters

si	Stream index.
start	Playback start position (in seconds).
duration	Time to play (in seconds).
mode	FaunPlayMode (FAUN_PLAY_ONCE or FAUN_PLAY_LOOP).

faun_pollSignals()

int faun_pollSignals	(	FaunSignal *	sigbuf,
		int	count )

Check for signals from sources and streams.

Parameters

sigbuf	Pointer to memory for signals.
count	Number of signals sigbuf can hold.

Returns

Number of signals copied to sigbuf.

faun_program()

void faun_program	(	int	exec,
		const uint8_t *	bytecode,
		int	len )

Execute a Faun program.

This can be used to sequence the playback of multiple sources and streams.

Any currently running program on the execution unit will be halted and replaced.

Parameters

exec	Execution unit index.
bytecode	FuanOpcode instructions and data. The program must be terminated by FO_END.
len	Byte length of bytecode. The maximum len is FAUN_PROGRAM_MAX.

faun_setErrorStream()

void faun_setErrorStream

(

FILE *

fp

)

Redirect error messages from stderr.

Pass NULL to reset to stderr.

faun_setParameter()

void faun_setParameter	(	int	si,
		int	count,
		uint8_t	param,
		float	value )

Set source or stream parameter.

Parameters

si	Source or stream index.
count	Number of sources or streams to modify.
param	FaunParameter enum (FAUN_VOLUME, FAUN_FADE_PERIOD, FAUN_END_TIME).
value	Value assigned to param.

faun_shutdown()

void faun_shutdown

(

)

Called once when the program exits.

It is safe to call this even if faun_startup() was not called.

faun_startup()

const char * faun_startup	(	int	bufferLimit,
		int	sourceLimit,
		int	streamLimit,
		int	progLimit,
		const char *	appName )

Called once at program startup.

Stream identifier numbers start at the source limit. So if sourceLimit is 8 and streamLimit is 2, then the valid stream ids will be 8 & 9.

Parameters

bufferLimit	Maximum number of buffers (0-256).
sourceLimit	Maximum number of simultaneously playing sounds (0-32).
streamLimit	Maximum number of simultaneously playing streams (0-6).
progLimit	Maximum number of program execution units (0-16).
appName	Program identifier for networked audio systems.

Returns

Error string or NULL if successful.

faun_suspend()

void faun_suspend

(

int

halt

)

Pause or resume mixing.

Parameters

halt	Non-zero suspends and zero resumes.

faun_waitSignal()

void faun_waitSignal

(

FaunSignal *

sigbuf

)

Block calling thread until a signal is emitted.

Parameters

sigbuf

Memory for next signal.