Skip to contents

This file is used to read an audio file and return a Wave object, it is an abstraction function for various specific audio reading functions. If no existing method can be identified an attempt is made to use the av package to read the audio.

Usage

readAudio(
  file,
  mime = "auto",
  from = 0,
  to = Inf,
  time.unit = "seconds",
  units
)

Arguments

file

File to read

mime

MIME type of file to read, or "auto" to read the type from the bytes of the file rather than from its name. "audio/x-wav" is read by tuneR::readWave(); any other type, "audio/mpeg" (MP3) among them, is read by the av package.

from

Start point in file to return, a number that is not negative, and a whole number in samples, which must fall within the recording

to

End point in file to return, a number that is not negative, and a whole number in samples, which must leave some audio after the start point, read as the end of the recording where it is beyond it

time.unit

One of "samples", "seconds", "minutes", "hours". Default is "seconds".

units

Deprecated, use time.unit instead.

Value

A Wave object, or a WaveMC object for a file with more than two channels.

Details

Mono and stereo files are returned as a tuneR::Wave object, and files with more than two channels as a tuneR::WaveMC object holding one column per channel, in the order the file holds them. writeAudio() writes either back out, and functions that take multichannel audio, such as tdoa(), take the result directly.

Which reader a file is given to is decided by the first bytes of the file, not by its extension, as a name is only a convention and the two disagree often enough in a real collection to matter: a wave file called .mp3 read as an MP3 comes back as a shorter recording at the wrong sample rate, without complaint. The name is used only where the bytes identify nothing. Passing mime says what the file is and is taken as given, whatever it holds.

WAVE files are read by tuneR::readWave() whatever their channel count, so a multichannel WAVE keeps the channel names the file itself records. Everything read through the av package is named by channel position instead (see tuneR::MCnames), because the av package reports a channel layout that does not identify the channels of the file.

Files read through the av package (which is everything that is not WAVE, e.g. FLAC) are returned at the bit depth the file was stored at, so that the same audio compares equal however it was read. The av package does not report a bit depth of 24, and returns 24bit audio as 32bit, so the samples of a 24bit file are 256 times those tuneR::readWave() would give for the same audio stored as WAVE. Audio stored as floating point is returned as 32bit.

MP3 files are read through the av package too, and returned as 16bit, as tuneR::readMP3() returned them before. That function decodes with libmad and fills as many samples as the frame headers count: where libmad skips a frame it cannot decode, as it skips a first frame whose audio begins in bytes before the start of the file, every later sample comes a frame early and the last frame's samples are whatever the memory held, which change from one read to the next. The av package decodes every frame, and drops the encoder's delay where the file records it, so a recording can be shorter than tuneR::readMP3() gave: AUDIOMOTH.mp3 is 240000 sample frames rather than 241920.

A sample at negative full scale is read as the value it holds. Read through the av package it is -2^31 in the 32bit range the package decodes to, which R keeps for a missing integer, so the av package gives -2^31 + 1 instead; at 8, 16 and 24 bits nothing else gives that, and it is read as the full scale it is. At 32 bits, of integers or floating point, -2^31 + 1 can be a sample of its own, and is left as it is. A 32bit PCM WAVE file read by tuneR::readWave() gives -2^31 for it.

A recording made on a trigger is expanded by audiomothExpand() as it is read, so that the periods that did not trigger a recording are returned as silence and the timing of the triggered recordings is preserved. Such a recording is recognised by the trigger AudioMoth records in the comment it writes into the header, rather than by the T before its extension: a name is only a convention, which an ordinary recording can meet and a triggered one can be renamed out of. A file whose comment has been lost can still be expanded by calling audiomothExpand() on it.

A recorder that loses power part-way through a WAV file can stop before writing the size of the audio, leaving a file that declares an empty recording while still holding the audio it was recording at the time. The audio of such a file is read to the end of the file, with a warning, rather than returned as nothing. A file that really holds no audio is read as empty.

