LIBFFADO  2.4.6
Classes | Macros | Typedefs | Enumerations | Functions
ffado.h File Reference
#include <stdlib.h>

Go to the source code of this file.

Classes

struct  ffado_device_info
 
struct  ffado_options
 

Macros

#define FFADO_API_VERSION   9
 
#define FFADO_MAX_NAME_LEN   256
 
#define FFADO_STREAMING_MAX_URL_LENGTH   2048
 
#define FFADO_IGNORE_CAPTURE   (1<<0)
 
#define FFADO_IGNORE_PLAYBACK   (1<<1)
 
#define WEAK_ATTRIBUTE   __weak__
 
#define FFADO_MAX_SPECSTRING_LENGTH   256
 
#define FFADO_MAX_SPECSTRINGS   64
 

Typedefs

typedef struct ffado_handle * ffado_handle_t
 
typedef struct _ffado_device ffado_device_t
 
typedef unsigned int ffado_sample_t
 
typedef unsigned int ffado_nframes_t
 
typedef struct ffado_device_info ffado_device_info_t
 
typedef struct ffado_options ffado_options_t
 

Enumerations

enum  ffado_direction { FFADO_CAPTURE = 0 , FFADO_PLAYBACK = 1 }
 
enum  ffado_streaming_stream_type {
  ffado_stream_type_invalid = -1 , ffado_stream_type_unknown = 0 , ffado_stream_type_audio = 1 , ffado_stream_type_midi = 2 ,
  ffado_stream_type_control = 3
}
 
enum  ffado_streaming_audio_datatype { ffado_audio_datatype_error = -1 , ffado_audio_datatype_int24 = 0 , ffado_audio_datatype_float = 1 }
 
enum  ffado_wait_response { ffado_wait_shutdown = -3 , ffado_wait_error = -2 , ffado_wait_xrun = -1 , ffado_wait_ok = 0 }
 

Functions

const char * ffado_get_version ()
 
int ffado_get_api_version ()
 
ffado_device_tffado_streaming_init (ffado_device_info_t device_info, ffado_options_t options)
 
int ffado_streaming_set_period_size (ffado_device_t *dev, unsigned int period) FFADO_WEAK_EXPORT
 
int ffado_streaming_prepare (ffado_device_t *dev)
 
void ffado_streaming_finish (ffado_device_t *dev)
 
int ffado_streaming_get_nb_capture_streams (ffado_device_t *dev)
 
int ffado_streaming_get_nb_playback_streams (ffado_device_t *dev)
 
int ffado_streaming_get_capture_stream_name (ffado_device_t *dev, int number, char *buffer, size_t buffersize)
 
int ffado_streaming_get_playback_stream_name (ffado_device_t *dev, int number, char *buffer, size_t buffersize)
 
ffado_streaming_stream_type ffado_streaming_get_capture_stream_type (ffado_device_t *dev, int number)
 
ffado_streaming_stream_type ffado_streaming_get_playback_stream_type (ffado_device_t *dev, int number)
 
int ffado_streaming_set_capture_stream_buffer (ffado_device_t *dev, int number, char *buff)
 
int ffado_streaming_capture_stream_onoff (ffado_device_t *dev, int number, int on)
 
int ffado_streaming_set_playback_stream_buffer (ffado_device_t *dev, int number, char *buff)
 
int ffado_streaming_playback_stream_onoff (ffado_device_t *dev, int number, int on)
 
ffado_streaming_audio_datatype ffado_streaming_get_audio_datatype (ffado_device_t *dev)
 
int ffado_streaming_set_audio_datatype (ffado_device_t *dev, ffado_streaming_audio_datatype t)
 
int ffado_streaming_start (ffado_device_t *dev)
 
int ffado_streaming_stop (ffado_device_t *dev)
 
int ffado_streaming_reset (ffado_device_t *dev)
 
ffado_wait_response ffado_streaming_wait (ffado_device_t *dev)
 
int ffado_streaming_transfer_buffers (ffado_device_t *dev)
 
int ffado_streaming_transfer_playback_buffers (ffado_device_t *dev)
 
int ffado_streaming_transfer_capture_buffers (ffado_device_t *dev)
 

Macro Definition Documentation

