---------------------------------------------------------------------
                    README file for Audio::Wav.
            3/1/99 - Nick Peskett - nick@soup.demon.co.uk
---------------------------------------------------------------------

Modules for reading & writing Microsoft Wav files.

---------------------------------------------------------------------
                                NOTES
---------------------------------------------------------------------

I have seperated the module Audio::ByteOrder because I developed these
packages on a Win32 machine & I was worried about unpacking types on a
big endian processor. I have only tested the Audio::XXX modules on
Win32 so far.

This module is written entirely in Perl. This is because I don't know
any C, however I'm sure the methods read & write in the respective
Read & Write classes would benefit from being re-written. These
methods unpack bytes from the data block in a wav and repack them
again to write.

---------------------------------------------------------------------
                             INSTALLATION
---------------------------------------------------------------------

You'll need to install Audio::Tools first.

Same as for any CPAN module;

tar zxvf Audio-Wav-0.01.tar.gz
cd Audio-Wav-0.01
perl Makefile.PL
make test
make install

---------------------------------------------------------------------
                            DOCUMENTATION
---------------------------------------------------------------------

---------------------------------------------------------------------
                              Audio::Wav
          Modules for reading & writing Microsoft Wav files.
---------------------------------------------------------------------

SYNOPSIS
            use Audio;

            my $buffer = 512;

            my $wav = new Audio::Wav;

            my $read = $wav -> read( 'testout.wav' );

            my $write = $wav -> write( 'testcopy.wav', $read ->
            details() );

            my $total = 0;

            my $length = $read -> length();
            while ( $total < $length ) {
                    my $left = $length - $total;
                    $buffer = $left unless $left > $buffer;
                    my $data = $read -> read_raw( $buffer );
                    last unless defined( $data );
                    $write -> write_raw( $data, $buffer );
                    $total += $buffer;
            }

            $write -> finish();

NOTES
    All sample positions used are in byte offsets (the
    Audio::Tools::Time manpage for conversion utilities)

DESCRIPTION
    These modules provide a method of reading & writing uncompressed
    Microsoft Wav files. It was developed on mswin32 so I'm not sure
    if this version has the correct byte order for big endian
    machines.

METHODS
  new

    Returns a blessed Audio::Wav object.

            my $wav = new Audio::Wav;

  write

    Returns a blessed Audio::Wav::Write object.

            my $details =   {
                            'bits_sample'   => 16,
                            'sample_rate'   => 44100,
                            'channels'      => 2,
                            };

            my $write = $wav -> write( 'testout.wav', $details );

    See the Audio::Wav::Write manpage for methods.

  read

    Returns a blessed Audio::Wav::Read object.

            my $read = $wav -> read( 'testout.wav' );

    See the Audio::Wav::Read manpage for methods.


---------------------------------------------------------------------
                           Audio::Wav::Read
               Module for reading Microsoft Wav files.
---------------------------------------------------------------------

SYNOPSIS
            use Audio::Wav;
            my $wav = new Audio::Wav;
            my $read = $wav -> read( 'filename.wav' );
            my $details = $read -> details();

DESCRIPTION
    Reads Microsoft Wav files.

NOTES
    This module shouldn't be used directly, a blessed object can be
    returned from the Audio::Wav manpage.

METHODS
  file_name

    Returns the file name.

            my $file = $read -> file_name();

  get_info

    Returns information contained within the wav file.

            my $info = $read -> get_info();

    Returns a reference to a hash containing; (for example, a file
    marked up for use in Audio::Mix)

            {
              keywords => 'bpm:126 key:a',
              name => 'Mission Venice',
              artist => 'Nightmares on Wax'
            };

  get_cues

    Returns the cuepoints marked within the wav file.

            my $cues = $read -> get_cues();

    Returns a reference to a hash containing; (for example, a file
    marked up for use in Audio::Mix) (position is byte offset)

            {
              1 => {
                     label => 'sig',
                     position => 764343,
                     note => 'first'
                   },
              2 => {
                     label => 'fade_in',
                     position => 1661774,
                     note => 'trig'
                   },
              3 => {
                     label => 'sig',
                     position => 18033735,
                     note => 'last'
                   },
              4 => {
                     label => 'fade_out',
                     position => 17145150,
                     note => 'trig'
                   },
              5 => {
                     label => 'end',
                     position => 18271676
                   }
            }

  read_raw

    Reads raw packed bytes from the current audio data position in
    the file.

            my $data = $self -> read_raw( $byte_length );

  read

    Returns the current audio data position sample across all
    channels.

            my @channels = $self -> read();

    Returns an array of unpacked samples. Each element is a channel
    i.e ( left, right ). The numbers will be in the range;

            where $samp_max = ( 2 ** bits_per_sample ) / 2
            -$samp_max to +$samp_max

  position

    Returns the current audio data position (as byte offset).

            my $byte_offset = $read -> position();

  move_to

    Moves the current audio data position to byte offset.

            $read -> move_to( $byte_offset );

  length

    Returns the number of bytes of audio data in the file.

            my $audio_bytes = $read -> length();

  details

    Returns a reference to a hash of lots of details about the file.
    Too many to list here, try it with Data::Dumper.....

            use Data::Dumper;
            my $details = $read -> details();
            print Data::Dumper->Dump([ $details ]);


---------------------------------------------------------------------
                          Audio::Wav::Write
               Module for writing Microsoft Wav files.
---------------------------------------------------------------------

SYNOPSIS
            use Audio::Wav;

            my $wav = new Audio::Wav;

            my $sample_rate = 44100;
            my $bits_sample = 16;

            my $details =   {
                            'bits_sample'   => $bits_sample,
                            'sample_rate'   => $sample_rate,
                            'channels'      => 1,
                            };

            my $write = $wav -> write( 'testout.wav', $details );

            &add_sine( 200, 1 );

            sub add_sine {
                    my $hz = shift;
                    my $length = shift;
                    my $pi = ( 22 / 7 ) * 2;
                    $length *= $sample_rate;
                    my $max_no =  ( 2 ** $bits_sample ) / 2;
                    for my $pos ( 0 .. $length ) {
                            $time = $pos / $sample_rate;
                            $time *= $hz;
                            my $val = sin $pi * $time;
                            my $samp = $val * $max_no;
                            $write -> write( $samp );
                    }
            }

            $write -> finish();

DESCRIPTION
    Currently only writes to a file.

NOTES
    This module shouldn't be used directly, a blessed object can be
    returned from the Audio::Wav manpage.

METHODS
  finish

    Finishes off & closes the current wav file.

            $write -> finish();

  add_cue

    Adds a cue point to the wav file.

            $write -> add_cue( $byte_offset, "label", "note"  );

  file_name

    Returns the current filename (silly, I know).

            my $file = $write -> file_name();

  write

    Adds a sample to the current file.

            $write -> write( @sample_channels );

    Each element in @sample_channels should be in the range of;

            where $samp_max = ( 2 ** bits_per_sample ) / 2
            -$samp_max to +$samp_max

  write_raw

    Adds a some pre-packed data to the current file.

            $write -> write_raw( $data, $data_length );

    Where;

            $data is the packed data
            $data_length (optional) is the length in bytes of the data

