
   MPEG layer-3 decoder driver v1.4   (C) 1998. by GyikSoft/ESP-team
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Authors:
========
- Porting to DOS real mode, and driver routines made by: GyikSoft/ESP-team
- The decoder routines based on the source of MPG123 player for LINUX,
  by Michael Hipp and Oliver Fromme.

COPYRIGHT:
==========
You can use it FREE for non-commercial programs, but if you
write one, please send it to me!

USING THIS DRIVER:
==================
All of the functions are on INT 33h, the mouse driver interrupt.

You can find the string "GyikSoft MP3 driver" after INT 33h
address+2. (There is a SHORT JMP, jumping over the string...)
It's a possibly method of detecting this driver.

Calling the driver:
   AX=0E0??h   (function number)
   EBX='MP3!'
   INT 33h

Functions:
==========

1. Initialize & detect driver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Call:    AX=0E001h
           EBX='MP3!'
           ES:DI->read_proc   (seg&ofs address of YOUR read_proc routine)
           INT 33h
  Return:  EBX='O.K.' if driver installed

This function initializes buffer pointers, and set the read_proc address.
Note: you must call this, before the decoding!

'read_proc' is a FAR procedure, it's used for reading input stream.
calling of read_proc: (by the decoder driver!)
  Call:    DS:DX = destination address
           CX = number of bytes for read
           Call FAR read_proc
  Return:  AX = number of bytes readed  (0 if error occured)

The simplest read_proc routine:  (for reading file without buffering)
  READ_PROC:
    PUSH BX
      MOV BX,CS:FileHandleNumber
      MOV AH,3Fh   ; DOS / Read file function
      INT 21h
      JNC @OK      ;
        XOR AX,AX  ; return 0 if error
      @OK:         ;
    POP BX
  RETF

2. Reading & decoding a frame
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Call:    AX=0E002h
           EBX='MP3!'
           ES:DI->pcm buffer   (usually 4608 bytes/frame)
           DX=mode
           INT 33h
  Return:  AX=bytes decoded (usually 4608 if success, 0 if error)

mode:
  -2 = reading only, without decoding (must call twice after fseek)
  -1 = reading & decoding to stereo
   0 = reading & decoding to mono  (faster)

This function decodes one frame, reading input via your read_proc
and put the decoded PCM data to buffer (pointed by ES:DI on call),
and returns with number of bytes in buffer, or with zero if
any error occured (can't read input, illegal MPEG header,
or unsupported layer/format).

3. Removing driver from memory:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Call:    AX=0E003h
           EBX='MP3!'
           INT 33h
  Return:  ES=driver's psp segment

  The function resets original interrupts (INT 33h), and put the
  address of PSP in ES, so you need only a FREEMEM-call.
  Example call:
     MOV AX,0E003h
     MOV EBX,'MP3!'
     INT 33h     ; resets interrupts, and put PSP address into ES
     mov AH,49h  ; DOS FREEMEM function (free memory segment in ES)
     INT 21h

Note: I checked all of my .mp3 files, and the decoded frame size
was always 4608 bytes. But I don't know, is it true for ALL mp3s,
because it was handled in LINUX-mpg123 as a variable.

Used compilers:
===============
The decoder part is compiled with WATCOM C v10.6,
the driver routines (written by me) are compiled with
my BAssPasC compiler v2.4 and TASM 3.0.

BUGS:
=====
There aren't known bugs yet. :)
If you found one, or you have problems using this driver,
send an E-mail to me: arpi@banki1.banki.hu

NEW VERSIONS:
=============
Visit our site for download new versions, full source code and
other MP3-related stuffz:   http://banki1.banki.hu/~arpi

There are other usefull programs for DOS & LINUX as well, written
by the ESP-team members. The best ones are BAssPasC compiler and
the ESP archiver, check it out!


