handling AmbiX files More...

Modules
	ambix_readf()
	Read samples from the ambix fileReads samples from an ambix file, possibly expanding a reduced channel set to a full ambisonics set (when reading an 'ambix extended' file as 'ambix basic')

	ambix_writef()
	Write samples to the ambix file.Writes samples (as single precision floating point values) to an ambix file, possibly expanding a reduced channel set to a full ambisonics set (when writing an 'ambix extended' file as 'ambix basic').

Functions
AMBIX_API ambix_t *	ambix_open (const char path, const ambix_filemode_t mode, ambix_info_t ambixinfo)
	Open an ambix file. More...

AMBIX_API ambix_err_t	ambix_close (ambix_t *ambix)
	Close an ambix handle. More...

AMBIX_API int64_t	ambix_seek (ambix_t *ambix, int64_t frames, int whence)
	Reposition the file pointer. More...

AMBIX_API struct SNDFILE_tag *	ambix_get_sndfile (ambix_t *ambix)
	Get the libsndfile handle associated with the ambix handle. More...

AMBIX_API uint32_t	ambix_get_num_markers (ambix_t *ambix)
	Get the number of stored markers within the ambix file. More...

AMBIX_API uint32_t	ambix_get_num_regions (ambix_t *ambix)
	Get the number of stored regions within the ambix file. More...

AMBIX_API ambix_marker_t *	ambix_get_marker (ambix_t *ambix, uint32_t id)
	Get one marker. More...

AMBIX_API ambix_region_t *	ambix_get_region (ambix_t *ambix, uint32_t id)
	Get one region. More...

AMBIX_API ambix_err_t	ambix_add_marker (ambix_t ambix, ambix_marker_t marker)
	Add a new marker to the ambix file. More...

AMBIX_API ambix_err_t	ambix_add_region (ambix_t ambix, ambix_region_t region)
	Add a new region to the ambix file. More...

AMBIX_API ambix_err_t	ambix_delete_markers (ambix_t *ambix)
	Deletes all markers in the ambix file. More...

AMBIX_API ambix_err_t	ambix_delete_regions (ambix_t *ambix)
	Deletes all regions in the ambix file. More...

AMBIX_API const ambix_matrix_t *	ambix_get_adaptormatrix (ambix_t *ambix)
	Get the adaptor matrix. More...

AMBIX_API ambix_err_t	ambix_set_adaptormatrix (ambix_t ambix, const ambix_matrix_t matrix)
	Set a matrix to be pre-multiplied. More...

Detailed Description

handling AmbiX files

Function Documentation

AMBIX_API ambix_err_t ambix_add_marker	(	ambix_t *	ambix,
		ambix_marker_t *	marker
	)

Add a new marker to the ambix file.

Remarks: Markers have to be set before sample data is written!

Parameters

ambix	The handle to an ambix file
marker	A valid marker that should be added to the ambix file.

Returns: an errorcode indicating success.

AMBIX_API ambix_err_t ambix_add_region	(	ambix_t *	ambix,
		ambix_region_t *	region
	)

Add a new region to the ambix file.

Remarks: Regions have to be set before sample data is written!

Parameters

ambix	The handle to an ambix file
region	A valid region that should be added to the ambix file.

Returns: an errorcode indicating success.

AMBIX_API ambix_err_t ambix_close ( ambix_t * ambix )

Close an ambix handle.

Closes an ambix handle and cleans up all memory allocations associated with it.

Parameters

ambix The handle to an ambix file

Returns: an error code indicating success

AMBIX_API ambix_err_t ambix_delete_markers ( ambix_t * ambix )

Deletes all markers in the ambix file.

Parameters

ambix The handle to an ambix file

Returns: an errorcode indicating success.

AMBIX_API ambix_err_t ambix_delete_regions ( ambix_t * ambix )

Deletes all regions in the ambix file.

Parameters

ambix The handle to an ambix file

Returns: an errorcode indicating success.

AMBIX_API const ambix_matrix_t* ambix_get_adaptormatrix ( ambix_t * ambix )

Get the adaptor matrix.

The ambix extended fileformat comes with a adaptor matrix, that can be used to reconstruct a full 3d ambisonics set from the channels stored in ambix file. In the ambix AMBIX_BASIC format no adaptor matrix is present, the file always contains the full set.

Remarks: the adaptor matrix can only be obtained for a ambix extended file; if you have opened an ambix extended file as "ambix basic", the adaptor will be done by the library; in this case, you will not be able to fetch the adaptor matrix.; if you have opened an ambix basic file as ambix extended, this will return a unity matrix.

Parameters

ambix The handle to an ambix file