◆ FFADO_API_VERSION

#define FFADO_API_VERSION   9

◆ FFADO_IGNORE_CAPTURE

#define FFADO_IGNORE_CAPTURE   (1<<0)

◆ FFADO_IGNORE_PLAYBACK

#define FFADO_IGNORE_PLAYBACK   (1<<1)

◆ FFADO_MAX_NAME_LEN

#define FFADO_MAX_NAME_LEN   256

◆ FFADO_MAX_SPECSTRING_LENGTH

#define FFADO_MAX_SPECSTRING_LENGTH   256

◆ FFADO_MAX_SPECSTRINGS

#define FFADO_MAX_SPECSTRINGS   64

◆ FFADO_STREAMING_MAX_URL_LENGTH

#define FFADO_STREAMING_MAX_URL_LENGTH   2048

◆ WEAK_ATTRIBUTE

#define WEAK_ATTRIBUTE   __weak__

Typedef Documentation

◆ ffado_device_info_t

This struct serves to define the devices that should be used by the library device_spec_strings is an array of pointers that should contain nb_device_spec_strings valid pointers to strings.

The spec strings should be null terminated and can be no longer than FFADO_MAX_SPECSTRINGS.

nb_device_spec_strings < FFADO_MAX_SPECSTRING_LENGTH nb_device_spec_strings >= 0

If nb_device_spec_strings == 0, all busses are scanned for attached devices, and all found devices that are supported are combined into one large pseudo-device. The device order is defined by the GUID of the device. Devices with lower GUID's will be the first ones.

If multiple device specifications are present, the device order is defined as follows:

  • device(s) that correspond to a spec string with a lower index will be added before devices from higher indexes.
  • if a spec string results in multiple devices, they are sorted by GUID unless the spec format dictates otherwise.

The actual meaning of the device specification should be one of the following:

  • Format 1: "hw:x[,y[,z]]" x = the FireWire bus to use ('port' in raw1394 terminology) (mandatory) y = the node id the device currently has (bus resets might change that, but FFADO will track these changes and keep using the device specified on startup) (optional) z = the stream direction to use. 0 => capture (record) channels only 1 => playback channels only other/unspecified => both playback and capture (optional)
  • Format 2: the device alias as defined in the ffado config file (UNIMPLEMENTED)

◆ ffado_device_t

typedef struct _ffado_device ffado_device_t

◆ ffado_handle_t

typedef struct ffado_handle* ffado_handle_t

◆ ffado_nframes_t

typedef unsigned int ffado_nframes_t

◆ ffado_options_t

Structure to pass the options to the ffado streaming code.

◆ ffado_sample_t

typedef unsigned int ffado_sample_t

The sample format used by the ffado streaming API

Enumeration Type Documentation

◆ ffado_direction

Enumerator
FFADO_CAPTURE 
FFADO_PLAYBACK 

◆ ffado_streaming_audio_datatype

Audio data types known to the API

Enumerator
ffado_audio_datatype_error 
ffado_audio_datatype_int24 
ffado_audio_datatype_float 

◆ ffado_streaming_stream_type

The types of streams supported by the API

A ffado_audio type stream is a stream that consists of successive samples. The format is a 24bit UINT in host byte order, aligned as the 24LSB's of the 32bit UINT of the read/write buffer. The wait operation looks at this type of streams only.

A ffado_midi type stream is a stream of midi bytes. The bytes are 8bit UINT, aligned as the first 8LSB's of the 32bit UINT of the read/write buffer.

A ffado_control type stream is a stream that provides control information. The format of this control information is undefined, and the stream should be ignored.

Enumerator
ffado_stream_type_invalid 
ffado_stream_type_unknown 
ffado_stream_type_audio 
ffado_stream_type_midi 
ffado_stream_type_control 

◆ ffado_wait_response

Wait responses

Enumerator
ffado_wait_shutdown 
ffado_wait_error 
ffado_wait_xrun 
ffado_wait_ok 

Function Documentation

◆ ffado_get_api_version()

int ffado_get_api_version ( )

◆ ffado_get_version()

const char* ffado_get_version ( )

◆ ffado_streaming_capture_stream_onoff()

int ffado_streaming_capture_stream_onoff ( ffado_device_t dev,
int  number,
int  on 
)

