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