Returns: the adaptor matrix to restore the full ambisonics set from the reduced set, or NULL if there is no such matrix; the memory is owned by the library and must neither be freed nor used after calling ambix_close().

AMBIX_API ambix_marker_t* ambix_get_marker	(	ambix_t *	ambix,
		uint32_t	id
	)

Get one marker.

Parameters

ambix	The handle to an ambix file
id	The id of the marker to retrieve.

Returns: The marker requested or NULL in case the marker does not exist.

AMBIX_API uint32_t ambix_get_num_markers ( ambix_t * ambix )

Get the number of stored markers within the ambix file.

Returns: number of markers.

AMBIX_API uint32_t ambix_get_num_regions ( ambix_t * ambix )

Get the number of stored regions within the ambix file.

Parameters

ambix The handle to an ambix file

Returns: Number of regions.

AMBIX_API ambix_region_t* ambix_get_region	(	ambix_t *	ambix,
		uint32_t	id
	)

Get one region.

Parameters

ambix	The handle to an ambix file
id	The id of the region to retrieve.

Returns: The region requested or NULL in case the region does not exist.

AMBIX_API struct SNDFILE_tag* ambix_get_sndfile ( ambix_t * ambix )

Get the libsndfile handle associated with the ambix handle.

If possible, require an SNDFILE handle if possible; if the ambix handle is not associated with SNDFILE (e.g. because libambix is compiled without libsndfile support), NULL is returned.

Parameters

ambix The handle to an ambix file

Returns: A libsndfile handle or NULL

AMBIX_API ambix_t* ambix_open	(	const char *	path,
		const ambix_filemode_t	mode,
		ambix_info_t *	ambixinfo
	)

Open an ambix file.

Opens a soundfile for reading/writing

Parameters

path	filename of the file to open
mode	whether to open the file for reading and/or writing (AMBIX_READ, AMBIX_WRITE, AMBIX_RDRW)
ambixinfo	pointer to a valid ambix_info_t structure

Remarks: when opening a file for reading, the structure should be initialized to zero before calling ambix_open(): the fields will be set by the library; if you set the ambixinfo.ambixformat field to something else than AMBIX_NONE, the library will present the data as if the was written in this format (e.g. if you set ambixinfo.ambixformat to AMBIX_BASIC but the file really is AMBIX_EXTENDED, the library will automatically pre-multiply the reconstruction matrix to give you the full ambisonics set.; when opening a file for writing, the caller must set the fields; if ambixinfo.ambixformat is AMBIX_NONE, than ambixinfo.ambichannels must be 0, else ambixinfo.ambichannels must be >0; if ambixinfo.ambixformat is AMBIX_BASIC, then ambixinfo.ambichannels must be \((order_{ambi}+1)^2\)

Returns: A handle to the opened file (or NULL on failure)

AMBIX_API int64_t ambix_seek	(	ambix_t *	ambix,
		int64_t	frames,
		int	whence
	)

Reposition the file pointer.

Reposition the file read (and/or write) pointer to a new offset. Consecutive calls to ambix_readf() (resp. ambix_writef()) will read (resp. write) from the new position.

Parameters

ambix	The handle to an ambix file
frames	frame offset from the position given in whence
whence	location from where to seek; if whence is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset is relative to the start of the file, the current position indicator, or end-of-file, respectively.

Returns: the offset in (multichannel) frames from the start of the audio data or -1 if an error occurred.

AMBIX_API ambix_err_t ambix_set_adaptormatrix	(	ambix_t *	ambix,
		const ambix_matrix_t *	matrix
	)

Set a matrix to be pre-multiplied.

Adds an (additional) adaptor matrix to the processing. Depending on the mode of operation this can have different meanings! When READing an ambix 'AMBIX_BASIC' file, this tells the library to do an (additional) matrix-multiplication When reconstructing the full ambisonics set; you can use this to get the ambisonics channels in a format other than SN3D/ACN (e.g. using an ambix to Furse-Malham adaptor matrix) or getting the loudspeaker feeds directly (by supplying a decoder matrix); in this case, the matrix MUST have ambix->ambichannels columns. When WRITEing an ambix 'AMBIX_EXTENDED' file, this tells the library to store the matrix as the adaptor matrix within the file.

Parameters

ambix	The handle to an ambix file
matrix	a matrix that will be pre-multiplied to the reconstruction-matrix; can be freed after this call.

Returns: an errorcode indicating success

Remarks: using this on ambix handles other than AMBIX_READ/AMBIX_BASIC or AMBIX_WRITE/AMBIX_EXTENDED is an error.

Modules

Functions

Detailed Description

Function Documentation