# API documentation for libmpg123, libout123, and libsyn123

Note: This API doc is automatically generated from the current development version that you can get via Subversion or as a daily snapshot from http://mpg123.org/snapshot. There may be differences (additions) compared to the latest stable release. See NEWS.libmpg123, NEWS.libout123, NEWS.libsyn123, and the overall NEWS file on libmpg123 versions and important changes between them.
Let me emphasize that the policy for the lib*123 family is to always stay backwards compatible -- only additions are planned (and it's not yet planned to change the plans;-).
Typedefs | Functions
mpg123 advanced parameter API

Direct access to a parameter set without full handle around it. Possible uses: More...

## Typedefs
typedef struct mpg123_pars_struct | mpg123_pars

## Functions
MPG123_EXPORT mpg123_handle * | mpg123_parnew (mpg123_pars *mp, const char *decoder, int *error)
MPG123_EXPORT mpg123_pars * | mpg123_new_pars (int *error)
MPG123_EXPORT void | mpg123_delete_pars (mpg123_pars *mp)
MPG123_EXPORT int | mpg123_fmt_none (mpg123_pars *mp)
MPG123_EXPORT int | mpg123_fmt_all (mpg123_pars *mp)
MPG123_EXPORT int | mpg123_fmt (mpg123_pars *mp, long rate, int channels, int encodings)
MPG123_EXPORT int | mpg123_fmt2 (mpg123_pars *mp, long rate, int channels, int encodings)
MPG123_EXPORT int | mpg123_fmt_support (mpg123_pars *mp, long rate, int encoding)
MPG123_EXPORT int | mpg123_par (mpg123_pars *mp, enum mpg123_parms type, long value, double fvalue)
MPG123_EXPORT int | mpg123_par2 (mpg123_pars *mp, int type, long value, double fvalue)
MPG123_EXPORT int | mpg123_getpar (mpg123_pars *mp, enum mpg123_parms type, long *value, double *fvalue)
MPG123_EXPORT int | mpg123_getpar2 (mpg123_pars *mp, int type, long *value, double *fvalue)

## Detailed Description

Direct access to a parameter set without full handle around it. Possible uses:

- Influence behaviour of library during initialization of handle (MPG123_VERBOSE).
- Use one set of parameters for multiple handles.

The functions for handling mpg123_pars (mpg123_par() and mpg123_fmt() family) directly return a fully qualified mpg123 error code, the ones operating on full handles normally MPG123_OK or MPG123_ERR, storing the specific error code itseld inside the handle.

## Typedef Documentation

## ◆ mpg123_pars

typedef struct mpg123_pars_struct mpg123_pars

Opaque structure for the libmpg123 decoder parameters.

Definition at line 2128 of file mpg123.h.

## Function Documentation

## ◆ mpg123_parnew()

MPG123_EXPORT mpg123_handle* mpg123_parnew | ( | mpg123_pars * | mp,
|  | const char * | decoder,
|  | int * | error
| ) |  |

Create a handle with preset parameters.

Parameters

  mp | parameter handle
  decoder | decoder choice
  error | error code return address

Returns
  mpg123 handle

## ◆ mpg123_new_pars()

MPG123_EXPORT mpg123_pars* mpg123_new_pars | ( | int * | error | ) |

Allocate memory for and return a pointer to a new mpg123_pars

Parameters

  error | error code return address

Returns
  new parameter handle

## ◆ mpg123_delete_pars()

MPG123_EXPORT void mpg123_delete_pars | ( | mpg123_pars * | mp | ) |

Delete and free up memory used by a mpg123_pars data structure

Parameters

  mp | parameter handle

## ◆ mpg123_fmt_none()

MPG123_EXPORT int mpg123_fmt_none | ( | mpg123_pars * | mp | ) |

Configure mpg123 parameters to accept no output format at all, use before specifying supported formats with mpg123_format

Parameters

  mp | parameter handle

Returns
  MPG123_OK on success

## ◆ mpg123_fmt_all()

MPG123_EXPORT int mpg123_fmt_all | ( | mpg123_pars * | mp | ) |

Configure mpg123 parameters to accept all formats (also any custom rate you may set) – this is default.

Parameters

  mp | parameter handle

Returns
  MPG123_OK on success

## ◆ mpg123_fmt()

MPG123_EXPORT int mpg123_fmt | ( | mpg123_pars * | mp,
|  | long | rate,
|  | int | channels,
|  | int | encodings
| ) |  |

Set the audio format support of a mpg123_pars in detail:

Parameters

  mp | parameter handle
  rate | The sample rate value (in Hertz).
  channels | A combination of MPG123_STEREO and MPG123_MONO.
  encodings | A combination of accepted encodings for rate and channels, p.ex MPG123_ENC_SIGNED16|MPG123_ENC_ULAW_8 (or 0 for no support).

Returns
  MPG123_OK on success

## ◆ mpg123_fmt2()

MPG123_EXPORT int mpg123_fmt2 | ( | mpg123_pars * | mp,
|  | long | rate,
|  | int | channels,
|  | int | encodings
| ) |  |

Set the audio format support of a mpg123_pars in detail:

Parameters

  mp | parameter handle
  rate | The sample rate value (in Hertz). Special value 0 means all rates (reason for this variant of mpg123_fmt).
  channels | A combination of MPG123_STEREO and MPG123_MONO.
  encodings | A combination of accepted encodings for rate and channels, p.ex MPG123_ENC_SIGNED16|MPG123_ENC_ULAW_8 (or 0 for no support).

Returns
  MPG123_OK on success

## ◆ mpg123_fmt_support()

MPG123_EXPORT int mpg123_fmt_support | ( | mpg123_pars * | mp,
|  | long | rate,
|  | int | encoding
| ) |  |

Check to see if a specific format at a specific rate is supported by mpg123_pars.

Parameters

  mp | parameter handle
  rate | sampling rate
  encoding | encoding

Returns
  0 for no support (that includes invalid parameters), MPG123_STEREO, MPG123_MONO or MPG123_STEREO|MPG123_MONO.

## ◆ mpg123_par()

MPG123_EXPORT int mpg123_par | ( | mpg123_pars * | mp,
|  | enum mpg123_parms | type,
|  | long | value,
|  | double | fvalue
| ) |  |

Set a specific parameter in a par handle.

Note that this name is mapped to mpg123_par2() instead unless MPG123_ENUM_API is defined.

Parameters

  mp | parameter handle
  type | parameter choice
  value | integer value
  fvalue | floating point value

Returns
  MPG123_OK on success

## ◆ mpg123_par2()

MPG123_EXPORT int mpg123_par2 | ( | mpg123_pars * | mp,
|  | int | type,
|  | long | value,
|  | double | fvalue
| ) |  |

Set a specific parameter in a par handle. No enums.

This is actually called instead of mpg123_par() unless MPG123_ENUM_API is defined.

Parameters

  mp | parameter handle
  type | parameter choice (enum mpg123_parms)
  value | integer value
  fvalue | floating point value

Returns
  MPG123_OK on success

## ◆ mpg123_getpar()

MPG123_EXPORT int mpg123_getpar | ( | mpg123_pars * | mp,
|  | enum mpg123_parms | type,
|  | long * | value,
|  | double * | fvalue
| ) |  |

Get a specific parameter from a par handle.

Note that this name is mapped to mpg123_getpar2() instead unless MPG123_ENUM_API is defined.

Parameters

  mp | parameter handle
  type | parameter choice
  value | integer value return address
  fvalue | floating point value return address

Returns
  MPG123_OK on success

## ◆ mpg123_getpar2()

MPG123_EXPORT int mpg123_getpar2 | ( | mpg123_pars * | mp,
|  | int | type,
|  | long * | value,
|  | double * | fvalue
| ) |  |

Get a specific parameter from a par handle. No enums.

This is actually called instead of mpg123_getpar() unless MPG123_ENUM_API is defined.

Parameters

  mp | parameter handle
  type | parameter choice (enum mpg123_parms)
  value | integer value return address
  fvalue | floating point value return address

Returns
  MPG123_OK on success