--background--

HISTORY

   51.9  (28.06.2015)
   - Added MMA_MimeType attribute.
   - Revised and extended MMA_DataFormat attribute handling.

   51.8  (09.08.2012)
   - MMM_Seek() finally uses MMM_PreSeek()/MMM_PostSeek() methods, in
     effect the demuxer works properly with non-seekable sources.

   51.7  (07.04.2007)
   - Implemented MMA_ExtraData for reading WAVE 'fmt ' extension.
   - Added support for MicroSoft ADPCM subformat.

   51.6  (03.04.2007)
   - MMM_SEEK_BYTES is now allowed in MMM_Seek(). It is needed for
     compressed subformats, when only decoder can perform frame/time
     seek.

   51.5  (18.11.2006)
   - Added support for IMA ADPCM subformat.
   - Added MMA_BlockAlign internal attribute.

   51.4  (08.01.2006)
   - Fixed seeking bug in SeekChunk(): current chunk position was not
     updated.

   51.3  (15.11.2005)
   - Fixed error forwarding in MMM_Pull.
   - Fix in ReadChunkBytes(), MMM_Pull is not called if data size is 0.

   51.2  (06.06.2005)
   - Added support for type 6 (CCITT A-law PCM) and type 7 (CCITT mu-law
     PCM).

   51.1  (05.06.2005)
   - Type 3 (floating point PCM) streams return 32 as
     MMA_Sound_BitsPerSample, 25 was misleading, as it didn't represent
     dynamic range properly.
   - Seeking implemented.

   50.5  (08.12.2004)
   - Separate MMM_Setup for every port.

   50.4  (26.11.2004)
   - Support for WAVE type 3 (floating point PCM).

   50.3  (22.11.2004)
   - WAVE MPEG-s are handled (using mpegaudio.decoder).

   50.2  (16.11.2004)
   - Implemented MMA_DataFormat.

   50.1  (23.10.2004)
   - Initial revision.

DESCRIPTION

   The class is a Reggae demultiplexer for WAVE (*.wav) sounds. WAVE format
   has many subformats and wave.demuxer will select matching decoder. The
   demuxer extracts header information ans passes sound data to the next
   processing stage. The demuxer recognizes following subformats:
     - type 1, uncompressed integer PCM,
     - type 2, MicroSoft ADPCM,
     - type 3, uncompressed floating point PCM,
     - type 6, CCITT A-law PCM,
     - type 7, CCITT mu-law PCM,
     - type 17, IMA/DVI ADPCM,
     - type 85, MPEG-1 Audio Layer III.

   Port 0 (input) accepts MMF_STREAM.
   Port 1 (output) produces one of:
     - MMF_AUDIO_PCM8U (type 1, 8-bit)
     - MMF_AUDIO_PCM16LE (type 1, 16-bit)
     - MMF_AUDIO_PCM24LE (type 1, 24-bit)
     - MMF_AUDIO_PCM32LE (type 1, 32-bit)
     - MMF_AUDIO_MS_ADPCM (type 2)
     - MMF_AUDIO_PCMF32LE (type 3)
     - MMF_AUDIO_ALAW (type 6)
     - MMF_AUDIO_MULAW (type 7)
     - MMF_AUDIO_IMA_ADPCM (type 17)
     - MMF_AUDIO_MPEG (type 85)

   wave.demuxer is direct subclass of multimedia.class.

NEW ATTRIBUTES

   Attributes applicability:
     I - may be set at creation time.
     S - may be set on an existing object.
     G - may be get from an object.
     P - may be set for an object's port.
     Q - may be queried from an object's port.

   MMA_DataFormat           (V50)    [..G.Q], STRPTR
   MMA_Sound_BitsPerSample  (V50)    [..G.Q], ULONG
   MMA_Sound_Channels       (V50)    [..G.Q], ULONG
   MMA_Sound_FrameCount     (V50)    [..G.Q], UQUAD*
   MMA_Sound_SampleRate     (V50)    [..G.Q], ULONG
   MMA_Sound_Volume         (V50)    [..G.Q], ULONG
   MMA_StreamPosFrames      (V51)    [..G.Q], UQUAD*
   MMA_StreamPosTime        (V51)    [..G.Q], UQUAD*
   MMA_BlockAlign           (V51)    [..G.Q], ULONG
   MMA_ExtraData            (V51.7)  [..G.Q], APTR

NEW METHODS

   MMM_Pull(port, buffer, length)  (V50)
   MMM_Seek(port, type, position)  (V51)

MMA_BlockAlign

MMA_BlockAlign (V51) [..G.Q], ULONG

DESCRIPTION

   Additional information for some of subformats. Used internally by
   some decoders

MMA_DataFormat

MMA_DataFormat (V50) [..G.Q], STRPTR

DESCRIPTION

   Returns read-only textual NULL-terminated description of decoded format.
   The description depends on WAVE subformat:
   - sub 1: "WAVE",
   - sub 2: "WAVE MS-ADPCM",
   - sub 3: "WAVE FP",
   - sub 6: "WAVE A-law",
   - sub 7: "WAVE mu-law",
   - sub 17: "WAVE IMA-ADPCM",
   - sub 85: "WAVE MPEG-1 Layer III".
 The class itself returns "WAVE

