get_trackdata: Get trackdata from loaded emuDB

Description

Extract trackdata information from a loaded emuDB that corresponds to the entries in a segment list.

Usage

get_trackdata(
  emuDBhandle,
  seglist = NULL,
  ssffTrackName = NULL,
  cut = NULL,
  npoints = NULL,
  onTheFlyFunctionName = NULL,
  onTheFlyParams = NULL,
  onTheFlyOptLogFilePath = NULL,
  onTheFlyFunction = NULL,
  resultType = "tibble",
  consistentOutputType = TRUE,
  verbose = TRUE
)

Value

object of type specified with resultType

Arguments

emuDBhandle

emuDB handle as returned by load_emuDB

seglist

tibble, emuRsegs or emusegs object obtained by querying a loaded emuDB

ssffTrackName

The name of track that one wishes to extract (see list_ssffTrackDefinitions for the defined ssffTracks of the emuDB). If the parameter onTheFlyFunctionName is set, then this corresponds to the column name af the AsspDataObj (see wrassp::wrasspOutputInfos[[onTheFlyFunctionName]]$tracks and wrasspOutputInfos - NOTE: library(wrassp) might be necessary to access the wrasspOutputInfos object without the wrassp:: prefix). If the parameter onTheFlyFunctionName is set and this one isn't, then per default the first track listed in the wrassp::wrasspOutputInfos is chosen (wrassp::wrasspOutputInfos[[onTheFlyFunctionName]]$tracks[1]).

get_trackdata has so called constant track names that are always available for every emuDB. The constant track names are:

"MEDIAFILE_SAMPLES": refers to the audio sample values specified by the "mediafileExtension" entry of the DBconfig.json

cut

An optional cut time for segment data, ranges between 0 and 1, a value of 0.5 will extract data only at the segment midpoint.

npoints

An optional number of points to retrieve for each segment or event. For segments this requires the cut parameter to be set; if this is the case, then data is extracted around the resulting cut time. For events data is extracted around the event time. If npoints is an odd number, the samples are centered around the cut-time-sample; if not, they are skewed to the right by one sample.

onTheFlyFunctionName

Name of wrassp function that will perform the on-the-fly calculation (see ?wrassp for a list of all the signal processing functions wrassp provides)

onTheFlyParams

A pairlist of parameters that will be given to the function passed in by the onTheFlyFunctionName parameter. This list can easily be generated by applying the formals function to the on-the-fly function name and then setting the according parameter one wishes to change.

onTheFlyOptLogFilePath

Path to optional log file for on-the-fly function

onTheFlyFunction

pass in a function pointer. This function will be called with the path to the current media file. It is required that the function returns a tibble/data.frame like object that contains a column called frame_time that specifies the time point of each row. get_trackdata will then extract the rows belonging to the current segment. This allows users to code their own function to be used with get_trackdata and allows for most data formats to be used within an emuDB.

resultType

Specify class of returned object. Either "emuRtrackdata", "trackdata" or "tibble" == the default (see trackdata, emuRtrackdata and tibble for details about these objects).

consistentOutputType

Prevent converting the output object to a data.frame depending on the npoint and cut arguments (only applies to output type "trackdata"). Set to FALSE if the following legacy emu.track output conversion behaviour is desired: If the cut parameter is not set (the default) an object of type trackdata is returned. If cut is set and npoints is not, or the seglist is of type event and npoints is not set, a data.frame is returned (see the consistentOutputType to change this behaviour).

verbose

Show progress bars and further information

Details

This function utilizes the wrassp package for signal processing and SSFF/audio file handling. It reads time relevant data from a given segment list (emuRsegs or emusegs), extracts the specified trackdata and places it into a trackdata object (analogous to the deprecated emu.track). This function replaces the deprecated emu.track function. Note that an warning is issued if the bundles in the emuRsegs or emusegs object have in-homogeneous sampling rates as this could lead to inconsistent/erroneous trackdata, emuRtrackdata or tibble result objects. For more information on the structural elements of an emuDB see the signal data extraction chapter of the EMU-SDMS manual (https://ips-lmu.github.io/The-EMU-SDMS-Manual/chap-sigDataExtr.html).

Examples

Run this code

if (FALSE) {

##################################
# prerequisite: loaded ae emuDB 
# (see ?load_emuDB for more information)

# query loaded "ae" emuDB for all "i:" segments of the "Phonetic" level
sl = query(emuDBhandle = ae, 
           query = "Phonetic == i:")

# get the corresponding formant trackdata
td = get_trackdata(emuDBhandle = ae, 
                   seglist = sl, 
                   ssffTrackName = "fm")

# get the corresponding F0 trackdata
# as there is no F0 ssffTrack defined in the "ae" emuDB we will 
# calculate the necessary values on-the-fly
td = get_trackdata(emuDBhandle = ae, 
                   seglist = sl, 
                   onTheFlyFunctionName = "ksvF0")
                   
}