# 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;-).
Functions
mpg123 position and seeking

Functions querying and manipulating position in the decoded audio bitstream. The position is measured in decoded audio samples or MPEG frame offset for the specific functions. The term sample refers to a group of samples for multiple channels, normally dubbed PCM frames. The latter term is avoided here because frame means something different in the context of MPEG audio. Since all samples of a PCM frame occur at the same time, there is only very limited ambiguity when talking about playback offset, as counting each channel sample individually does not make sense. More...

## Functions
MPG123_EXPORT off_t | mpg123_tell (mpg123_handle *mh)
MPG123_EXPORT int64_t | mpg123_tell64 (mpg123_handle *mh)
MPG123_EXPORT off_t | mpg123_tellframe (mpg123_handle *mh)
MPG123_EXPORT int64_t | mpg123_tellframe64 (mpg123_handle *mh)
MPG123_EXPORT off_t | mpg123_tell_stream (mpg123_handle *mh)
MPG123_EXPORT int64_t | mpg123_tell_stream64 (mpg123_handle *mh)
MPG123_EXPORT off_t | mpg123_seek (mpg123_handle *mh, off_t sampleoff, int whence)
MPG123_EXPORT int64_t | mpg123_seek64 (mpg123_handle *mh, int64_t sampleoff, int whence)
MPG123_EXPORT off_t | mpg123_feedseek (mpg123_handle *mh, off_t sampleoff, int whence, off_t *input_offset)
MPG123_EXPORT int64_t | mpg123_feedseek64 (mpg123_handle *mh, int64_t sampleoff, int whence, int64_t *input_offset)
MPG123_EXPORT off_t | mpg123_seek_frame (mpg123_handle *mh, off_t frameoff, int whence)
MPG123_EXPORT int64_t | mpg123_seek_frame64 (mpg123_handle *mh, int64_t frameoff, int whence)
MPG123_EXPORT off_t | mpg123_timeframe (mpg123_handle *mh, double sec)
MPG123_EXPORT int | mpg123_index (mpg123_handle *mh, off_t **offsets, off_t *step, size_t *fill)
MPG123_EXPORT int64_t | mpg123_timeframe64 (mpg123_handle *mh, double sec)
MPG123_EXPORT int | mpg123_index64 (mpg123_handle *mh, int64_t **offsets, int64_t *step, size_t *fill)
MPG123_EXPORT int | mpg123_set_index (mpg123_handle *mh, off_t *offsets, off_t step, size_t fill)
MPG123_EXPORT int | mpg123_set_index64 (mpg123_handle *mh, int64_t *offsets, int64_t step, size_t fill)
MPG123_EXPORT int | mpg123_position (mpg123_handle *mh, off_t INT123_frame_offset, off_t buffered_bytes, off_t *current_frame, off_t *frames_left, double *current_seconds, double *seconds_left)

## Detailed Description

Functions querying and manipulating position in the decoded audio bitstream. The position is measured in decoded audio samples or MPEG frame offset for the specific functions. The term sample refers to a group of samples for multiple channels, normally dubbed PCM frames. The latter term is avoided here because frame means something different in the context of MPEG audio. Since all samples of a PCM frame occur at the same time, there is only very limited ambiguity when talking about playback offset, as counting each channel sample individually does not make sense.

If gapless code is in effect, the positions are adjusted to compensate the skipped padding/delay - meaning, you should not care about that at all and just use the position defined for the samples you get out of the decoder;-) The general usage is modelled after stdlib's ftell() and fseek(). Especially, the whence parameter for the seek functions has the same meaning as the one for fseek() and needs the same constants from stdlib.h:

- SEEK_SET: set position to (or near to) specified offset
- SEEK_CUR: change position by offset from now
- SEEK_END: set position to offset from end

Since API version 48 (mpg123 1.32), the offset given with SEEK_END is always taken to be negative in the terms of standard lseek(). You can only seek from the end towards the beginning. All earlier versions had the sign wrong, positive was towards the beginning, negative past the end (which results in error, anyway).

Note that sample-accurate seek only works when gapless support has been enabled at compile time; seek is frame-accurate otherwise. Also, really sample-accurate seeking (meaning that you get the identical sample value after seeking compared to plain decoding up to the position) is only guaranteed when you do not mess with the position code by using MPG123_UPSPEED, MPG123_DOWNSPEED or MPG123_START_FRAME. The first two mainly should cause trouble with NtoM resampling, but in any case with these options in effect, you have to keep in mind that the sample offset is not the same as counting the samples you get from decoding since mpg123 counts the skipped samples, too (or the samples played twice only once)!

Short: When you care about the sample position, don't mess with those parameters;-)

Streams may be openend in ways that do not support seeking. Also, consider the effect of MPG123_FUZZY.

## Function Documentation

## ◆ mpg123_tell()