MMA_ExtraData

MMA_ExtraData (V51.7) [..G.Q], APTR

DESCRIPTION

   This attribute returns a pointer to WAVE 'fmt ' chunk extension data. It
   is used to transfer data needed for stream decoding to a decoder. The
   structure format depends on WAVE subformat. The first two bytes contain
   following extension data length in bytes. It is converted to big endian
   already, however any following data are not converted, as the class does
   not interprete them in any way, it is up to a decoder

MMA_MimeType

MMA_DataFormat (V51.9) [..G.Q], STRPTR

DESCRIPTION

   Returns read-only NULL-terminated MIME type string. The type depends on
   on WAVE subformat:
   - sub 1: "audio/wav",
   - sub 2: "audio/wav; codec=ms-adpcm",
   - sub 3: "audio/wav; codec=float",
   - sub 6: "audio/wav; codec=a-law",
   - sub 7: "audio/wav; codec=mu-law",
   - sub 17: "audio/wav; codec=ima-adpcm",
   - sub 85: "audio/wav; codec=mpeg".
 The class itself returns "audio/wav

MMA_Sound_BitsPerSample

MMA_Sound_BitsPerSample (V50) [..G.Q], ULONG

DESCRIPTION

   Specifies number of significant bits in a single sound sample as found in
   the header

MMA_Sound_Channels

MMA_Sound_Channels (V50) [..G.Q], ULONG

DESCRIPTION

   Specifies number of channels in WAVE stream as found in the header.
   Reggae can process up to 256 channels (streams with more channels will be
   rejected). Subformat channel limit is usually lower than that

MMA_Sound_FrameCount

MMA_Sound_FrameCount (V50) [..G.Q], UQUAD*

DESCRIPTION

   Returns number of sample frames in the stream as specified in the header

NOTES

   This is a 64-bit attribute passed by pointer to UQUAD variable, not by
   value.

MMA_Sound_SampleRate

MMA_Sound_SampleRate (V50) [..G.Q], ULONG

DESCRIPTION

   Specifies sampling rate of WAVE stream as found in the header, measured
   in sample frames per seconds. Any integer value is accepted, but note
   that output devices (as well as many filters) may not accept extremely
   high values

MMA_Sound_Volume

MMA_Sound_Volume (V50) [..G.Q], ULONG

DESCRIPTION

   Specifies default sound volume relative to the maximum one. Range of this
   attribute is from 0 (silence) to 65536 including (full volume). Current
   version of wave.demuxer does not recognize any WAVE chunks containing
   volume information so this attribute returns 65536 always

MMA_StreamPosFrames

MMA_StreamPosFrames (V51) [..G.Q], UQUAD*

DESCRIPTION

   Returns current absolute stream position in sample frames

NOTES

   This is a 64-bit attribute passed by pointer to UQUAD variable, not by
   value.

MMA_StreamPosTime

MMA_StreamPosTime (V51) [..G.Q], UQUAD*

DESCRIPTION

   Returns absolute stream time position in microseconds. This time position
   is strictly based on MMA_Sound_SampleRate, and reflects only the whole
   sample frames already pulled from the object output. The exact formula
   is:

   time_pos = whole_frames_pulled / MMA_Sound_SampleRate

NOTES

   This is a 64-bit attribute passed by pointer to UQUAD variable, not by
   value.

   Returned time is not in any way related to playback time for two reasons:
   firstly, there can be an unknown number of buffers between the
   demultiplexer and the output, secondly, playback samplerate may be
   different than those specified in the stream header.

SEE ALSO

MMM_Pull

Loads a block of encoded data to a buffer. (V50)

SYNOPSIS

   bytes = DoMethod(obj, MMM_Pull, ULONG port, APTR buffer, ULONG length);

DESCRIPTION

   Loads specified number of bytes of WAVE encoded data into the buffer. As
   the class does not process the data, it does not copy them, just passes
   them through

INPUTS

   - obj, object to perform the method on.
   - port, number of port is always 1 (the output port).
   - buffer, a memory buffer for pulled data, must be aligned to 16-byte
     boundary (preferrably allocated with MediaAllocVec()).
   - length, amount of pulled data in bytes

RESULT

   - bytes, number of bytes pulled actually

SEE ALSO

MMM_Seek

MMM_Seek (V51)

SYNOPSIS

   success = DoMethod(obj, MMM_Seek, ULONG port, ULONG type, UQUAD*
   position);

DESCRIPTION

   Performs seek in PCM stream as found in WAVE file. As wave.demuxer object
   knows samplerate and frame size, only frame seek and time seek are
   supported

INPUTS

   - obj, object to perform the method on.
   - port, number of port is always 1 (the output port).
   - type, seek type (MMM_SEEK_FRAMES, MMM_SEEK_TIME).
   - position, new, absolute position in the stream. For frame seek it is in
     frames, for time seek in microseconds. It is 64-bit parameter passed by
     a pointer to the value. Note that it is not playback time, see
     MMA_StreamPosTime for explanation

RESULT

   TRUE if success, FALSE otherwise. Check MMA_ErrorCode for detailed
   information

SEE ALSO