viewSpec: Interactively View and Annotate Spectrograms
In monitoR: Acoustic Template Detection in R

Description Usage Arguments Details Value Note Author(s) See Also Examples

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.

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

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

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

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

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

Jon Katz, Sasha D. Hafner

dbUploadAnno

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)