# 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;-).
Enumerations | Functions
mpg123 volume and equalizer

## Enumerations
enum | mpg123_channels { MPG123_LEFT =0x1, MPG123_RIGHT =0x2, MPG123_LR =0x3 }

## Functions
MPG123_EXPORT int | mpg123_eq (mpg123_handle *mh, enum mpg123_channels channel, int band, double val)
MPG123_EXPORT int | mpg123_eq2 (mpg123_handle *mh, int channel, int band, double val)
MPG123_EXPORT int | mpg123_eq_bands (mpg123_handle *mh, int channel, int a, int b, double factor)
MPG123_EXPORT int | mpg123_eq_change (mpg123_handle *mh, int channel, int a, int b, double db)
MPG123_EXPORT double | mpg123_geteq (mpg123_handle *mh, enum mpg123_channels channel, int band)
MPG123_EXPORT double | mpg123_geteq2 (mpg123_handle *mh, int channel, int band)
MPG123_EXPORT int | mpg123_reset_eq (mpg123_handle *mh)
MPG123_EXPORT int | mpg123_volume (mpg123_handle *mh, double vol)
MPG123_EXPORT int | mpg123_volume_change (mpg123_handle *mh, double change)
MPG123_EXPORT int | mpg123_volume_change_db (mpg123_handle *mh, double db)
MPG123_EXPORT int | mpg123_getvolume (mpg123_handle *mh, double *base, double *really, double *rva_db)

## Detailed Description

## Enumeration Type Documentation

## ◆ mpg123_channels

enum mpg123_channels

another channel enumeration, for left/right choice

Enumerator
MPG123_LEFT | The Left Channel.
MPG123_RIGHT | The Right Channel.
MPG123_LR | Both left and right channel; same as MPG123_LEFT|MPG123_RIGHT

Definition at line 1327 of file mpg123.h.

## Function Documentation

## ◆ mpg123_eq()

MPG123_EXPORT int mpg123_eq | ( | mpg123_handle * | mh,
|  | enum mpg123_channels | channel,
|  | int | band,
|  | double | val
| ) |  |

Set the 32 Band Audio Equalizer settings.

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

Parameters

  mh | handle
  channel | Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for both.
  band | The equaliser band to change (from 0 to 31)
  val | The (linear) adjustment factor.

Returns
  MPG123_OK on success

## ◆ mpg123_eq2()

MPG123_EXPORT int mpg123_eq2 | ( | mpg123_handle * | mh,
|  | int | channel,
|  | int | band,
|  | double | val
| ) |  |

Set the 32 Band Audio Equalizer settings. No enums.

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

Parameters

  mh | handle
  channel | Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for both.
  band | The equaliser band to change (from 0 to 31)
  val | The (linear) adjustment factor.

Returns
  MPG123_OK on success

## ◆ mpg123_eq_bands()

MPG123_EXPORT int mpg123_eq_bands | ( | mpg123_handle * | mh,
|  | int | channel,
|  | int | a,
|  | int | b,
|  | double | factor
| ) |  |

Set a range of equalizer bands

Parameters

  channel | Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for both.
  mh | handle
  a | The first equalizer band to set (from 0 to 31)
  b | The last equalizer band to set (from 0 to 31)
  factor | The (linear) adjustment factor, 1 being neutral.

Returns
  MPG123_OK on success

## ◆ mpg123_eq_change()

MPG123_EXPORT int mpg123_eq_change | ( | mpg123_handle * | mh,
|  | int | channel,
|  | int | a,
|  | int | b,
|  | double | db
| ) |  |

Change a range of equalizer bands

Parameters

  mh | handle
  channel | Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for both.
  a | The first equalizer band to change (from 0 to 31)
  b | The last equalizer band to change (from 0 to 31)
  db | The adjustment in dB (limited to +/- 60 dB).

Returns
  MPG123_OK on success

## ◆ mpg123_geteq()

MPG123_EXPORT double mpg123_geteq | ( | mpg123_handle * | mh,
|  | enum mpg123_channels | channel,
|  | int | band
| ) |  |

Get the 32 Band Audio Equalizer settings.

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

Parameters

  mh | handle
  channel | Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for (arithmetic mean of) both.
  band | The equaliser band to change (from 0 to 31)

Returns
  The (linear) adjustment factor (zero for pad parameters)

## ◆ mpg123_geteq2()

MPG123_EXPORT double mpg123_geteq2 | ( | mpg123_handle * | mh,
|  | int | channel,
|  | int | band
| ) |  |

Get the 32 Band Audio Equalizer settings.

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

Parameters

  mh | handle
  channel | Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for (arithmetic mean of) both.
  band | The equaliser band to change (from 0 to 31)

Returns
  The (linear) adjustment factor (zero for pad parameters)

## ◆ mpg123_reset_eq()

MPG123_EXPORT int mpg123_reset_eq | ( | mpg123_handle * | mh | ) |

Reset the 32 Band Audio Equalizer settings to flat

Parameters

  mh | handle

Returns
  MPG123_OK on success

## ◆ mpg123_volume()

MPG123_EXPORT int mpg123_volume | ( | mpg123_handle * | mh,
|  | double | vol
| ) |  |

Set the absolute output volume including the RVA setting, vol<0 just applies (a possibly changed) RVA setting.

Parameters

  mh | handle
  vol | volume value (linear factor)

Returns
  MPG123_OK on success

## ◆ mpg123_volume_change()

MPG123_EXPORT int mpg123_volume_change | ( | mpg123_handle * | mh,
|  | double | change
| ) |  |

Adjust output volume including the RVA setting by chosen amount

Parameters

  mh | handle
  change | volume value (linear factor increment)

Returns
  MPG123_OK on success

## ◆ mpg123_volume_change_db()

MPG123_EXPORT int mpg123_volume_change_db | ( | mpg123_handle * | mh,
|  | double | db
| ) |  |

Adjust output volume including the RVA setting by chosen amount

Parameters

  mh | handle
  db | volume adjustment in decibels (limited to +/- 60 dB)

Returns
  MPG123_OK on success

## ◆ mpg123_getvolume()

MPG123_EXPORT int mpg123_getvolume | ( | mpg123_handle * | mh,
|  | double * | base,
|  | double * | really,
|  | double * | rva_db
| ) |  |

Return current volume setting, the actual value due to RVA, and the RVA adjustment itself. It's all as double float value to abstract the sample format. The volume values are linear factors / amplitudes (not percent) and the RVA value is in decibels.

Parameters

  mh | handle
  base | return address for base volume (linear factor)
  really | return address for actual volume (linear factor)
  rva_db | return address for RVA value (decibels)

Returns
  MPG123_OK on success