◆ ffado_streaming_finish()

void ffado_streaming_finish ( ffado_device_t dev)

Finishes the FFADO streaming. Cleans up all internal data structures and terminates connections.

Parameters
devthe ffado device to be closed.

◆ ffado_streaming_get_audio_datatype()

ffado_streaming_audio_datatype ffado_streaming_get_audio_datatype ( ffado_device_t dev)

◆ ffado_streaming_get_capture_stream_name()

int ffado_streaming_get_capture_stream_name ( ffado_device_t dev,
int  number,
char *  buffer,
size_t  buffersize 
)

Copies the capture channel name into the specified buffer

Parameters
devthe ffado device
numberthe stream number
bufferthe buffer to copy the name into. has to be allocated.
buffersizethe size of the buffer
Returns
the number of characters copied into the buffer

◆ ffado_streaming_get_capture_stream_type()

ffado_streaming_stream_type ffado_streaming_get_capture_stream_type ( ffado_device_t dev,
int  number 
)

Returns the type of a capture channel

Parameters
devthe ffado device
numberthe stream number
Returns
the channel type

◆ ffado_streaming_get_nb_capture_streams()

int ffado_streaming_get_nb_capture_streams ( ffado_device_t dev)

Returns the amount of capture channels available

Parameters
devthe ffado device
Returns
the number of capture streams present & active on the device. can be 0. returns -1 upon error.

◆ ffado_streaming_get_nb_playback_streams()

int ffado_streaming_get_nb_playback_streams ( ffado_device_t dev)

Returns the amount of playack channels available

Parameters
devthe ffado device
Returns
the number of playback streams present & active on the device. can be 0. returns -1 upon error.

◆ ffado_streaming_get_playback_stream_name()

int ffado_streaming_get_playback_stream_name ( ffado_device_t dev,
int  number,
char *  buffer,
size_t  buffersize 
)

Copies the playback channel name into the specified buffer

Parameters
devthe ffado device
numberthe stream number
bufferthe buffer to copy the name into. has to be allocated.
buffersizethe size of the buffer
Returns
the number of characters copied into the buffer

◆ ffado_streaming_get_playback_stream_type()

ffado_streaming_stream_type ffado_streaming_get_playback_stream_type ( ffado_device_t dev,
int  number 
)

Returns the type of a playback channel

Parameters
devthe ffado device
numberthe stream number
Returns
the channel type

◆ ffado_streaming_init()

ffado_device_t* ffado_streaming_init ( ffado_device_info_t  device_info,
ffado_options_t  options 
)

Initializes the streaming from/to a FFADO device. A FFADO device is a virtual device composed of several BeBoB or compatible devices, linked together in one sync domain.

This prepares all IEEE1394 related stuff and sets up all buffering. It elects a sync master if nescessary.

Parameters
device_infoprovides a way to specify the virtual device
optionsoptions regarding buffers, ieee1394 setup, ...
Returns
Opaque device handle if successful. If this is NULL, the init operation failed.

◆ ffado_streaming_playback_stream_onoff()

int ffado_streaming_playback_stream_onoff ( ffado_device_t dev,
int  number,
int  on 
)

◆ ffado_streaming_prepare()

int ffado_streaming_prepare ( ffado_device_t dev)

preparation should be done after setting all per-stream parameters the way you want them. being buffer data type etc...

Parameters
devthe ffado device
Returns

preparation should be done after setting all per-stream parameters the way you want them. being buffer data type etc...

Parameters
dev
Returns

◆ ffado_streaming_reset()

int ffado_streaming_reset ( ffado_device_t dev)

Resets the streaming as if it was stopped and restarted. The difference is that the connections are not nescessarily broken and restored.

All buffers are reset in the initial state and all data in them is lost.

Parameters
devthe ffado device
Returns
0 on success, -1 on failure.

◆ ffado_streaming_set_audio_datatype()

int ffado_streaming_set_audio_datatype ( ffado_device_t dev,
ffado_streaming_audio_datatype  t 
)

◆ ffado_streaming_set_capture_stream_buffer()

int ffado_streaming_set_capture_stream_buffer ( ffado_device_t dev,
int  number,
char *  buff 
)

