---------------------------------------------------------------------
                  README file for Audio::Wav (0.05).
---------------------------------------------------------------------

Modules for reading & writing Microsoft WAV files.

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

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

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

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

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

SYNOPSIS
    use Audio::Wav;
    my $wav = new Audio::Wav;
    my $read = $wav -> read( 'input.wav' );
    my $write = $wav -> write( 'output.wav', $read -> details() );
    print "input is ", $read -> length_seconds(), " seconds long\n";

    $write -> set_info( 'software' => 'Audio::Wav' );
    my $data;
    while ( defined( $data = $read -> read_raw( $buffer ) ) ) {
	$write -> write_raw( $data );
    }
    my $length = $read -> length_samples();
    my( $third, $half, $twothirds ) = map int( $length / $_ ), ( 3, 2, 1.5 );
    my %samp_loop = (
	'start' => $third,
	'end'   => $twothirds,
    );
    $write -> add_sampler_loop( %samp_loop );
    $write -> add_cue( $half, "cue label 1", "cue note 1" );
    $write -> finish();

NOTES
    All sample positions are now in sample offsets (unless option
    '.01compatible' is true).

DESCRIPTION
    These modules provide a method of reading & writing uncompressed
    Microsoft WAV files.

METHODS
  new
    Returns a blessed Audio::Wav object. All the parameters are optional and
    default to 0

        my %options = (
            '.01compatible'         => 0,
            'oldcooledithack'       => 0,
            'debug'                 => 0,
        );
        my $wav = Audio::Wav -> new( %options );

  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 Audio::Wav::Write for methods.

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

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

    See Audio::Wav::Read for methods.

  set_error_handler
    Specifies a subroutine for catching errors. The subroutine should take a
    hash as input. The keys in the hash are 'filename', 'message' (error
    message), and 'warning'. If no error handler is set, die and warn will
    be used.

    sub myErrorHandler {
	my( %parameters ) = @_;
	if ( $parameters{'warning'} ) {
	    # This is a non-critical warning
	    warn "Warning: $parameters{'filename'}: $parameters{'message'}\n";
	} else {
	    # Critical error!
	    die "ERROR: $parameters{'filename'}: $parameters{'message'}\n";
	}
    }
    $wav -> set_error_handler( \&myErrorHandler );

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

NAME
    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 Audio::Wav.

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 sample position)

        {
            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_raw_samples
    Reads raw packed samples from the current audio data position in the
    file.

        my $data = $self -> read_raw_samples( $samples );

  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();

  position_samples
    Returns the current audio data position (in samples).

        my $samples = $read -> position_samples();

  move_to
    Moves the current audio data position to byte offset.

        $read -> move_to( $byte_offset );

  move_to_sample
    Moves the current audio data position to sample offset.

        $read -> move_to_sample( $sample_offset );

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

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

  length_samples
    Returns the number of samples of audio data in the file.

        my $audio_samples = $read -> length_samples();

  length_seconds
    Returns the number of seconds of audio data in the file.

        my $audio_seconds = $read -> length_seconds();

  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 ]);

  reread_length
    Rereads the length of the file in case it is being written to as we are
    reading it.

        my $new_data_length = $read -> reread_length();

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

NAME
    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,
            # if you'd like this module not to use a write cache, uncomment the next line
            #'no_cache'     => 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 Audio::Wav.

METHODS
  finish
    Finishes off & closes the current wav file.

        $write -> finish();

  add_cue
    Adds a cue point to the wav file. If $sample is undefined then the
    position will be the current position (end of all data written so far).

        # $byte_offset for 01 compatibility mode
        $write -> add_cue( $sample, "label", "note"  );

  set_sampler_info
    All parameters are optional.

        my %info = (
            'midi_pitch_fraction'   => 0,
            'smpte_format'          => 0,
            'smpte_offset'          => 0,
            'product'               => 0,
            'sample_period'         => 0,
            'manufacturer'          => 0,
            'sample_data'           => 0,
            'midi_unity_note'       => 65,
        );
        $write -> set_sampler_info( %info );

  add_sampler_loop
    All parameters are optional except start & end.

        my $length = $read -> length_samples();
        my( $third, $twothirds ) = map int( $length / $_ ), ( 3, 1.5 );
        my %loop = (
            'start'                 => $third,
            'end'                   => $twothirds,
            'fraction'              => 0,
            'type'                  => 0,
        );
        $write -> add_sampler_loop( %loop );

  add_display
  set_info
    Sets information to be contained in the wav file.

        $write -> set_info( 'artist' => 'Nightmares on Wax', 'name' => 'Mission Venice' );

  file_name
    Returns the current filename.

        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 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

  write_raw_samples
    Adds some pre-packed data to the current file, returns number of samples
    written.

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

    Where;

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

---------------------------------------------------------------------
                              AUTHORS
---------------------------------------------------------------------

    Nick Peskett (see http://www.peskett.co.uk/ for contact details).
    Kurt George Gjerde <kurt.gjerde@media.uib.no>. (from 0.02)

---------------------------------------------------------------------
                                END
---------------------------------------------------------------------
