Deprecated. Reads and parses metadata stored in wave files produced by AudioMoth devices.
Value
A list of extracted parameters:
- raw
The comment string the other fields were read from
- start_time
Recording start time, as
"HH:MM:SS"- start_date
Recording start date, as
"DD/MM/YYYY"- time_zone
Time zone of the start time, e.g.
"UTC"or"UTC+1"- serial
The device serial number, or NA for a deployment ID file
- deployment_id
The configured deployment ID, or NA if none was set
- gain
Gain setting, one of "low", "low-medium", "medium", "medium-high" or "high"
- voltage
Battery voltage in volts. Where the firmware reported only that the battery was outside the range it measures, the threshold it compared against is returned with a leading
"<"or">", e.g."<2.5". The thresholds themselves have changed: firmware up to 1.2.0 wrote"<3.6"and">5.0", 1.2.2 and 1.3.0"<3.6"and">4.9", and 1.4.0 onwards"<2.5"and">4.9"- temperature
Temperature in degrees Celsius, or NA for firmware before 1.4.0, which did not record it
- external_mic
Whether an external microphone was used
- filter
"Low-pass", "Band-pass", "High-pass", or FALSE if no filter was applied
- filter.limit
Filter frequency as the recorder writes it in its comment: text, in kHz, such as
"5.0", or two values separated by a hyphen for a band-pass filter, such as"1.0-5.0". It is not converted to Hz, the unit of the frequencies the package measures, as it is a reading of the recorder's own record. FALSE if no filter was applied- cancelled
Why the recording stopped early, or FALSE if it ran to completion
- unparsed
The fields the comment appeared to carry and that could not be read, where there are any. Absent otherwise
Details
Deprecated in favour of readMetadata(), which reads the AudioMoth comment
along with every other kind of metadata a file carries and returns these
same fields as its sources$audiomoth. It also normalises the recording
time into a datetime, which this function leaves as the separate
start_date, start_time and time_zone strings the recorder wrote.
The comment written into the wave header has been reworded several times across AudioMoth-Firmware-Basic releases, most significantly in 1.6.0, where "at medium gain setting while battery state was" became "at medium gain while battery was" and the filter and cancellation clauses were rephrased. Fields are matched by pattern rather than by position, so all wordings from 1.0 onwards are read.
Firmware from 1.5.0 can be configured with a deployment ID, which the
firmware writes in place of the device serial number. Such files have a
deployment_id and no serial.
Firmware before 1.4.0 wrote a gain index rather than a gain name, so
gain is a number ("0" to "4") for files from those versions.
Fields that were not read
A field this cannot read is NA, and is named in unparsed. Nothing is
reported as a default: filter, filter.limit, cancelled and
external_mic are FALSE only where the comment carries no clause of that
kind at all, which is how the firmware says that no filter was applied, that
the recording ran to completion and that the built-in microphone was used —
by writing nothing. Where it carries such a clause in a wording this package
does not know, the field is NA rather than FALSE, since FALSE would be a
claim about the recording that the file never made.
unparsed is therefore what tells the two apart: a field that is NA and is
not named there has no value to be had, and one that is NA and is named
there is a wording this package needs to learn. A warning classed
unparsedComment, and unparsedField, carries the comment so that it can
be reported; class it to silence this one kind of warning while reading a
corpus that is known to hold wordings this package does not know.
A comment cut short names nothing in unparsed and warns about nothing.
Every complete comment ends in a full stop, so one that does not was cut —
a version 1 ID3 tag allows a comment 30 bytes, which the recorder's own
wording fills before it reaches the end of the date — and what is past the
cut is absent from the file rather than unread. There is no wording to
report in that case, only a shorter comment than the recorder wrote.
See also
readMetadata(), which reads this alongside every other kind of
metadata a file holds, and whose sources$audiomoth is what this function
returns.
Examples
if (FALSE) { # \dontrun{
# Deprecated. Prefer:
readMetadata("./FILENAME.WAV")$sources$audiomoth
} # }