Sets the decode buffer for the stream. This allows for zero-copy decoding. The call to ffado_streaming_transfer_buffers will decode one period of the stream to this buffer. Make sure it is large enough.

Parameters
devthe ffado device
numberthe stream number
buffa pointer to the sample buffer, make sure it is large enough i.e. sizeof(your_sample_type)*period_size
tthe type of the buffer. this determines sample type and the decode function used.
Returns
-1 on error, 0 on success

◆ ffado_streaming_set_period_size()

int ffado_streaming_set_period_size ( ffado_device_t dev,
unsigned int  period 
)

This permits the setting of the period size at some time after initialisation. The primary use of this function is to support the setbufsize functionality of JACK.

Parameters
devthe ffado device
periodthe new period size
Returns
0 on success, non-zero if an error occurred

◆ ffado_streaming_set_playback_stream_buffer()

int ffado_streaming_set_playback_stream_buffer ( ffado_device_t dev,
int  number,
char *  buff 
)

Sets the encode buffer for the stream. This allows for zero-copy encoding (directly to the events). The call to ffado_streaming_transfer_buffers will encode one period of the stream from this buffer to the event buffer.

Parameters
devthe ffado device
numberthe stream number
buffa pointer to the sample buffer
tthe type of the buffer. this determines sample type and the decode function used.
Returns
-1 on error, 0 on success

◆ ffado_streaming_start()

int ffado_streaming_start ( ffado_device_t dev)

Starts the streaming operation. This initiates the connections to the FFADO devices and starts the packet handling thread(s). This has to be called before any I/O can occur.

Parameters
devthe ffado device
Returns
0 on success, -1 on failure.

◆ ffado_streaming_stop()

int ffado_streaming_stop ( ffado_device_t dev)

Stops the streaming operation. This closes the connections to the FFADO devices and stops the packet handling thread(s).

Parameters
devthe ffado device
Returns
0 on success, -1 on failure.

◆ ffado_streaming_transfer_buffers()

int ffado_streaming_transfer_buffers ( ffado_device_t dev)

Transfer & decode the events from the packet buffer to the sample buffers

This should be called after the wait call returns, before reading/writing the sample buffers with ffado_streaming_[read|write].

The purpose is to allow more precise timing information. ffado_streaming_wait returns as soon as the period boundary is crossed, and can therefore be used to determine the time instant of this crossing (e.g. jack DLL).

The actual decoding work is done in this function and can therefore be omitted in this timing calculation. Note that you HAVE to call this function in order for the buffers not to overflow, and only call it when ffado_streaming_wait doesn't indicate a buffer xrun (xrun handler resets buffer).

If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers their contents should be valid before calling this function. If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers their contents are updated in this function.

Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers to have more control. Don't use both.

Parameters
devthe ffado device
Returns
-1 on error.

◆ ffado_streaming_transfer_capture_buffers()

int ffado_streaming_transfer_capture_buffers ( ffado_device_t dev)

Transfer & decode the events from the packet buffer to the sample buffers

This should be called after the wait call returns, before reading the sample buffers with ffado_streaming_read.

If user supplied capture buffers are specified with ffado_streaming_set_capture_buffers their contents are updated in this function.

Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers to have more control. Don't use both.

Parameters
devthe ffado device
Returns
-1 on error.

◆ ffado_streaming_transfer_playback_buffers()

int ffado_streaming_transfer_playback_buffers ( ffado_device_t dev)

Transfer & encode the events from the sample buffers to the packet buffer

This should be called after the wait call returns, after writing the sample buffers with ffado_streaming_write.

If user supplied playback buffers are specified with ffado_streaming_set_playback_buffers their contents should be valid before calling this function.

Use either ffado_streaming_transfer_buffers to transfer all buffers at once, or use ffado_streaming_transfer_playback_buffers and ffado_streaming_transfer_capture_buffers to have more control. Don't use both.

Parameters
devthe ffado device
Returns
-1 on error.

◆ ffado_streaming_wait()

ffado_wait_response ffado_streaming_wait ( ffado_device_t dev)

Waits until there is at least one period of data available on all capture connections and room for one period of data on all playback connections

Parameters
devthe ffado device
Returns
The number of frames ready. -1 when a problem occurred.