nzilbb.labbcat (version 1.0-1)

processWithPraat: Process a set of intervals with Praat.

Description

This function instructs the LaBB-CAT server to invoke Praat for a set of sound intervals, in order to extract acoustic measures.

Usage

processWithPraat(
  labbcat.url,
  match.ids,
  start.offsets,
  end.offsets,
  praat.script,
  window.offset = 0,
  gender.attribute = "participant_gender",
  attributes = NULL,
  no.progress = FALSE
)

Arguments

labbcat.url

URL to the LaBB-CAT instance

match.ids

A vector of annotation IDs, e.g. the MatchId column, or the URL column, of a results set.

start.offsets

The start time in seconds, or a vector of start times.

end.offsets

The end time in seconds, or a vector of end times.

praat.script

Script to run on each match. This may be a single string or a character vector.

window.offset

In many circumstances, you will want some context before and after the sample start/end time. For this reason, you can specify a "window offset" - this is a number of seconds to subtract from the sample start and add to the sample end time, before extracting that part of the audio for processing. For example, if the sample starts at 2.0s and ends at 3.0s, and you set the window offset to 0.5s, then Praat will extract a sample of audio from 1.5s to 3.5s, and do the selected processing on that sample.

gender.attribute

Which participant attribute represents the participant's gender.

attributes

Vector of participant attributes to make available to the script. For example, if you want to use different acoustic parameters depending on what the gender of the speaker is, including the "participant_gender" attribute will make a variable called participant_gender$ available to the praat script, whose value will be the gender of the speaker for that segment.

no.progress

TRUE to supress visual progress bar. Otherwise, progress bar will be shown when interactive().

Value

A data frame of acoustic measures, one row for each matchId.

Details

The exact measurements to return depend on the praat.script that is invoked. This is a Praat script fragment that will run once for each sound interval specified.

There are functions to allow the generation of a number of pre-defined praat scripts for common tasks such as formant, pitch, intensity, and centre of gravity -- see praatScriptFormants, praatScriptCentreOfGravity, praatScriptIntensity and praatScriptPitch.

You can provide your own script, either by building a string with your code, or loading one from a file.

LaBB-CAT prefixes praat.script with code to open a sound file and extract a defined part of it into a Sound object which is then selected.

LaBB-CAT `Remove's this Sound object after the script finishes executing. Any other objects created by the script must be `Remove'd before the end of the script (otherwise Praat runs out of memory during very large batches)

LaBB-CAT assumes that all calls to the function 'print' correspond to fields for export and each field must be printed on its own line. Specifically it scans for lines of the form:

print 'myOutputVariable' 'newline$'

Variables that can be assumed to be already set in the context of the script are:

• windowOffset -- the value used for the Window Offset; how much context to include.

• windowAbsoluteStart -- the start time of the window extracted relative to the start of the original audio file.

• windowAbsoluteEnd -- the end time of the window extracted relative to the start of the original audio file.

• windowDuration -- the duration of the window extracted (including window offset).

• targetAbsoluteStart -- the start time of the target interval relative to the start of the original audio file.

• targetAbsoluteEnd -- the end time of the target interval relative to the start of the original audio file.

• targetStart -- the start time of the target interval relative to the start of the window extracted.

• targetEnd -- the end time of the target interval relative to the start of the window extracted.

• targetDuration -- the duration of the target interval.

• sampleNumber -- the number of the sample within the set of samples being processed.

• sampleName$ -- the name of the extracted/selected Sound object.

See Also

praatScriptFormants

praatScriptCentreOfGravity

praatScriptIntensity

praatScriptPitch

Examples

# NOT RUN {
## define the LaBB-CAT URL
labbcat.url <- "https://labbcat.canterbury.ac.nz/demo/"

## Perform a search
results <- getMatches(labbcat.url, list(segment="I"))

## get F1 and F2 for the mid point of the vowel
formants <- processWithPraat(
       labbcat.url,
       results$MatchId, results$Target.segment.start, results$Target.segment.end,
       praatScriptFormants())

## get first 3 formants at three points during the sample, the mean, min, and max
## pitch, the max intensity, and the CoG using powers 1 and 2 
acoustic.measurements <- processWithPraat(
       labbcat.url,
       results$MatchId, results$Target.segment.start, results$Target.segment.end,
       paste(
           praatScriptFormants(c(1,2,3), c(0.25,0.5,0.75)),
           praatScriptPitch(get.mean=TRUE, get.minimum=TRUE, get.maximum=TRUE),
           praatScriptIntensity(),
           praatScriptCentreOfGravity(powers=c(1.0,2.0))),
       window.offset=0.5)

## execute a custom script loaded form a file
acoustic.measurements <- processWithPraat(
       labbcat.url,
       results$MatchId, results$Target.segment.start, result$Target.segment.end,
       readLines("acousticMeasurements.praat"))
# }