viewSpec: Interactively View and Annotate Spectrograms

In jonkatz2/monitoR: Acoustic Template Detection in R

Interactively View and Annotate Spectrograms

Description

Interactively page through short or long spectrograms of wav or mp3 files or Wave objects. Extract short or long wave files, play audio while viewing spectrogram, and annotate sounds in the spectrogram. Load annotations from csv files for viewing.

Usage

viewSpec(clip, interactive = FALSE, start.time = 0, 
    units = "seconds", page.length = 30, 
    annotate = FALSE, anno, channel = "left", 
    output.dir = getwd(), frq.lim = c(0, 12), spec.col = gray.3(), 
    page.ovlp = 0.25, player = "play", wl = 512, ovlp = 0, 
    wn = "hanning", consistent = TRUE, 
    mp3.meta = list(kbps = 128, samp.rate = 44100, stereo = TRUE), 
    main = NULL, ...)

Arguments

clip	File path to wav file, mp3 file, or wave object. See Details.
interactive	Logical. FALSE displays the first 30 seconds (or more, if page.length is increased) of a spectrogram. TRUE enables the options to page through spectrograms, zoom in time and frequency, play, extract segments, and annotate. See Details.
start.time	Time in file to start reading.
units	Units for start.time. Available units are c("seconds", "minutes", "hours") Defaults to "seconds".
page.length	Duration of page length to view, in seconds. Can be repeatedly halved and doubled within the function.
annotate	Logical, to allow sounds to be highlighted and named on the spectrogram. See Details.
anno	Character, file path to csv containing annotations. Read in only if annotate = TRUE.
channel	Character value in c("left", "right", "both"). Stereo recordings may be viewed as single channel or multi-channel spectrograms. See Details.
output.dir	File path to directory where extracted clips and annotations will be saved, if other than the current working directory.
frq.lim	Initial frequency limits to spectrogram, in kHz. Accepts a 2 element vector. Can be adjusted from within the function.
spec.col	Color (or grayscale) gradient to apply to the spectrogram. See Details.
page.ovlp	Numeric value between 0 and 1. Proportion of page.length to overlap when moving to a new page.
player	Character value specifying an audio player to play the portion of the file corresponding to the visible spectrogram.
wl	Numeric value specifying number of samples per window in the Fourier Transform. Accepts powers of 2: c(128, 256, 512, 1024, 2048)
ovlp	Numeric value specifying window overlap in the Fourier Transform. Specified as a percent between 0 and 99.
wn	Character value specifying window function in the Fourier Transform. Defaults to "hanning"; "hamming" is also implemented.
consistent	Logical, offers a method of maintaining color gradient map from page to page. See Details.
mp3.meta	List of metadata used when paging through mp3 files using mp3splt. kbps is the compression rate, samp.rate is the sample rate, and stereo is logical where TRUE represents both stereo and JntStereo.
main	Optional character object with which to name the spectrogram. If NULL the file name will be used if possible.
...	Additional arguments to spectro

Details

When interactive = TRUE, during the function session the console will display a command menu that prints commands to scroll or nudge to the next/previous page, zoom in/out in the time axis (by halving or doubling the page.length), play the page, save the page as a wave file, change spectrogram parameters (e.g. frq.lim, start.time, wl, ovlp, etc), or quit. An option not presented on-screen is "i" to identify the RMS amplitude in a selected portion of the spectrogram.

viewSpec relies on the WaveIO functions in tuneR, with some modifications. Seeking in wave files and wave objects is accurate to the nearest sample, but the decoding required for mp3 files is "bare bones". Users can install the software mp3splt which will allow seeking in mp3 files very similar (albeit slightly less accurate) to that that exists for wave files. When using mp3splt a short mp3 file the duration of each page is extracted from the clip file or object and saved to the working directory for each new page.

When annotation is set to TRUE the default is to start a new annotation file, unless a csv file containing annotations is specified with the argument anno. Annotation adds the option to annotate to the console command menu, and annotations can be made after typing "a" into the console and pressing enter. Annotation is accomplished by selecting first the upper-left corner of a bounding box around an event in the spectrogram followed by the lower-right corner; after the selection is complete the console will prompt to name the annotation. At a minimum the first annotation must be named, but subsequent annotations will recycle the previous name if a new one is not provided. When in annotation mode the console menu is not shown; instructions for annotation are displayed instead. To exit annotation mode right-click an appropriate number of times, and the console command menu will return. One or more annotations can be deleted by typing "d" in the console after the command menu is displayed, then bounding all annotations to delete in the same manner as if creating a new annotation. Annotations are saved when the command to exit the function is initiated ("q"). Occasionally unrecognized commands may cause the function to exit before annotations can be saved; to guard against losing annotations in such an event, annotations are auto-saved to a file called "TMPannotations.csv" in the working directory, from where they can be retrieved until written over during the next session. Annotation is only possible in one channel per function invocation. The channel will revert to "left" if annotate = TRUE and channel = "both".

Spectrogram colors are adjustable, and users may opt to create their own gradients for display. A few are provided with monitoR including gray.1, gray.2, gray.3, rainbow.1, and topo.1, all of which are based on existing R colors. The gradient is mapped to the values in the spectrogram each time the page is loaded. In gray.2, for example, this means that every page will display the highest dB value as black and the lowest value as white. The highest dB value likely changes from page to page, which can result in successive pages being displayed with wildly different color values. Setting consistent = TRUE (the default) offers a way to minimize this effect, as it artificially weights a single cell in the lower-left corner with a value of 0 dB, which is usually mapped to a black. Under normal circumstances this artificially black cell will not be noticed, but at high magnification it may stand out as erroneous, in which case setting consistent = FALSE may be warranted.

Spectrograms of existing Wave objects are titled with the first argument of the call, which is assumed to be clip.

The default audio player, "play", is the shell command for SoX, the multi-OS media player. Windows will detect the file type and use the default media player with "start", or you can specify one (such as Windows Media Player) with "start wmplayer.exe". On Ubuntu try Rhythmbox ("rhythmbox"), and on Mac OS try afplay ("afplay").

Value

A spectrogram plot. Certain options invoked during the function may write new wave or csv files to the working directory.

Note

The time axis is presented with a fair amount of rounding. It becomes progressively more accurate as the zoom level increases.

Author(s)

Jon Katz, Sasha D. Hafner

See Also

dbUploadAnno

Examples

data(survey)
viewSpec(survey)

## Not run: 
# Start a new annotation file
viewSpec(survey, annotate = TRUE)

# View previous annotations
data(survey_anno)
write.csv(survey_anno, "survey_anno.csv", row.names = FALSE)
viewSpec(survey, interactive = TRUE, annotate = TRUE, anno = "survey_anno.csv", start.time = 5)

# Disable consistent spectrograms
viewSpec(survey, interactive = TRUE, annotate = TRUE, page.length = 10, consistent = FALSE)

## End(Not run)

jonkatz2/monitoR documentation built on March 27, 2024, 4:39 p.m.