Wav::Read(3pm)

💖 Wav::Read — the manual, but make it cute

okay so this is Wav::Read(3pm) from the User Contributed Perl Documentation collection, and bestie, if you're here it's because you want to read Microsoft WAV files and you want it to be easy. spoiler: it is. let's go 💅

---

✨ NAME ✨

Audio::Wav::Read — the module for reading Microsoft WAV files. that's it, that's the whole job, and it does it fabulously 🎀

---

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste and go:

use Audio::Wav;

my $wav = new Audio::Wav;
my $read = $wav -> read( 'filename.wav' );
#OR
my $read = Audio::Wav -> read( 'filename.wav' );

my $details = $read -> details();

like, you either build an Audio::Wav object first and call read on it, or you skip straight to Audio::Wav -> read(...). both paths, same destination, no cap 🦋

---

🔥 DESCRIPTION 🔥

Reads Microsoft Wav files. periodt.

---

👀 SEE ALSO 👀

• Audio::Wav
• Audio::Wav::Write

---

💀 NOTES 💀

girlie listen. this module shouldn't be used directly. a blessed object can be returned from Audio::Wav. so like, don't come for this file's door directly, go through the parent. iykyk 🙈

---

👑 METHODS 👑

file_name

Returns the file name.

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

just... the name of the file. iconic, simple, we love her.

---

get_info

Returns information contained within the wav file.

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

you get back a reference to a hash containing stuff. here's an example — a file marked up for use in Audio::Mix:

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

the way this just hands you the metadata for free 🥹 obsessed.

---

get_cues

Returns the cuepoints marked within the wav file.

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

you get a reference to a hash back — again, example is a file marked up for use in Audio::Mix, and heads up that 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,
    }
}

no comment on cue 3 and 4 being in that order, that's just what the file says, keep it moving 💅

---

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

you get back an array of unpacked samples, and each element is a channel, i.e. ( left, right ). the numbers land in this 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. genuinely too many to list here — bestie, just 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();

yes, live-editing the file while you read it is a whole situation, and this is the method that handles it. main character energy fr fr 🔥

---

🫶 AUTHORS 🫶

giving credit where credit is due, all of these legends:

Nick Peskett (see http://www.peskett.co.uk/ for contact details).
Brian Szymanski <ski-cpan@allafrica.com> (0.07-0.14)
Wolfram humann (pureperl 24 and 32 bit read support in 0.09)
Kurt George Gjerde <kurt.gjerde@media.uib.no>. (0.02-0.03)

---

and that's the whole page, bestie! this one shipped with perl v5.36.0, dated 2022-10-13, living its life as Wav::Read(3pm). now go read some wav files and slay ✨💖🎀