MPG123_EXPORT off_t mpg123_tell | ( | mpg123_handle * | mh | ) |

Returns the current position in samples. On the next successful read, you'd get audio data with that offset.

Parameters

  mh | handle

Returns
  sample (PCM frame) offset or MPG123_ERR (null handle)

## ◆ mpg123_tell64()

MPG123_EXPORT int64_t mpg123_tell64 | ( | mpg123_handle * | mh | ) |

Returns the current 64 bit position in samples. On the next successful read, you'd get audio data with that offset.

Parameters

  mh | handle

Returns
  sample (PCM frame) offset or MPG123_ERR (null handle)

## ◆ mpg123_tellframe()

MPG123_EXPORT off_t mpg123_tellframe | ( | mpg123_handle * | mh | ) |

Returns the frame number that the next read will give you data from.

Parameters

  mh | handle

Returns
  frame offset or MPG123_ERR (null handle)

## ◆ mpg123_tellframe64()

MPG123_EXPORT int64_t mpg123_tellframe64 | ( | mpg123_handle * | mh | ) |

Returns the 64 bit frame number that the next read will give you data from.

Parameters

  mh | handle

Returns
  frame offset or MPG123_ERR (null handle)

## ◆ mpg123_tell_stream()

MPG123_EXPORT off_t mpg123_tell_stream | ( | mpg123_handle * | mh | ) |

Returns the current byte offset in the input stream.

Parameters

  mh | handle

Returns
  byte offset or MPG123_ERR (null handle)

## ◆ mpg123_tell_stream64()

MPG123_EXPORT int64_t mpg123_tell_stream64 | ( | mpg123_handle * | mh | ) |

Returns the current 64 bit byte offset in the input stream.

Parameters

  mh | handle

Returns
  byte offset or MPG123_ERR (null handle)

## ◆ mpg123_seek()

MPG123_EXPORT off_t mpg123_seek | ( | mpg123_handle * | mh,
|  | off_t | sampleoff,
|  | int | whence
| ) |  |

Seek to a desired sample offset. Usage is modelled afer the standard lseek().

Parameters

  mh | handle
  sampleoff | offset in samples (PCM frames)
  whence | one of SEEK_SET, SEEK_CUR or SEEK_END (Offset for SEEK_END is always effectively negative since API version 48, was inverted from lseek() usage since ever before.)

Returns
  The resulting offset >= 0 or error/message code

## ◆ mpg123_seek64()

MPG123_EXPORT int64_t mpg123_seek64 | ( | mpg123_handle * | mh,
|  | int64_t | sampleoff,
|  | int | whence
| ) |  |

Seek to a desired 64 bit sample offset. Usage is modelled afer the standard lseek().

Parameters

  mh | handle
  sampleoff | offset in samples (PCM frames)
  whence | one of SEEK_SET, SEEK_CUR or SEEK_END (Offset for SEEK_END is always effectively negative.)

Returns
  The resulting offset >= 0 or error/message code

## ◆ mpg123_feedseek()

MPG123_EXPORT off_t mpg123_feedseek | ( | mpg123_handle * | mh,
|  | off_t | sampleoff,
|  | int | whence,
|  | off_t * | input_offset
| ) |  |

Seek to a desired sample offset in data feeding mode. This just prepares things to be right only if you ensure that the next chunk of input data will be from input_offset byte position.

Parameters

  mh | handle
  sampleoff | offset in samples (PCM frames)
  whence | one of SEEK_SET, SEEK_CUR or SEEK_END (Offset for SEEK_END is always effectively negative since API version 48, was inverted from lseek() usage since ever before.)
  input_offset | The position it expects to be at the next time data is fed to mpg123_decode().

Returns
  The resulting offset >= 0 or error/message code

## ◆ mpg123_feedseek64()

MPG123_EXPORT int64_t mpg123_feedseek64 | ( | mpg123_handle * | mh,
|  | int64_t | sampleoff,
|  | int | whence,
|  | int64_t * | input_offset
| ) |  |

Seek to a desired 64 bit sample offset in data feeding mode. This just prepares things to be right only if you ensure that the next chunk of input data will be from input_offset byte position.

Parameters

  mh | handle
  sampleoff | offset in samples (PCM frames)
  whence | one of SEEK_SET, SEEK_CUR or SEEK_END (Offset for SEEK_END is always effectively negative.)
  input_offset | The position it expects to be at the next time data is fed to mpg123_decode().

Returns
  The resulting offset >= 0 or error/message code

## ◆ mpg123_seek_frame()

MPG123_EXPORT off_t mpg123_seek_frame | ( | mpg123_handle * | mh,
|  | off_t | frameoff,
|  | int | whence
| ) |  |

Seek to a desired MPEG frame offset. Usage is modelled afer the standard lseek().

