1 //
2 // mpg123.h header binding for the Free Pascal Compiler aka FPC
3 //
4 // Binaries and demos available at http://www.djmaster.com/
5 //
7 (*
8 libmpg123: MPEG Audio Decoder library
10 copyright 1995-2015 by the mpg123 project
11 free software under the terms of the LGPL 2.1
12 see COPYING and AUTHORS files in distribution or http://mpg123.org
13 *)
16 (** \file mpg123.h The header file for the libmpg123 MPEG Audio decoder *)
22 interface
24 uses
25 ctypes;
27 {$IFDEF FPC}
28 {$PACKRECORDS C}
29 {$ENDIF}
31 {$IF DEFINED(WINDOWS)}
32 {$IFDEF MPG123_WINDOZE_STATIC}
33 {$LINKLIB libmpg123.a}
34 {$ELSE}
35 {$DEFINE MPG123_DYNAMIC}
37 {$ENDIF}
38 {$ELSEIF DEFINED(UNIX)}
39 {$DEFINE MPG123_DYNAMIC}
40 {$LINKLIB libmpg123}
42 {$ELSE}
43 {$ERROR libmpg123 not supported on this platform. Fix it!}
44 {$ENDIF}
46 type
51 (* off_t = cint; *)
57 const
58 (** A macro to check at compile time which set of API functions to expect.
59 * This should be incremented at least each time a new symbol is added
60 * to the header.
61 *)
66 //TODO /** Defines needed for MS Visual Studio(tm) DLL builds.
67 //TODO * Every public function must be prefixed with MPG123_EXPORT. When building
68 //TODO * the DLL ensure to define BUILD_MPG123_DLL. This makes the function accessible
69 //TODO * for clients and includes it in the import library which is created together
70 //TODO * with the DLL. When consuming the DLL ensure to define LINK_MPG123_DLL which
71 //TODO * imports the functions from the DLL.
72 //TODO */
73 //TODO #ifdef BUILD_MPG123_DLL
74 //TODO /* The dll exports. */
75 //TODO #define MPG123_EXPORT __declspec(dllexport)
76 //TODO #else
77 //TODO #ifdef LINK_MPG123_DLL
78 //TODO /* The exe imports. */
79 //TODO #define MPG123_EXPORT __declspec(dllimport)
80 //TODO #else
81 //TODO /* Nothing on normal/UNIX builds */
82 //TODO #define MPG123_EXPORT
83 //TODO #endif
84 //TODO #endif
85 //TODO
86 //TODO /* This is for Visual Studio, so this header works as distributed in the binary downloads */
87 //TODO #if defined(_MSC_VER) && !defined(MPG123_DEF_SSIZE_T)
88 //TODO #define MPG123_DEF_SSIZE_T
89 //TODO #include <stddef.h>
90 //TODO typedef ptrdiff_t ssize_t;
91 //TODO #endif
92 //TODO
93 //TODO #ifndef MPG123_NO_CONFIGURE /* Enable use of this file without configure. */
94 //TODO #include <stdlib.h>
95 //TODO #include <sys/types.h>
96 //TODO
97 //TODO /* Simplified large file handling.
98 //TODO I used to have a check here that prevents building for a library with conflicting large file setup
99 //TODO (application that uses 32 bit offsets with library that uses 64 bits).
100 //TODO While that was perfectly fine in an environment where there is one incarnation of the library,
101 //TODO it hurt GNU/Linux and Solaris systems with multilib where the distribution fails to provide the
102 //TODO correct header matching the 32 bit library (where large files need explicit support) or
103 //TODO the 64 bit library (where there is no distinction).
104 //TODO
105 //TODO New approach: When the app defines _FILE_OFFSET_BITS, it wants non-default large file support,
106 //TODO and thus functions with added suffix (mpg123_open_64).
107 //TODO Any mismatch will be caught at link time because of the _FILE_OFFSET_BITS setting used when
108 //TODO building libmpg123. Plus, there's dual mode large file support in mpg123 since 1.12 now.
109 //TODO Link failure is not the expected outcome of any half-sane usage anymore.
110 //TODO
111 //TODO More complication: What about client code defining _LARGEFILE64_SOURCE? It might want direct access to the _64 functions, along with the ones without suffix. Well, that's possible now via defining MPG123_NO_LARGENAME and MPG123_LARGESUFFIX, respectively, for disabling or enforcing the suffix names.
112 //TODO */
113 //TODO
114 //TODO /*
115 //TODO Now, the renaming of large file aware functions.
116 //TODO By default, it appends underscore _FILE_OFFSET_BITS (so, mpg123_seek_64 for mpg123_seek), if _FILE_OFFSET_BITS is defined. You can force a different suffix via MPG123_LARGESUFFIX (that must include the underscore), or you can just disable the whole mess by defining MPG123_NO_LARGENAME.
117 //TODO */
118 //TODO #if (!defined MPG123_NO_LARGENAME) && ((defined _FILE_OFFSET_BITS) || (defined MPG123_LARGESUFFIX))
119 //TODO
120 //TODO /* Need some trickery to concatenate the value(s) of the given macro(s). */
121 //TODO #define MPG123_MACROCAT_REALLY(a, b) a ## b
122 //TODO #define MPG123_MACROCAT(a, b) MPG123_MACROCAT_REALLY(a, b)
123 //TODO #ifndef MPG123_LARGESUFFIX
124 //TODO #define MPG123_LARGESUFFIX MPG123_MACROCAT(_, _FILE_OFFSET_BITS)
125 //TODO #endif
126 //TODO #define MPG123_LARGENAME(func) MPG123_MACROCAT(func, MPG123_LARGESUFFIX)
127 //TODO
128 //TODO #define mpg123_open MPG123_LARGENAME(mpg123_open)
129 //TODO #define mpg123_open_fd MPG123_LARGENAME(mpg123_open_fd)
130 //TODO #define mpg123_open_handle MPG123_LARGENAME(mpg123_open_handle)
131 //TODO #define mpg123_framebyframe_decode MPG123_LARGENAME(mpg123_framebyframe_decode)
132 //TODO #define mpg123_decode_frame MPG123_LARGENAME(mpg123_decode_frame)
133 //TODO #define mpg123_tell MPG123_LARGENAME(mpg123_tell)
134 //TODO #define mpg123_tellframe MPG123_LARGENAME(mpg123_tellframe)
135 //TODO #define mpg123_tell_stream MPG123_LARGENAME(mpg123_tell_stream)
136 //TODO #define mpg123_seek MPG123_LARGENAME(mpg123_seek)
137 //TODO #define mpg123_feedseek MPG123_LARGENAME(mpg123_feedseek)
138 //TODO #define mpg123_seek_frame MPG123_LARGENAME(mpg123_seek_frame)
139 //TODO #define mpg123_timeframe MPG123_LARGENAME(mpg123_timeframe)
140 //TODO #define mpg123_index MPG123_LARGENAME(mpg123_index)
141 //TODO #define mpg123_set_index MPG123_LARGENAME(mpg123_set_index)
142 //TODO #define mpg123_position MPG123_LARGENAME(mpg123_position)
143 //TODO #define mpg123_length MPG123_LARGENAME(mpg123_length)
144 //TODO #define mpg123_framelength MPG123_LARGENAME(mpg123_framelength)
145 //TODO #define mpg123_set_filesize MPG123_LARGENAME(mpg123_set_filesize)
146 //TODO #define mpg123_replace_reader MPG123_LARGENAME(mpg123_replace_reader)
147 //TODO #define mpg123_replace_reader_handle MPG123_LARGENAME(mpg123_replace_reader_handle)
148 //TODO #define mpg123_framepos MPG123_LARGENAME(mpg123_framepos)
149 //TODO
150 //TODO #endif /* largefile hackery */
151 //TODO
152 //TODO #endif /* MPG123_NO_CONFIGURE */
154 (** \defgroup mpg123_init mpg123 library and handle setup
155 *
156 * Functions to initialise and shutdown the mpg123 library and handles.
157 * The parameters of handles have workable defaults, you only have to tune them when you want to tune something;-)
158 * Tip: Use a RVA setting...
159 *
160 * @{
161 *)
163 (** Opaque structure for the libmpg123 decoder handle. *)
164 type
169 (** Opaque structure for the libmpg123 decoder handle.
170 * Most functions take a pointer to a mpg123_handle as first argument and operate on its data in an object-oriented manner.
171 *)
172 type
176 (** Function to initialise the mpg123 library.
177 * This function is not thread-safe. Call it exactly once per process, before any other (possibly threaded) work with the library.
178 *
179 * \return MPG123_OK if successful, otherwise an error number.
180 *)
183 (** Function to close down the mpg123 library.
184 * This function is not thread-safe. Call it exactly once per process, before any other (possibly threaded) work with the library. *)
187 (** Create a handle with optional choice of decoder (named by a string, see mpg123_decoders() or mpg123_supported_decoders()).
188 * and optional retrieval of an error code to feed to mpg123_plain_strerror().
189 * Optional means: Any of or both the parameters may be NULL.
190 *
191 * \param decoder optional choice of decoder variant (NULL for default)
192 * \param error optional address to store error codes
193 * \return Non-NULL pointer to fresh handle when successful.
194 *)
195 function mpg123_new(const decoder: pchar; error: pcint): pmpg123_handle; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
197 (** Delete handle, mh is either a valid mpg123 handle or NULL.
198 * \param mh handle
199 *)
200 procedure mpg123_delete(mh: pmpg123_handle); cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
202 (** Enumeration of the parameters types that it is possible to set/get. *)
203 type
205 const
206 MPG123_VERBOSE = 0; (**< set verbosity value for enabling messages to stderr, >= 0 makes sense (integer) *)
217 MPG123_OUTSCALE = 11; (**< the scale for output samples (amplitude - integer or float according to mpg123 output format, normally integer) *)
218 MPG123_TIMEOUT = 12; (**< timeout for reading from a stream (not supported on win32, integer) *)
220 MPG123_RESYNC_LIMIT = 14; (**< Try resync on frame parsing for that many bytes or until end of stream (<0 ... integer). This can enlarge the limit for skipping junk on beginning, too (but not reduce it). *)
221 MPG123_INDEX_SIZE = 15; (**< Set the frame index size (if supported). Values <0 mean that the index is allowed to grow dynamically in these steps (in positive direction, of course) -- Use this when you really want a full index with every individual frame. *)
222 MPG123_PREFRAMES = 16; (**< Decode/ignore that many frames in advance for layer 3. This is needed to fill bit reservoir after seeking, for example (but also at least one frame in advance is needed to have all "normal" data for layer 3). Give a positive integer value, please.*)
223 MPG123_FEEDPOOL = 17; (**< For feeder mode, keep that many buffers in a pool to avoid frequent malloc/free. The pool is allocated on mpg123_open_feed(). If you change this parameter afterwards, you can trigger growth and shrinkage during decoding. The default value could change any time. If you care about this, then set it. (integer) *)
224 MPG123_FEEDBUFFER = 18; (**< Minimal size of one internal feeder buffer, again, the default value is subject to change. (integer) *)
226 (** Flag bits for MPG123_FLAGS, use the usual binary or to combine. *)
227 type
229 const
230 MPG123_FORCE_MONO = $7; (**< 0111 Force some mono mode: This is a test bitmask for seeing if any mono forcing is active. *)
237 MPG123_GAPLESS = $40; (**< 01000000 Enable gapless decoding (default on if libmpg123 has support). *)
239 MPG123_SEEKBUFFER = $100; (**< 000100000000 Enable small buffer on non-seekable streams to allow some peek-ahead (for better MPEG sync). *)
240 MPG123_FUZZY = $200; (**< 001000000000 Enable fuzzy seeks (guessing byte offsets or using approximate seek points from Xing TOC) *)
241 MPG123_FORCE_FLOAT = $400; (**< 010000000000 Force floating point output (32 or 64 bits depends on mpg123 internal precision). *)
242 MPG123_PLAIN_ID3TEXT = $800; (**< 100000000000 Do not translate ID3 text data to UTF-8. ID3 strings will contain the raw text data, with the first byte containing the ID3 encoding code. *)
243 MPG123_IGNORE_STREAMLENGTH = $1000; (**< 1000000000000 Ignore any stream length information contained in the stream, which can be contained in a 'TLEN' frame of an ID3v2 tag or a Xing tag *)
245 MPG123_IGNORE_INFOFRAME = $4000; (**< 100 0000 0000 0000 Do not parse the LAME/Xing info frame, treat it as normal MPEG data. *)
246 MPG123_AUTO_RESAMPLE = $8000; (**< 1000 0000 0000 0000 Allow automatic internal resampling of any kind (default on if supported). Especially when going lowlevel with replacing output buffer, you might want to unset this flag. Setting MPG123_DOWNSAMPLE or MPG123_FORCE_RATE will override this. *)
249 * the stream in order to probe
250 * the stream length and search for the id3v1 field. This also means
251 * the file size is unknown unless set using mpg123_set_filesize() and
252 * the stream is assumed as non-seekable unless overridden.
253 *)
257 (** choices for MPG123_RVA *)
258 type
260 const
266 (** Set a specific parameter, for a specific mpg123_handle, using a parameter
267 * type key chosen from the mpg123_parms enumeration, to the specified value.
268 * \param mh handle
269 * \param type parameter choice
270 * \param value integer value
271 * \param fvalue floating point value
272 * \return MPG123_OK on success
273 *)
274 function mpg123_param(mh: pmpg123_handle; _type: mpg123_parms; value: clong; fvalue: cdouble): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
276 (** Get a specific parameter, for a specific mpg123_handle.
277 * See the mpg123_parms enumeration for a list of available parameters.
278 * \param mh handle
279 * \param type parameter choice
280 * \param value integer value return address
281 * \param fvalue floating point value return address
282 * \return MPG123_OK on success
283 *)
284 function mpg123_getparam(mh: pmpg123_handle; _type: mpg123_parms; val: pclong; fval: pcdouble): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
286 (** Feature set available for query with mpg123_feature. *)
287 type
289 const
290 MPG123_FEATURE_ABI_UTF8OPEN = 0; (**< mpg123 expects path names to be given in UTF-8 encoding instead of plain native. *)
306 (** Query libmpg123 features.
307 * \param key feature selection
308 * \return 1 for success, 0 for unimplemented functions
309 *)
310 function mpg123_feature(const key: mpg123_feature_set): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
312 (* @} *)
314 (** \defgroup mpg123_error mpg123 error handling
315 *
316 * Functions to get text version of the error numbers and an enumeration
317 * of the error codes returned by libmpg123.
318 *
319 * Most functions operating on a mpg123_handle simply return MPG123_OK (0)
320 * on success and MPG123_ERR (-1) on failure, setting the internal error
321 * variable of the handle to the specific error code. If there was not a valid
322 * (non-NULL) handle provided to a function operating on one, MPG123_BAD_HANDLE
323 * may be returned if this can not be confused with a valid positive return
324 * value.
325 * Meaning: A function expected to return positive integers on success will
326 * always indicate error or a special condition by returning a negative one.
327 *
328 * Decoding/seek functions may also return message codes MPG123_DONE,
329 * MPG123_NEW_FORMAT and MPG123_NEED_MORE (all negative, see below on how to
330 * react). Note that calls to those can be nested, so generally watch out
331 * for these codes after initial handle setup.
332 * Especially any function that needs information about the current stream
333 * to work will try to at least parse the beginning if that did not happen
334 * yet.
335 *
336 * On a function that is supposed to return MPG123_OK on success and
337 * MPG123_ERR on failure, make sure you check for != MPG123_OK, not
338 * == MPG123_ERR, as the error code could get more specific in future,
339 * or there is just a special message from a decoding routine as indicated
340 * above.
341 *
342 * @{
343 *)
345 (** Enumeration of the message and error codes and returned by libmpg123 functions. *)
346 type
348 const
350 MPG123_NEW_FORMAT = -11; (**< Message: Output format will be different on next call. Note that some libmpg123 versions between 1.4.3 and 1.8.0 insist on you calling mpg123_getformat() after getting this message code. Newer verisons behave like advertised: You have the chance to call mpg123_getformat(), but you can also just continue decoding and get your data. *)
351 MPG123_NEED_MORE = -10; (**< Message: For feed reader: "Feed me more!" (call mpg123_feed() or mpg123_decode() with some new input data). *)
395 MPG123_LFS_OVERFLOW = 42; (**< Offset value overflow during translation of large file API calls -- your client program cannot handle that large file. *)
398 (** An enum over all sample types possibly known to mpg123.
399 * The values are designed as bit flags to allow bitmasking for encoding families.
400 *
401 * Note that (your build of) libmpg123 does not necessarily support all these.
402 * Usually, you can expect the 8bit encodings and signed 16 bit.
403 * Also 32bit float will be usual beginning with mpg123-1.7.0 .
404 * What you should bear in mind is that (SSE, etc) optimized routines may be absent
405 * for some formats. We do have SSE for 16, 32 bit and float, though.
406 * 24 bit integer is done via postprocessing of 32 bit output -- just cutting
407 * the last byte, no rounding, even. If you want better, do it yourself.
408 *
409 * All formats are in native byte order. If you need different endinaness, you
410 * can simply postprocess the output buffers (libmpg123 wouldn't do anything else).
411 * mpg123_encsize() can be helpful there.
412 *)
414 type
416 const
423 MPG123_ENC_SIGNED_16 = (MPG123_ENC_16 or MPG123_ENC_SIGNED or $10); (* 1101 0000 signed 16 bit *)
429 MPG123_ENC_SIGNED_32 = MPG123_ENC_32 or MPG123_ENC_SIGNED or $1000; (* 0001 0001 1000 0000 signed 32 bit *)
431 MPG123_ENC_SIGNED_24 = MPG123_ENC_24 or MPG123_ENC_SIGNED or $1000; (* 0101 0000 1000 0000 signed 24 bit *)
441 (** Look up error strings given integer code.
442 * \param errcode integer error code
443 * \return string describing what that error error code means
444 *)
445 function mpg123_plain_strerror(errcode: cint): pchar; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
447 (** Give string describing what error has occured in the context of handle mh.
448 * When a function operating on an mpg123 handle returns MPG123_ERR, you should check for the actual reason via
449 * char *errmsg = mpg123_strerror(mh)
450 * This function will catch mh == NULL and return the message for MPG123_BAD_HANDLE.
451 * \param mh handle
452 * \return error message
453 *)
454 function mpg123_strerror(mh: pmpg123_handle): pchar; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
456 (** Return the plain errcode intead of a string.
457 * \param mh handle
458 * \return error code recorded in handle or MPG123_BAD_HANDLE
459 *)
460 function mpg123_errcode(mh: pmpg123_handle): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
462 (*@}*)
464 (** \defgroup mpg123_decoder mpg123 decoder selection
465 *
466 * Functions to list and select the available decoders.
467 * Perhaps the most prominent feature of mpg123: You have several (optimized) decoders to choose from (on x86 and PPC (MacOS) systems, that is).
468 *
469 * @{
470 *)
472 (** Get available decoder list.
473 * \return NULL-terminated array of generally available decoder names (plain 8bit ASCII)
474 *)
477 (** Get supported decoder list.
478 * \return NULL-terminated array of the decoders supported by the CPU (plain 8bit ASCII)
479 *)
480 function mpg123_supported_decoders(): ppchar; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
482 (** Set the active decoder.
483 * \param mh handle
484 * \param decoder_name name of decoder
485 * \return MPG123_OK on success
486 *)
487 function mpg123_decoder(mh: pmpg123_handle; const decoder_name: pchar): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
489 (** Get the currently active decoder name.
490 * The active decoder engine can vary depening on output constraints,
491 * mostly non-resampling, integer output is accelerated via 3DNow & Co. but for
492 * other modes a fallback engine kicks in.
493 * Note that this can return a decoder that is ony active in the hidden and not
494 * available as decoder choice from the outside.
495 * \param mh handle
496 * \return The decoder name or NULL on error.
497 *)
498 function mpg123_current_decoder(mh: pmpg123_handle): pchar; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
500 (*@}*)
502 (** \defgroup mpg123_output mpg123 output audio format
503 *
504 * Functions to get and select the format of the decoded audio.
505 *
506 * Before you dive in, please be warned that you might get confused by this. This seems to happen a lot, therefore I am trying to explain in advance.
507 *
508 * The mpg123 library decides what output format to use when encountering the first frame in a stream, or actually any frame that is still valid but differs from the frames before in the prompted output format. At such a deciding point, an internal table of allowed encodings, sampling rates and channel setups is consulted. According to this table, an output format is chosen and the decoding engine set up accordingly (including optimized routines for different output formats). This might seem unusual but it just follows from the non-existence of "MPEG audio files" with defined overall properties. There are streams, streams are concatenations of (semi) independent frames. We store streams on disk and call them "MPEG audio files", but that does not change their nature as the decoder is concerned (the LAME/Xing header for gapless decoding makes things interesting again).
509 *
510 * To get to the point: What you do with mpg123_format() and friends is to fill the internal table of allowed formats before it is used. That includes removing support for some formats or adding your forced sample rate (see MPG123_FORCE_RATE) that will be used with the crude internal resampler. Also keep in mind that the sample encoding is just a question of choice -- the MPEG frames do only indicate their native sampling rate and channel count. If you want to decode to integer or float samples, 8 or 16 bit ... that is your decision. In a "clean" world, libmpg123 would always decode to 32 bit float and let you handle any sample conversion. But there are optimized routines that work faster by directly decoding to the desired encoding / accuracy. We prefer efficiency over conceptual tidyness.
511 *
512 * People often start out thinking that mpg123_format() should change the actual decoding format on the fly. That is wrong. It only has effect on the next natural change of output format, when libmpg123 will consult its format table again. To make life easier, you might want to call mpg123_format_none() before any thing else and then just allow one desired encoding and a limited set of sample rates / channel choices that you actually intend to deal with. You can force libmpg123 to decode everything to 44100 KHz, stereo, 16 bit integer ... it will duplicate mono channels and even do resampling if needed (unless that feature is disabled in the build, same with some encodings). But I have to stress that the resampling of libmpg123 is very crude and doesn't even contain any kind of "proper" interpolation.
513 *
514 * In any case, watch out for MPG123_NEW_FORMAT as return message from decoding routines and call mpg123_getformat() to get the currently active output format.
515 *
516 * @{
517 *)
519 (** They can be combined into one number (3) to indicate mono and stereo... *)
520 type
522 const
526 (** An array of supported standard sample rates
527 * These are possible native sample rates of MPEG audio files.
528 * You can still force mpg123 to resample to a different one, but by default you will only get audio in one of these samplings.
529 * \param list Store a pointer to the sample rates array there.
530 * \param number Store the number of sample rates there. *)
531 procedure mpg123_rates(const list: ppclong; number: pcsize_t); cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
533 (** An array of supported audio encodings.
534 * An audio encoding is one of the fully qualified members of mpg123_enc_enum (MPG123_ENC_SIGNED_16, not MPG123_SIGNED).
535 * \param list Store a pointer to the encodings array there.
536 * \param number Store the number of encodings there. *)
537 procedure mpg123_encodings(const list: ppcint; number: pcsize_t); cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
539 (** Return the size (in bytes) of one mono sample of the named encoding.
540 * \param encoding The encoding value to analyze.
541 * \return positive size of encoding in bytes, 0 on invalid encoding. *)
542 function mpg123_encsize(encoding: cint): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
544 (** Configure a mpg123 handle to accept no output format at all,
545 * use before specifying supported formats with mpg123_format
546 * \param mh handle
547 * \return MPG123_OK on success
548 *)
549 function mpg123_format_none(mh: pmpg123_handle): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
551 (** Configure mpg123 handle to accept all formats
552 * (also any custom rate you may set) -- this is default.
553 * \param mh handle
554 * \return MPG123_OK on success
555 *)
556 function mpg123_format_all(mh: pmpg123_handle): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
558 (** Set the audio format support of a mpg123_handle in detail:
559 * \param mh handle
560 * \param rate The sample rate value (in Hertz).
561 * \param channels A combination of MPG123_STEREO and MPG123_MONO.
562 * \param encodings A combination of accepted encodings for rate and channels, p.ex MPG123_ENC_SIGNED16 | MPG123_ENC_ULAW_8 (or 0 for no support). Please note that some encodings may not be supported in the library build and thus will be ignored here.
563 * \return MPG123_OK on success, MPG123_ERR if there was an error. *)
564 function mpg123_format(mh: pmpg123_handle; rate: clong; channels: cint; encoding: cint): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
566 (** Check to see if a specific format at a specific rate is supported
567 * by mpg123_handle.
568 * \param mh handle
569 * \param rate sampling rate
570 * \param encoding encoding
571 * \return 0 for no support (that includes invalid parameters), MPG123_STEREO,
572 * MPG123_MONO or MPG123_STEREO|MPG123_MONO. *)
573 function mpg123_format_support(mh: pmpg123_handle; rate: clong; encoding: cint): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
575 (** Get the current output format written to the addresses given.
576 * If the stream is freshly loaded, this will try to parse enough
577 * of it to give you the format to come. This clears the flag that
578 * would otherwise make the first decoding call return
579 * MPG123_NEW_FORMAT.
580 * \param mh handle
581 * \param rate sampling rate return address
582 * \param channels channel count return address
583 * \param encoding encoding return address
584 * \return MPG123_OK on success
585 *)
586 function mpg123_getformat(mh: pmpg123_handle; rate: pclong; channels: pcint; encoding: pcint): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
588 (** Get the current output format written to the addresses given.
589 * This differs from plain mpg123_getformat() in that you can choose
590 * _not_ to clear the flag that would trigger the next decoding call
591 * to return MPG123_NEW_FORMAT in case of a new format arriving.
592 * \param mh handle
593 * \param rate sampling rate return address
594 * \param channels channel count return address
595 * \param encoding encoding return address
596 * \param clear_flag if true, clear internal format flag
597 * \return MPG123_OK on success
598 *)
599 function mpg123_getformat2(mh: pmpg123_handle; rate: pclong; channels: pcint; encoding: pcint; clear_flag: cint): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
601 (*@}*)
603 (** \defgroup mpg123_input mpg123 file input and decoding
604 *
605 * Functions for input bitstream and decoding operations.
606 * Decoding/seek functions may also return message codes MPG123_DONE, MPG123_NEW_FORMAT and MPG123_NEED_MORE (please read up on these on how to react!).
607 * @{
608 *)
610 (* reading samples / triggering decoding, possible return values: *)
611 (** Enumeration of the error codes returned by libmpg123 functions. *)
613 (** Open and prepare to decode the specified file by filesystem path.
614 * This does not open HTTP urls; libmpg123 contains no networking code.
615 * If you want to decode internet streams, use mpg123_open_fd() or mpg123_open_feed().
616 * \param mh handle
617 * \param path filesystem path
618 * \return MPG123_OK on success
619 *)
620 function mpg123_open(mh: pmpg123_handle; const path: pchar): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
622 (** Use an already opened file descriptor as the bitstream input
623 * mpg123_close() will _not_ close the file descriptor.
624 * \param mh handle
625 * \param fd file descriptor
626 * \return MPG123_OK on success
627 *)
628 function mpg123_open_fd(mh: pmpg123_handle; fd: cint): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
630 (** Use an opaque handle as bitstream input. This works only with the
631 * replaced I/O from mpg123_replace_reader_handle()!
632 * mpg123_close() will call the cleanup callback for your handle (if you gave one).
633 * \param mh handle
634 * \param iohandle your handle
635 * \return MPG123_OK on success
636 *)
637 function mpg123_open_handle(mh: pmpg123_handle; iohandle: pointer): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
639 (** Open a new bitstream and prepare for direct feeding
640 * This works together with mpg123_decode(); you are responsible for reading and feeding the input bitstream.
641 * \param mh handle
642 * \return MPG123_OK on success
643 *)
644 function mpg123_open_feed(mh: pmpg123_handle): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
646 (** Closes the source, if libmpg123 opened it.
647 * \param mh handle
648 * \return MPG123_OK on success
649 *)
650 function mpg123_close(mh: pmpg123_handle): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
652 (** Read from stream and decode up to outmemsize bytes.
653 * \param mh handle
654 * \param outmemory address of output buffer to write to
655 * \param outmemsize maximum number of bytes to write
656 * \param done address to store the number of actually decoded bytes to
657 * \return MPG123_OK or error/message code
658 *)
659 function mpg123_read(mh: pmpg123_handle; outmemory: pcuchar; outmemsize: csize_t; done: pcsize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
661 (** Feed data for a stream that has been opened with mpg123_open_feed().
662 * It's give and take: You provide the bytestream, mpg123 gives you the decoded samples.
663 * \param mh handle
664 * \param in input buffer
665 * \param size number of input bytes
666 * \return MPG123_OK or error/message code.
667 *)
668 function mpg123_feed(mh: pmpg123_handle; const _in: pcuchar; size: csize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
670 (** Decode MPEG Audio from inmemory to outmemory.
671 * This is very close to a drop-in replacement for old mpglib.
672 * When you give zero-sized output buffer the input will be parsed until
673 * decoded data is available. This enables you to get MPG123_NEW_FORMAT (and query it)
674 * without taking decoded data.
675 * Think of this function being the union of mpg123_read() and mpg123_feed() (which it actually is, sort of;-).
676 * You can actually always decide if you want those specialized functions in separate steps or one call this one here.
677 * \param mh handle
678 * \param inmemory input buffer
679 * \param inmemsize number of input bytes
680 * \param outmemory output buffer
681 * \param outmemsize maximum number of output bytes
682 * \param done address to store the number of actually decoded bytes to
683 * \return error/message code (watch out especially for MPG123_NEED_MORE)
684 *)
685 function mpg123_decode(mh: pmpg123_handle; const inmemory: pcuchar ; inmemsize: csize_t; outmemory: pcuchar; outmemsize: csize_t; done: pcsize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
687 (** Decode next MPEG frame to internal buffer
688 * or read a frame and return after setting a new format.
689 * \param mh handle
690 * \param num current frame offset gets stored there
691 * \param audio This pointer is set to the internal buffer to read the decoded audio from.
692 * \param bytes number of output bytes ready in the buffer
693 * \return MPG123_OK or error/message code
694 *)
695 function mpg123_decode_frame(mh: pmpg123_handle; num: poff_t; audio: ppcuchar; bytes: pcsize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
697 (** Decode current MPEG frame to internal buffer.
698 * Warning: This is experimental API that might change in future releases!
699 * Please watch mpg123 development closely when using it.
700 * \param mh handle
701 * \param num last frame offset gets stored there
702 * \param audio this pointer is set to the internal buffer to read the decoded audio from.
703 * \param bytes number of output bytes ready in the buffer
704 * \return MPG123_OK or error/message code
705 *)
706 function mpg123_framebyframe_decode(mh: pmpg123_handle; num: poff_t; audio: ppcuchar; bytes: pcsize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
708 (** Find, read and parse the next mp3 frame
709 * Warning: This is experimental API that might change in future releases!
710 * Please watch mpg123 development closely when using it.
711 * \param mh handle
712 * \return MPG123_OK or error/message code
713 *)
714 function mpg123_framebyframe_next(mh: pmpg123_handle): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
716 (** Get access to the raw input data for the last parsed frame.
717 * This gives you a direct look (and write access) to the frame body data.
718 * Together with the raw header, you can reconstruct the whole raw MPEG stream without junk and meta data, or play games by actually modifying the frame body data before decoding this frame (mpg123_framebyframe_decode()).
719 * A more sane use would be to use this for CRC checking (see mpg123_info() and MPG123_CRC), the first two bytes of the body make up the CRC16 checksum, if present.
720 * You can provide NULL for a parameter pointer when you are not interested in the value.
721 *
722 * \param mh handle
723 * \param header the 4-byte MPEG header
724 * \param bodydata pointer to the frame body stored in the handle (without the header)
725 * \param bodybytes size of frame body in bytes (without the header)
726 * \return MPG123_OK if there was a yet un-decoded frame to get the
727 * data from, MPG123_BAD_HANDLE or MPG123_ERR otherwise (without further
728 * explanation, the error state of the mpg123_handle is not modified by
729 * this function).
730 *)
731 function mpg123_framedata(mh: pmpg123_handle; header: pculong; bodydata: ppcuchar; bodybytes: pcsize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
733 (** Get the input position (byte offset in stream) of the last parsed frame.
734 * This can be used for external seek index building, for example.
735 * It just returns the internally stored offset, regardless of validity -- you ensure that a valid frame has been parsed before! *)
736 function mpg123_framepos(mh: pmpg123_handle): off_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
738 (*@}*)
740 (** \defgroup mpg123_seek mpg123 position and seeking
741 *
742 * Functions querying and manipulating position in the decoded audio bitstream.
743 * The position is measured in decoded audio samples, or MPEG frame offset for the specific functions.
744 * 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;-)
745 * The general usage is modelled after stdlib's ftell() and fseek().
746 * 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:
747 * - SEEK_SET: set position to (or near to) specified offset
748 * - SEEK_CUR: change position by offset from now
749 * - SEEK_END: set position to offset from end
750 *
751 * Note that sample-accurate seek only works when gapless support has been enabled at compile time; seek is frame-accurate otherwise.
752 * 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)!
753 * Short: When you care about the sample position, don't mess with those parameters;-)
754 * Also, seeking is not guaranteed to work for all streams (underlying stream may not support it).
755 * And yet another caveat: If the stream is concatenated out of differing pieces (Frankenstein stream), seeking may suffer, too.
756 *
757 * @{
758 *)
760 (** Returns the current position in samples.
761 * On the next successful read, you'd get that sample.
762 * \param mh handle
763 * \return sample offset or MPG123_ERR (null handle)
764 *)
765 function mpg123_tell(mh: pmpg123_handle): off_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
767 (** Returns the frame number that the next read will give you data from.
768 * \param mh handle
769 * \return frame offset or MPG123_ERR (null handle)
770 *)
771 function mpg123_tellframe(mh: pmpg123_handle): off_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
773 (** Returns the current byte offset in the input stream.
774 * \param mh handle
775 * \return byte offset or MPG123_ERR (null handle)
776 *)
777 function mpg123_tell_stream(mh: pmpg123_handle): off_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
779 (** Seek to a desired sample offset.
780 * Usage is modelled afer the standard lseek().
781 * \param mh handle
782 * \param sampleoff offset in PCM samples
783 * \param whence one of SEEK_SET, SEEK_CUR or SEEK_END
784 * \return The resulting offset >= 0 or error/message code
785 *)
786 function mpg123_seek(mh: pmpg123_handle; sampleoff: off_t; whence: cint): off_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
788 (** Seek to a desired sample offset in data feeding mode.
789 * 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.
790 * \param mh handle
791 * \param sampleoff offset in PCM samples
792 * \param whence one of SEEK_SET, SEEK_CUR or SEEK_END
793 * \param input_offset The position it expects to be at the
794 * next time data is fed to mpg123_decode().
795 * \return The resulting offset >= 0 or error/message code *)
796 function mpg123_feedseek(mh: pmpg123_handle; sampleoff: off_t; whence: cint; input_offset: poff_t): off_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
798 (** Seek to a desired MPEG frame offset.
799 * Usage is modelled afer the standard lseek().
800 * \param mh handle
801 * \param frameoff offset in MPEG frames
802 * \param whence one of SEEK_SET, SEEK_CUR or SEEK_END
803 * \return The resulting offset >= 0 or error/message code *)
804 function mpg123_seek_frame(mh: pmpg123_handle; frameoff: off_t; whence: cint): off_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
806 (** Return a MPEG frame offset corresponding to an offset in seconds.
807 * 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.
808 * \return frame offset >= 0 or error/message code *)
809 function mpg123_timeframe(mh: pmpg123_handle; sec: cdouble): off_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
811 (** Give access to the frame index table that is managed for seeking.
812 * You are asked not to modify the values... Use mpg123_set_index to set the
813 * seek index
814 * \param mh handle
815 * \param offsets pointer to the index array
816 * \param step one index byte offset advances this many MPEG frames
817 * \param fill number of recorded index offsets; size of the array
818 * \return MPG123_OK on success
819 *)
820 function mpg123_index(mh: pmpg123_handle; offsets: ppoff_t; step: poff_t; fill: pcsize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
822 (** Set the frame index table
823 * Setting offsets to NULL and fill > 0 will allocate fill entries. Setting offsets
824 * to NULL and fill to 0 will clear the index and free the allocated memory used by the index.
825 * \param mh handle
826 * \param offsets pointer to the index array
827 * \param step one index byte offset advances this many MPEG frames
828 * \param fill number of recorded index offsets; size of the array
829 * \return MPG123_OK on success
830 *)
831 function mpg123_set_index(mh: pmpg123_handle; offsets: poff_t; step: off_t; fill: csize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
833 (** An old crutch to keep old mpg123 binaries happy.
834 * WARNING: This function is there only to avoid runtime linking errors with
835 * standalone mpg123 before version 1.23.0 (if you strangely update the
836 * library but not the end-user program) and actually is broken
837 * for various cases (p.ex. 24 bit output). Do never use. It might eventually
838 * be purged from the library.
839 *)
840 function mpg123_position( mh: pmpg123_handle; frame_offset: off_t; buffered_bytes: off_t; current_frame: poff_t; frames_left: poff_t; current_seconds: pcdouble; seconds_left: pcdouble): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
842 (*@}*)
844 (** \defgroup mpg123_voleq mpg123 volume and equalizer
845 *
846 * @{
847 *)
849 (** another channel enumeration, for left/right choice *)
850 type
852 const
857 (** Set the 32 Band Audio Equalizer settings.
858 * \param mh handle
859 * \param channel Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for both.
860 * \param band The equaliser band to change (from 0 to 31)
861 * \param val The (linear) adjustment factor.
862 * \return MPG123_OK on success
863 *)
864 function mpg123_eq(mh: pmpg123_handle; channel: mpg123_channels; band: cint; val: cdouble): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
866 (** Get the 32 Band Audio Equalizer settings.
867 * \param mh handle
868 * \param channel Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for (arithmetic mean of) both.
869 * \param band The equaliser band to change (from 0 to 31)
870 * \return The (linear) adjustment factor (zero for pad parameters) *)
871 function mpg123_geteq(mh: pmpg123_handle; channel: mpg123_channels; band: cint): cdouble; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
873 (** Reset the 32 Band Audio Equalizer settings to flat
874 * \param mh handle
875 * \return MPG123_OK on success
876 *)
877 function mpg123_reset_eq(mh: pmpg123_handle): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
879 (** Set the absolute output volume including the RVA setting,
880 * vol<0 just applies (a possibly changed) RVA setting.
881 * \param mh handle
882 * \param vol volume value (linear factor)
883 * \return MPG123_OK on success
884 *)
885 function mpg123_volume(mh: pmpg123_handle; vol: cdouble): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
887 (** Adjust output volume including the RVA setting by chosen amount
888 * \param mh handle
889 * \param change volume value (linear factor increment)
890 * \return MPG123_OK on success
891 *)
892 function mpg123_volume_change(mh: pmpg123_handle; change: cdouble): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
894 (** Return current volume setting, the actual value due to RVA, and the RVA
895 * adjustment itself. It's all as double float value to abstract the sample
896 * format. The volume values are linear factors / amplitudes (not percent)
897 * and the RVA value is in decibels.
898 * \param mh handle
899 * \param base return address for base volume (linear factor)
900 * \param really return address for actual volume (linear factor)
901 * \param rva_db return address for RVA value (decibels)
902 * \return MPG123_OK on success
903 *)
904 function mpg123_getvolume(mh: pmpg123_handle; base: pcdouble; really: pcdouble; rva_db: pcdouble): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
906 (* TODO: Set some preamp in addition / to replace internal RVA handling? *)
908 (*@}*)
910 (** \defgroup mpg123_status mpg123 status and information
911 *
912 * @{
913 *)
915 (** Enumeration of the mode types of Variable Bitrate *)
916 type
918 const
923 (** Enumeration of the MPEG Versions *)
924 type
926 const
932 (** Enumeration of the MPEG Audio mode.
933 * Only the mono mode has 1 channel, the others have 2 channels. *)
934 type
936 const
943 (** Enumeration of the MPEG Audio flag bits *)
944 type
946 const
952 (** Data structure for storing information about a frame of MPEG Audio *)
953 type
962 flags: mpg123_flags_type; (**< MPEG Audio flag bits. Just now I realize that it should be declared as int, not enum. It's a bitwise combination of the enum values. *)
969 (** Get frame information about the MPEG audio bitstream and store it in a mpg123_frameinfo structure.
970 * \param mh handle
971 * \param mi address of existing frameinfo structure to write to
972 * \return MPG123_OK on success
973 *)
974 function mpg123_info(mh: pmpg123_handle; mi: pmpg123_frameinfo): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
976 (** Get the safe output buffer size for all cases
977 * (when you want to replace the internal buffer)
978 * \return safe buffer size
979 *)
980 function mpg123_safe_buffer(): csize_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
982 (** Make a full parsing scan of each frame in the file. ID3 tags are found. An
983 * accurate length value is stored. Seek index will be filled. A seek back to
984 * current position is performed. At all, this function refuses work when
985 * stream is not seekable.
986 * \param mh handle
987 * \return MPG123_OK on success
988 *)
989 function mpg123_scan(mh: pmpg123_handle): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
991 (** Return, if possible, the full (expected) length of current track in frames.
992 * \param mh handle
993 * \return length >= 0 or MPG123_ERR if there is no length guess possible.
994 *)
995 function mpg123_framelength(mh: pmpg123_handle): off_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
997 (** Return, if possible, the full (expected) length of current track in samples.
998 * \param mh handle
999 * \return length >= 0 or MPG123_ERR if there is no length guess possible.
1000 *)
1001 function mpg123_length(mh: pmpg123_handle): off_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1003 (** Override the value for file size in bytes.
1004 * Useful for getting sensible track length values in feed mode or for HTTP streams.
1005 * \param mh handle
1006 * \param size file size in bytes
1007 * \return MPG123_OK on success
1008 *)
1009 function mpg123_set_filesize(mh: pmpg123_handle; size: off_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1011 (** Get MPEG frame duration in seconds.
1012 * \param mh handle
1013 * \return frame duration in seconds, <0 on error
1014 *)
1015 function mpg123_tpf(mh: pmpg123_handle): cdouble; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1017 (** Get MPEG frame duration in samples.
1018 * \param mh handle
1019 * \return samples per frame for the most recently parsed frame; <0 on errors
1020 *)
1021 function mpg123_spf(mh: pmpg123_handle): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1023 (** Get and reset the clip count.
1024 * \param mh handle
1025 * \return count of clipped samples
1026 *)
1027 function mpg123_clip(mh: pmpg123_handle): clong; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1029 (** The key values for state information from mpg123_getstate(). *)
1030 type
1032 const
1033 MPG123_ACCURATE = 1; (**< Query if positons are currently accurate (integer value, 0 if false, 1 if true). *)
1034 MPG123_BUFFERFILL = 2; (**< Get fill of internal (feed) input buffer as integer byte count returned as long and as double. An error is returned on integer overflow while converting to (signed) long, but the returned floating point value shold still be fine. *)
1035 MPG123_FRANKENSTEIN = 3; (**< Stream consists of carelessly stitched together files. Seeking may yield unexpected results (also with MPG123_ACCURATE, it may be confused). *)
1036 MPG123_FRESH_DECODER = 4; (**< Decoder structure has been updated, possibly indicating changed stream (integer value, 0 if false, 1 if true). Flag is cleared after retrieval. *)
1038 (** Get various current decoder/stream state information.
1039 * \param mh handle
1040 * \param key the key to identify the information to give.
1041 * \param val the address to return (long) integer values to
1042 * \param fval the address to return floating point values to
1043 * \return MPG123_OK on success
1044 *)
1045 function mpg123_getstate(mh: pmpg123_handle; key: mpg123_state; val: pclong; fval: pcdouble): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1047 (*@}*)
1049 (** \defgroup mpg123_metadata mpg123 metadata handling
1050 *
1051 * Functions to retrieve the metadata from MPEG Audio files and streams.
1052 * Also includes string handling functions.
1053 *
1054 * @{
1055 *)
1057 (** Data structure for storing strings in a safer way than a standard C-String.
1058 * Can also hold a number of null-terminated strings. *)
1059 type
1067 (** Create and allocate memory for a new mpg123_string
1068 * \param sb string handle (address of existing structure on your side)
1069 *)
1070 procedure mpg123_init_string(sb: pmpg123_string); cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1072 (** Free-up mempory for an existing mpg123_string
1073 * \param sb string handle
1074 *)
1075 procedure mpg123_free_string(sb: pmpg123_string); cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1077 (** Change the size of a mpg123_string
1078 * \param sb string handle
1079 * \param news new size in bytes
1080 * \return 0 on error, 1 on success
1081 *)
1082 function mpg123_resize_string(sb: pmpg123_string; news: csize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1084 (** Increase size of a mpg123_string if necessary (it may stay larger).
1085 * Note that the functions for adding and setting in current libmpg123
1086 * use this instead of mpg123_resize_string().
1087 * That way, you can preallocate memory and safely work afterwards with
1088 * pieces.
1089 * \param sb string handle
1090 * \param news new minimum size
1091 * \return 0 on error, 1 on success
1092 *)
1093 function mpg123_grow_string(sb: pmpg123_string; news: csize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1095 (** Copy the contents of one mpg123_string string to another.
1096 * Yes the order of arguments is reversed compated to memcpy().
1097 * \param from string handle
1098 * \param to string handle
1099 * \return 0 on error, 1 on success
1100 *)
1101 function mpg123_copy_string(from: pmpg123_string; _to: pmpg123_string ): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1103 (** Append a C-String to an mpg123_string
1104 * \param sb string handle
1105 * \param stuff to append
1106 * \return 0 on error, 1 on success
1107 *)
1108 function mpg123_add_string(sb: pmpg123_string; const stuff: pchar): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1110 (** Append a C-substring to an mpg123 string
1111 * \param sb string handle
1112 * \param stuff content to copy
1113 * \param from offset to copy from
1114 * \param count number of characters to copy (a null-byte is always appended)
1115 * \return 0 on error, 1 on success
1116 *)
1117 function mpg123_add_substring(sb: pmpg123_string; const stuff: pchar; from: csize_t; count: csize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1119 (** Set the content of a mpg123_string to a C-string
1120 * \param sb string handle
1121 * \param stuff content to copy
1122 * \return 0 on error, 1 on success
1123 *)
1124 function mpg123_set_string(sb: pmpg123_string; const stuff: pchar): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1126 (** Set the content of a mpg123_string to a C-substring
1127 * \param sb string handle
1128 * \param stuff the future content
1129 * \param from offset to copy from
1130 * \param count number of characters to copy (a null-byte is always appended)
1131 * \return 0 on error, 1 on success
1132 *)
1133 function mpg123_set_substring(sb: pmpg123_string; const stuff: pchar; from: csize_t; count: csize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1135 (** Count characters in a mpg123 string (non-null bytes or UTF-8 characters).
1136 * Even with the fill property, the character count is not obvious as there could be multiple trailing null bytes.
1137 * \param sb string handle
1138 * \param utf8 a flag to tell if the string is in utf8 encoding
1139 * \return character count
1140 *)
1141 function mpg123_strlen(sb: pmpg123_string; utf8: cint): csize_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1143 (** Remove trailing \\r and \\n, if present.
1144 * \param sb string handle
1145 * \return 0 on error, 1 on success
1146 *)
1147 function mpg123_chomp_string(sb: pmpg123_string): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1149 (** The mpg123 text encodings. This contains encodings we encounter in ID3 tags or ICY meta info. *)
1150 type
1152 const
1153 mpg123_text_unknown = 0; (**< Unkown encoding... mpg123_id3_encoding can return that on invalid codes. *)
1155 mpg123_text_latin1 = 2; (**< ISO-8859-1. Note that sometimes latin1 in ID3 is abused for totally different encodings. *)
1156 mpg123_text_icy = 3; (**< ICY metadata encoding, usually CP-1252 but we take it as UTF-8 if it qualifies as such. *)
1158 mpg123_text_utf16 = 5; (**< Some UTF-16 encoding. The last of a set of leading BOMs (byte order mark) rules.
1159 * When there is no BOM, big endian ordering is used. Note that UCS-2 qualifies as UTF-8 when
1160 * you don't mess with the reserved code points. If you want to decode little endian data
1161 * without BOM you need to prepend 0xff 0xfe yourself. *)
1163 mpg123_text_utf16be = 7; (**< Another alias for UTF16 from ID3v2. Note, that, because of the mess that is reality,
1164 * BOMs are used if encountered. There really is not much distinction between the UTF16 types for mpg123
1165 * One exception: Since this is seen in ID3v2 tags, leading null bytes are skipped for all other UTF16
1166 * types (we expect a BOM before real data there), not so for utf16be!*)
1169 (** The encoding byte values from ID3v2. *)
1170 type
1172 const
1179 (** Convert ID3 encoding byte to mpg123 encoding index.
1180 * \param id3_enc_byte the ID3 encoding code
1181 * \return the mpg123 encoding index
1182 *)
1183 function mpg123_enc_from_id3(id3_enc_byte: cuchar): mpg123_text_encoding; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1185 (** Store text data in string, after converting to UTF-8 from indicated encoding
1186 * A prominent error can be that you provided an unknown encoding value, or this build of libmpg123 lacks support for certain encodings (ID3 or ICY stuff missing).
1187 * Also, you might want to take a bit of care with preparing the data; for example, strip leading zeroes (I have seen that).
1188 * \param sb target string
1189 * \param enc mpg123 text encoding value
1190 * \param source source buffer with plain unsigned bytes (you might need to cast from signed char)
1191 * \param source_size number of bytes in the source buffer
1192 * \return 0 on error, 1 on success (on error, mpg123_free_string is called on sb)
1193 *)
1194 function mpg123_store_utf8(sb: pmpg123_string; enc: mpg123_text_encoding; const source: pcuchar; source_size: csize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1196 (** Sub data structure for ID3v2, for storing various text fields (including comments).
1197 * This is for ID3v2 COMM, TXXX and all the other text fields.
1198 * Only COMM and TXXX have a description, only COMM and USLT have a language.
1199 * You should consult the ID3v2 specification for the use of the various text fields ("frames" in ID3v2 documentation, I use "fields" here to separate from MPEG frames). *)
1200 type
1204 id: array[0..3] of char; (**< The ID3v2 text field id, like TALB, TPE2, ... (4 characters, no string termination). *)
1209 (** The picture type values from ID3v2. *)
1210 type
1212 const
1235 (** Sub data structure for ID3v2, for storing picture data including comment.
1236 * This is for the ID3v2 APIC field. You should consult the ID3v2 specification
1237 * for the use of the APIC field ("frames" in ID3v2 documentation, I use "fields"
1238 * here to separate from MPEG frames). *)
1239 type
1249 (** Data structure for storing IDV3v2 tags.
1250 * This structure is not a direct binary mapping with the file contents.
1251 * The ID3v2 text frames are allowed to contain multiple strings.
1252 * So check for null bytes until you reach the mpg123_string fill.
1253 * All text is encoded in UTF-8. *)
1254 type
1263 genre: pmpg123_string; (**< Genre String (pointer into text_list). The genre string(s) may very well need postprocessing, esp. for ID3v2.3. *)
1264 comment: pmpg123_string; (**< Pointer to last encountered comment text with empty description. *)
1265 (* Encountered ID3v2 fields are appended to these lists.
1266 There can be multiple occurences, the pointers above always point to the last encountered data. *)
1277 (** Data structure for ID3v1 tags (the last 128 bytes of a file).
1278 * Don't take anything for granted (like string termination)!
1279 * Also note the change ID3v1.1 did: comment[28] = 0; comment[29] = track_number
1280 * It is your task to support ID3v1 only or ID3v1.1 ...*)
1281 type
1294 const
1296 MPG123_NEW_ID3 = $1; (**< 0001 There is ID3 info that changed since last call to mpg123_id3. *)
1298 MPG123_NEW_ICY = $4; (**< 0100 There is ICY info that changed since last call to mpg123_icy. *)
1300 (** Query if there is (new) meta info, be it ID3 or ICY (or something new in future).
1301 * \param mh handle
1302 * \return combination of flags, 0 on error (same as "nothing new")
1303 *)
1304 function mpg123_meta_check(mh: pmpg123_handle): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF}; (* On error (no valid handle) just 0 is returned. *)
1306 (** Clean up meta data storage (ID3v2 and ICY), freeing memory.
1307 * \param mh handle
1308 *)
1309 procedure mpg123_meta_free(mh: pmpg123_handle); cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1311 (** Point v1 and v2 to existing data structures wich may change on any next read/decode function call.
1312 * v1 and/or v2 can be set to NULL when there is no corresponding data.
1313 * \return MPG123_OK on success
1314 *)
1315 function mpg123_id3(mh: pmpg123_handle; v1: ppmpg123_id3v1; v2: ppmpg123_id3v2): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1317 (** Point icy_meta to existing data structure wich may change on any next read/decode function call.
1318 * \param mh handle
1319 * \param icy_meta return address for ICY meta string (set to NULL if nothing there)
1320 * \return MPG123_OK on success
1321 *)
1322 function mpg123_icy(mh: pmpg123_handle; icy_meta: ppchar): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF}; (* same for ICY meta string *)
1324 (** Decode from windows-1252 (the encoding ICY metainfo used) to UTF-8.
1325 * Note that this is very similar to mpg123_store_utf8(&sb, mpg123_text_icy, icy_text, strlen(icy_text+1)) .
1326 * \param icy_text The input data in ICY encoding
1327 * \return pointer to newly allocated buffer with UTF-8 data (You free() it!) *)
1328 function mpg123_icy2utf8(const icy_text: pchar): pchar; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1330 (* @} *)
1332 (** \defgroup mpg123_advpar mpg123 advanced parameter API
1333 *
1334 * Direct access to a parameter set without full handle around it.
1335 * Possible uses:
1336 * - Influence behaviour of library _during_ initialization of handle (MPG123_VERBOSE).
1337 * - Use one set of parameters for multiple handles.
1338 *
1339 * The functions for handling mpg123_pars (mpg123_par() and mpg123_fmt()
1340 * family) directly return a fully qualified mpg123 error code, the ones
1341 * operating on full handles normally MPG123_OK or MPG123_ERR, storing the
1342 * specific error code itseld inside the handle.
1343 *
1344 * @{
1345 *)
1347 (** Opaque structure for the libmpg123 decoder parameters. *)
1348 type
1353 (** Opaque structure for the libmpg123 decoder parameters. *)
1354 type
1358 (** Create a handle with preset parameters.
1359 * \param mp parameter handle
1360 * \param decoder decoder choice
1361 * \param error error code return address
1362 * \return mpg123 handle
1363 *)
1364 function mpg123_parnew(mp: pmpg123_pars; const decoder: pchar; error: pcint): pmpg123_handle; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1366 (** Allocate memory for and return a pointer to a new mpg123_pars
1367 * \param error error code return address
1368 * \return new parameter handle
1369 *)
1370 function mpg123_new_pars(error: pcint): pmpg123_pars; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1372 (** Delete and free up memory used by a mpg123_pars data structure
1373 * \param mp parameter handle
1374 *)
1375 procedure mpg123_delete_pars(mp: pmpg123_pars); cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1377 (** Configure mpg123 parameters to accept no output format at all,
1378 * use before specifying supported formats with mpg123_format
1379 * \param mp parameter handle
1380 * \return MPG123_OK on success
1381 *)
1382 function mpg123_fmt_none(mp: pmpg123_pars): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1384 (** Configure mpg123 parameters to accept all formats
1385 * (also any custom rate you may set) -- this is default.
1386 * \param mp parameter handle
1387 * \return MPG123_OK on success
1388 *)
1389 function mpg123_fmt_all(mp: pmpg123_pars): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1391 (** Set the audio format support of a mpg123_pars in detail:
1392 * \param mp parameter handle
1393 * \param rate The sample rate value (in Hertz).
1394 * \param channels A combination of MPG123_STEREO and MPG123_MONO.
1395 * \param encodings A combination of accepted encodings for rate and channels,
1396 * p.ex MPG123_ENC_SIGNED16|MPG123_ENC_ULAW_8 (or 0 for no
1397 * support).
1398 * \return MPG123_OK on success
1399 *)
1400 function mpg123_fmt(mp: pmpg123_pars; rate: clong; channels: cint; encodings: cint): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF}; (* 0 is good, -1 is error *)
1402 (** Check to see if a specific format at a specific rate is supported
1403 * by mpg123_pars.
1404 * \param mp parameter handle
1405 * \param rate sampling rate
1406 * \param encoding encoding
1407 * \return 0 for no support (that includes invalid parameters), MPG123_STEREO,
1408 * MPG123_MONO or MPG123_STEREO|MPG123_MONO. *)
1409 function mpg123_fmt_support(mp: pmpg123_pars; rate: clong; encoding: cint): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1411 (** Set a specific parameter, for a specific mpg123_pars, using a parameter
1412 * type key chosen from the mpg123_parms enumeration, to the specified value.
1413 * \param mp parameter handle
1414 * \param type parameter choice
1415 * \param value integer value
1416 * \param fvalue floating point value
1417 * \return MPG123_OK on success
1418 *)
1419 function mpg123_par(mp: pmpg123_pars; _type: mpg123_parms; value: clong; fvalue: cdouble): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1421 (** Get a specific parameter, for a specific mpg123_pars.
1422 * See the mpg123_parms enumeration for a list of available parameters.
1423 * \param mp parameter handle
1424 * \param type parameter choice
1425 * \param value integer value return address
1426 * \param fvalue floating point value return address
1427 * \return MPG123_OK on success
1428 *)
1429 function mpg123_getpar(mp: pmpg123_pars; _type: mpg123_parms; val: pclong; fval: pcdouble): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1431 (* @} *)
1434 (** \defgroup mpg123_lowio mpg123 low level I/O
1435 * You may want to do tricky stuff with I/O that does not work with mpg123's default file access or you want to make it decode into your own pocket...
1436 *
1437 * @{ *)
1439 (** Replace default internal buffer with user-supplied buffer.
1440 * Instead of working on it's own private buffer, mpg123 will directly use the one you provide for storing decoded audio.
1441 * Note that the required buffer size could be bigger than expected from output
1442 * encoding if libmpg123 has to convert from primary decoder output (p.ex. 32 bit
1443 * storage for 24 bit output).
1444 * \param mh handle
1445 * \param data pointer to user buffer
1446 * \param size of buffer in bytes
1447 * \return MPG123_OK on success
1448 *)
1449 function mpg123_replace_buffer(mh: pmpg123_handle; data: pcuchar; size: csize_t): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1451 (** The max size of one frame's decoded output with current settings.
1452 * Use that to determine an appropriate minimum buffer size for decoding one frame.
1453 * \param mh handle
1454 * \return maximum decoded data size in bytes
1455 *)
1456 function mpg123_outblock(mh: pmpg123_handle): csize_t; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1458 (** Replace low-level stream access functions; read and lseek as known in POSIX.
1459 * You can use this to make any fancy file opening/closing yourself,
1460 * using mpg123_open_fd() to set the file descriptor for your read/lseek
1461 * (doesn't need to be a "real" file descriptor...).
1462 * Setting a function to NULL means that the default internal read is
1463 * used (active from next mpg123_open call on).
1464 * Note: As it would be troublesome to mess with this while having a file open,
1465 * this implies mpg123_close().
1466 * \param mh handle
1467 * \param r_read callback for reading (behaviour like POSIX read)
1468 * \param r_lseek callback for seeking (like POSIX lseek)
1469 * \return MPG123_OK on success
1470 *)
1471 type
1475 function mpg123_replace_reader(mh: pmpg123_handle; r_read: mpg123_readproc; r_lseek: mpg123_seekproc): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1477 (** Replace I/O functions with your own ones operating on some kind of
1478 * handle instead of integer descriptors.
1479 * The handle is a void pointer, so you can pass any data you want...
1480 * mpg123_open_handle() is the call you make to use the I/O defined here.
1481 * There is no fallback to internal read/seek here.
1482 * Note: As it would be troublesome to mess with this while having a file open,
1483 * this mpg123_close() is implied here.
1484 * \param mh handle
1485 * \param r_read callback for reading (behaviour like POSIX read)
1486 * \param r_lseek callback for seeking (like POSIX lseek)
1487 * \param cleanup A callback to clean up an I/O handle on mpg123_close,
1488 * can be NULL for none (you take care of cleaning your handles).
1489 * \return MPG123_OK on success
1490 *)
1491 function mpg123_replace_reader_handle(mh: pmpg123_handle; r_read: mpg123_readproc; r_lseek: mpg123_seekproc; cleanup: pointer): cint; cdecl; external {$IFDEF MPG123_DYNAMIC}LIB_MPG123{$ENDIF};
1493 (* @} *)
1495 implementation