ambix

handling AmbiX files More...

## Topics

| ambix_readf()
| Read samples from the ambix file.
| ambix_writef()
| Write samples to the ambix file.

## Functions

AMBIX_API ambix_t * | ambix_open (const char *path, const ambix_filemode_t mode, ambix_info_t *ambixinfo)
| Open an ambix file.
AMBIX_API ambix_err_t | ambix_close (ambix_t *ambix)
| Close an ambix handle.
AMBIX_API int64_t | ambix_seek (ambix_t *ambix, int64_t frames, int whence)
| Reposition the file pointer.
AMBIX_API SNDFILE * | ambix_get_sndfile (ambix_t *ambix)
| Get the libsndfile handle associated with the ambix handle.
AMBIX_API uint32_t | ambix_get_num_markers (ambix_t *ambix)
| Get the number of stored markers within the ambix file.
AMBIX_API uint32_t | ambix_get_num_regions (ambix_t *ambix)
| Get the number of stored regions within the ambix file.
AMBIX_API ambix_marker_t * | ambix_get_marker (ambix_t *ambix, uint32_t id)
| Get one marker.
AMBIX_API ambix_region_t * | ambix_get_region (ambix_t *ambix, uint32_t id)
| Get one region.
AMBIX_API ambix_err_t | ambix_add_marker (ambix_t *ambix, ambix_marker_t *marker)
| Add a new marker to the ambix file.
AMBIX_API ambix_err_t | ambix_add_region (ambix_t *ambix, ambix_region_t *region)
| Add a new region to the ambix file.
AMBIX_API ambix_err_t | ambix_delete_markers (ambix_t *ambix)
| Deletes all markers in the ambix file.
AMBIX_API ambix_err_t | ambix_delete_regions (ambix_t *ambix)
| Deletes all regions in the ambix file.
AMBIX_API const ambix_matrix_t * | ambix_get_adaptormatrix (ambix_t *ambix)
| Get the adaptor matrix.
AMBIX_API ambix_err_t | ambix_set_adaptormatrix (ambix_t *ambix, const ambix_matrix_t *matrix)
| Set a matrix to be pre-multiplied.

## Detailed Description

handling AmbiX files

## Function Documentation

## ambix_add_marker()

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_add_region()

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_close()

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_delete_markers()

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_delete_regions()

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_get_adaptormatrix()

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_get_marker()

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_get_num_markers()

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_get_num_regions()

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_get_region()

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_get_sndfile()

AMBIX_API SNDFILE * ambix_get_sndfile | ( | ambix_t * | ambix | ) |

Get the libsndfile handle associated with the ambix handle.

If possible, require an SNDFILE handle; if the ambix handle is not associated with SNDFILE (e.g. because libambix is compiled without libsndfile support), NULL is returned. If you need this, you probably should include <sndfile.h> before including <ambix/ambix.h>

Parameters

  ambix | The handle to an ambix file

Returns
  A libsndfile handle or NULL

## ambix_open()

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_seek()

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_set_adaptormatrix()

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.