A recording cut short, by a flat battery, a full card or a copy that did not finish, declares more audio than the file holds. The audio that is there is returned, with a warning naming the sample frames the file declares and the frames it holds, whatever part of the recording was asked for: the wave is otherwise no different from one of a recording that was meant to be that short. Only whole sample frames are read, so a frame the file holds only some of the bytes of is left out rather than made up, and a part of the recording that starts beyond the audio the file holds is refused as one beyond the end of any recording is.

A recording too long for the 4 GiB a RIFF header can describe is written in the RF64 or BW64 form, which keeps its sizes in a ds64 chunk. tuneR::readWave() does not read these forms, so they are read through the av package, by those sizes. One whose sizes were never written is recovered as above. One whose ds64 chunk disagrees with the rest of the file, or miscounts its sample frames, is still read, with a warning saying what is wrong with it.

Samples that are not finite numbers, which a floating-point file can hold, are read as zero with a warning, as they would otherwise spread through every measurement made from the wave.

Reading part of a recording

from and to give the part of the recording to return. An end point beyond the end of the recording reads to the end of it, as the default end of Inf does. A start point at or beyond the end is an error, of class startPastEnd, saying how long the recording is, whatever the format of the file and whatever the unit of the start: the part asked for holds no audio at all, and a start past the end is most often one given in the wrong unit, which an empty wave would carry into everything measured from it without saying so. A start of zero is the start of any recording, so a file that holds no audio is read from there as empty.

An end point that leaves no audio after the start point is an error of class endBeforeStart, for the same reason and in every format and unit alike: a start and an end swapped, or computed from different things, ask for nothing that can be measured. In samples the end point is the last sample returned, so an end at the start returns that one sample, and an end of zero is before the first. In a unit of time the two points are placed at the boundaries between samples nearest to them, so an end at the start holds no audio, nor does a part so short that both of its points are nearest the same boundary. Every format is cut at those same samples, so a part of a recording is the same part however the file holds it, and two parts that meet at a time meet without a sample lost or repeated between them.

A start or end point is a single number, and is never negative, in any unit; in samples it is a whole number too, as there is no part of a sample to start or end at. Any other point is an error of class invalidPoint, raised before the file is read, whatever its format. A fraction of a sample was read from a WAVE file from part-way into a sample, as audio made of the bytes of two samples, and a point written as text, or held as a factor or a time difference, was read as something other than what it said. A number of samples worked out from a time that misses the whole number it stands for by the last bits of a double, as 0.009 * 48000, which is 431.99999999999994, does, is read as that whole number.

A header that disagrees with the recorder's own metadata

A recorder can write a sample rate into its metadata that disagrees with the one in the format chunk of the header, and the header can be the one that is wrong. The wave is returned at the rate the header gives, as that is the rate the samples were read at, and the disagreement is reported with a warning naming both rates: nothing in the file says which of them is right, and a recording read at a tenth of the rate it was made at reads as ten times its length, with every frequency measured from it wrong by the same factor and nothing in the wave to show it.

The rates compared against the header are the Samplerate of the GUANO metadata and the F= rate of each generation of a bext coding history. A time-expanded recording is stored at a lower rate than it was made at, which is no fault: GUANO records the factor in its TE field, so a rate that meets the header rate multiplied by that factor is agreement. Of a coding history holding several generations, any one of them meeting the header is enough, as the others describe the recording as it was before it was last written.

Handling these warnings

Each warning above carries a class of its own, so that one of them can be handled without silencing the rest: sampleRateMismatch, unwrittenAudioSize, truncatedAudio and nonFiniteSamples; and badDs64 and frameCountMismatch for an RF64 or BW64 file whose ds64 chunk cannot be believed or miscounts its sample frames. All of them are also classed audioFileWarning, for handling every warning about the file at once, and warning, so suppressWarnings() and an ordinary warning handler treat them as the warnings they are.

withCallingHandlers(
  readAudio(file),
  sampleRateMismatch = function(cond) invokeRestart("muffleWarning")
)

The file it was read from

The wave records the path of the file it was read from, made absolute, in an attribute named "audioFile", which tagWave() moves into the metadata slot and calculateMetadata() reads to find the file. A wave read from part of a file records the same path as one read from the whole of it.