Parameters

  mh | handle
  frameoff | offset in MPEG frames
  whence | one of SEEK_SET, SEEK_CUR or SEEK_END (Offset for SEEK_END is always effectively negative since API version 48, was inverted from lseek() usage since ever before.)

Returns
  The resulting offset >= 0 or error/message code

## ◆ mpg123_seek_frame64()

MPG123_EXPORT int64_t mpg123_seek_frame64 | ( | mpg123_handle * | mh,
|  | int64_t | frameoff,
|  | int | whence
| ) |  |

Seek to a desired 64 bit MPEG frame offset. Usage is modelled afer the standard lseek().

Parameters

  mh | handle
  frameoff | offset in MPEG frames
  whence | one of SEEK_SET, SEEK_CUR or SEEK_END (Offset for SEEK_END is always effectively negative.)

Returns
  The resulting offset >= 0 or error/message code

## ◆ mpg123_timeframe()

MPG123_EXPORT off_t mpg123_timeframe | ( | mpg123_handle * | mh,
|  | double | sec
| ) |  |

Return a MPEG frame offset corresponding to an offset in seconds. This assumes that the samples per frame do not change in the file/stream, which is a good assumption for any sane file/stream only.

Returns
  frame offset >= 0 or error/message code

## ◆ mpg123_index()

MPG123_EXPORT int mpg123_index | ( | mpg123_handle * | mh,
|  | off_t ** | offsets,
|  | off_t * | step,
|  | size_t * | fill
| ) |  |

Give access to the frame index table that is managed for seeking. You are asked not to modify the values... Use mpg123_set_index to set the seek index. Note: This can be just a copy of the data in case a conversion is done from the internal 64 bit values.

Parameters

  mh | handle
  offsets | pointer to the index array
  step | one index byte offset advances this many MPEG frames
  fill | number of recorded index offsets; size of the array

Returns
  MPG123_OK on success

## ◆ mpg123_timeframe64()

MPG123_EXPORT int64_t mpg123_timeframe64 | ( | mpg123_handle * | mh,
|  | double | sec
| ) |  |

Return a 64 bit MPEG frame offset corresponding to an offset in seconds. This assumes that the samples per frame do not change in the file/stream, which is a good assumption for any sane file/stream only.

Returns
  frame offset >= 0 or error/message code

## ◆ mpg123_index64()

MPG123_EXPORT int mpg123_index64 | ( | mpg123_handle * | mh,
|  | int64_t ** | offsets,
|  | int64_t * | step,
|  | size_t * | fill
| ) |  |

Give access to the 64 bit frame index table that is managed for seeking. You are asked not to modify the values... Use mpg123_set_index to set the seek index.

Parameters

  mh | handle
  offsets | pointer to the index array
  step | one index byte offset advances this many MPEG frames
  fill | number of recorded index offsets; size of the array

Returns
  MPG123_OK on success

## ◆ mpg123_set_index()

MPG123_EXPORT int mpg123_set_index | ( | mpg123_handle * | mh,
|  | off_t * | offsets,
|  | off_t | step,
|  | size_t | fill
| ) |  |

Set the frame index table Setting offsets to NULL and fill > 0 will allocate fill entries. Setting offsets to NULL and fill to 0 will clear the index and free the allocated memory used by the index. Note that this function might involve conversion/copying of data because of the varying nature of off_t. Better use mpg123_set_index64().

Parameters

  mh | handle
  offsets | pointer to the index array
  step | one index byte offset advances this many MPEG frames
  fill | number of recorded index offsets; size of the array

Returns
  MPG123_OK on success

## ◆ mpg123_set_index64()

MPG123_EXPORT int mpg123_set_index64 | ( | mpg123_handle * | mh,
|  | int64_t * | offsets,
|  | int64_t | step,
|  | size_t | fill
| ) |  |

Set the 64 bit frame index table Setting offsets to NULL and fill > 0 will allocate fill entries. Setting offsets to NULL and fill to 0 will clear the index and free the allocated memory used by the index.

Parameters

  mh | handle
  offsets | pointer to the index array
  step | one index byte offset advances this many MPEG frames
  fill | number of recorded index offsets; size of the array

Returns
  MPG123_OK on success

## ◆ mpg123_position()

MPG123_EXPORT int mpg123_position | ( | mpg123_handle * | mh,
|  | off_t | INT123_frame_offset,
|  | off_t | buffered_bytes,
|  | off_t * | current_frame,
|  | off_t * | frames_left,
|  | double * | current_seconds,
|  | double * | seconds_left
| ) |  |

An old crutch to keep old mpg123 binaries happy. WARNING: This function is there only to avoid runtime linking errors with standalone mpg123 before version 1.32.0 (if you strangely update the library but not the end-user program) and actually is broken for various cases (p.ex. 24 bit output). Do never use. It might eventually be purged from the library.