# Description of MP3.DLL (version 1.0.0.x)

## 0. Preface

Table of contents:

- Methods Definitions
- Structure PlayRecord
- Description of methods
- Messages handle

MP3 library let You playing MPEG Layer III files in Windows 95 and Windows NT (in NT it should be work, but I don't check it). I hope so this description will help you to learn about using this library.

Together with MP3 library pack was delivered simple program in Delphi 3 which demonstrate how to use this library.

If after all you had any questions, mail me to address robin@arrakis.cs.put.poznan.pl, I try answer.

## 1. Methods definitions

> In library was declared following methods (because you might have problems with pass the parameters, I show you how this methods was declared):

> Play function:
> extern "C" {
> void WINAPI _export mp3play(PlayRecord far *DATA);
> }

> Stop function:
> extern "C" {
> void WINAPI _export mp3stop(void);
> }

> Seek function:
> extern "C" {
> void WINAPI _export mp3seek(int32 position);
> }

> Function which let you get time info about specified file:
> extern "C" {
> void WINAPI _export mp3gettime(PlayRecord far *DATA, double far *total, double far *perframe);
> }

## 2. Structure PlayRecord

> Method, which play .MP3 file get information about track from PlayRecord structure, which is a method parameter. Declaration of this structure:

> typedef struct {

- > char *FileName;
  > DWORD SeekAtStart;
  > HWND Owner;
  > DWORD Result;

  > } PlayRecord;

  ### Fields description:

  > - Filename - pointer to null-character string witch full name of file.

  > - SeekAtStart - start position (in frames).

  > - Owner - handle of window, which will be handle messages from library.

  > - Result - after return from mp3play method this field contain exit code (zero if no error occurs)

## 3. Description of methods

- ### 3.1 Get time information

  > mp3gettime(PlayRecord far *DATA, double far *total, double far *perframe)

- #### Fields description:

  > - DATA - structure described in point 2.

  > - total - track length in milliseconds

  > - perframe - number of milliseconds per frame

  #### Description:

  > This method return in fields total and perframe information need to define time parameter of playing track. You have to fill only DATA->FileName field.

  > If file is not exist or file haven't got MP3 header, the field DATA->Result will be equal 1.

### 3.2 Play file

> mp3play(PlayRecord far *DATA)

- #### Fields description:

  > - DATA - structure described in point 2.

  #### Description:

  > This method play the MP3 file specified in DATA structure. You may start play from specified in field DATA->SeekAtStart position.

  > ATENTION! This method doesn't create thread, which allow return from method before stop playing track. So, you have to create thread from this method if you want to have control of play process.

  > If file is not exist or file haven't got MP3 header, the field DATA->Result will be equal 1. If any error was occurred while executing play method this filed will be Equal 2. But the best way to detect error is recognize why play method was stopped (see Messages handle).

### 3.3 Seeking

> mp3seek(int32 position)

#### Fields description:

> - position - contain number of frame which will be played

#### Description:

> No description

### 3.4 Stop playing

> mp3stop(void)

#### Opis:

> This method stops the play process.

> ATENTION! Return from this method doesn't mean stop play process and free audio channel. So, you might have problems if you write sequence like this:

> {

> CreateThread(nil,0,&mp3play,&FirstTrack,0,dwThreadId);
> mp3stop();
> CreateThread(nil,0,&mp3play,&SecondTrack,0,dwThreadId);

> }

> Play process was stopped finally when you get message PLAY_STOP (see Message handle).

## 4. Messages handle

> Structure PlayRecord contain field-specifying handle of window, which will be service messages from MP3 library.

> There are following messages:

> - FRAME_POS (value 12000)

> Field wParam contain number of current frame. This message is sending after every 16 frames.

> - APPLY_POS (value 12001)

> This message is sending when seek process was done.

> - PLAY_STOP (value 12002)

> This message is sending when play process was stopped. Field lParam contain information why this process was stopped:

> value | Cause
> --- | ---
> 0 | End of track
> 1 | Error while playing (for example: AUDIO stream is in use)
> 2 | User break