Package 'pladdrr'

Description

$ method for Sound constructor (enables Sound$create_tone(), etc.)

Usage

## S3 method for class 'sound_constructor'
x$name

Arguments

Value

The requested static method function

Examples

tone_fn <- Sound$create_tone
sound <- tone_fn(frequency = 220, duration = 0.2, sampling_rate = 8000)

Description

$ method for TextGrid constructor (enables TextGrid$new(), TextGrid$create())

Usage

## S3 method for class 'textgrid_constructor'
x$name

Arguments

Value

The requested static method function

Examples

create_fn <- TextGrid$create
tg <- create_fn(0, 1, "words")

Description

Aggregate extracted measurements by interval label (e.g., phoneme, word). Common workflow after extract_measurements().

Usage

aggregate_measurements(
  measurements,
  by = "label",
  stats = c("mean", "sd", "n")
)

Arguments

Value

Data frame with aggregated statistics.

Examples

results <- data.frame(
  label = c("a", "a", "e", "e"),
  f0 = c(150, 155, 210, 205)
)
vowel_stats <- aggregate_measurements(
  measurements = results,
  by = "label",
  stats = c("mean", "sd", "n")
)

Description

Creates a new AmplitudeTier object with no points.

Usage

amplitude_tier_create(tmin, tmax)

Arguments

Value

An AmplitudeTier object

Examples

tier <- amplitude_tier_create(0, 1)
tier$add_point(0.5, 0.8)

Description

Extracts amplitude values from a Sound at the times specified by a PointProcess.

Usage

amplitude_tier_from_point_process(point_process, sound)

Arguments

Value

An AmplitudeTier object with amplitudes at each point time

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.5, sampling_rate =
 16000)
pp <- sound$to_point_process_periodic_cc(75, 600)
tier <- amplitude_tier_from_point_process(pp, sound)
tier$get_number_of_points()

Description

A Praat AmplitudeTier: sound pressure amplitude in Pascals as a function of time.

Arguments

Details

An AmplitudeTier stores amplitude as a sparse sequence of (time, value) points rather than a dense signal, with linear interpolation between points. It's the amplitude counterpart to an IntensityTier (which stores dB instead of Pa), and the two convert into each other. A common use is pulling amplitude at glottal pulse times (from a PointProcess) to compute shimmer.

Value

An AmplitudeTier object.

Usage

tier <- amplitude_tier_create(0, 1)
tier <- amplitude_tier_from_point_process(point_process, sound)
tier <- intensity_tier_to_amplitude_tier(intensity_tier)

Query methods

• get_start_time(), get_end_time() - time domain in seconds

• get_number_of_points() - number of (time, value) points

• get_time_from_index(index) - time at a 1-based point index

• get_value_at_index(index) - amplitude at a 1-based point index (Pa)

• get_value_at_time(time) - interpolated amplitude at a time (Pa)

Modification

• add_point(time, value) - add a (time, value) point

• remove_point(index) - remove the point at a 1-based index

Conversion and export

• to_intensity_tier(threshold_db) - convert amplitude to an IntensityTier

• as_data_frame() - points as a data frame with time and amplitude_pa columns

• save(path) - write to file

See Also

[amplitude_tier_create], [amplitude_tier_from_point_process], [intensity_tier_to_amplitude_tier]

Examples

tier <- amplitude_tier_create(0, 1)
tier$add_point(0.25, 0.5)
tier$add_point(0.75, 0.8)
tier$get_number_of_points()
tier$get_value_at_time(0.5)

Description

Process multiple audio files in parallel across multiple CPU cores, instead of processing them sequentially.

Usage

analyze_files_parallel(
  files,
  analysis_func,
  n_cores = NULL,
  threads_per_worker = NULL,
  ...
)

Arguments

Details

This function distributes batch analysis across worker processes. Each file is: 1. Loaded as a Sound object 2. Processed by analysis_func 3. Results collected and returned

Value

List of results from analysis_func, one per file

Examples

audio_dir <- tempfile("audio_")
dir.create(audio_dir)
tone <- Sound$create_tone(frequency = 150, duration = 0.3, sampling_rate =
 16000)
tone$save(file.path(audio_dir, "tone1.wav"))
files <- list.files(audio_dir, pattern = "\\.wav$", full.names = TRUE)

analyze_pitch <- function(sound) {
  pitch <- sound$to_pitch()
  list(
    mean_f0 = pitch$get_mean(0, 0, "hertz"),
    sd_f0 = pitch$get_standard_deviation(0, 0, "hertz")
  )
}

# n_cores = 1 keeps this a single-process example (CRAN-safe)
results <- analyze_files_parallel(files, analyze_pitch, n_cores = 1)

Description

Apply a user-defined C++ transform function to sample values, compiled via RcppXPtrUtils, instead of calling an R callback per sample. Requires the RcppXPtrUtils package.

Usage

apply_transform_xptr(sound, transform_func)

Arguments

Details

**ADVANCED API** - Requires RcppXPtrUtils package.

The transform function receives sample amplitude and returns transformed amplitude. Common transforms:

• Clipping: 'x > threshold ? threshold : (x < -threshold ? -threshold : x)'

• Soft clipping: 'tanh(x * gain)'

• Rectification: 'fabs(x)'

• Squaring: 'x * x'

Value

Sound object with transform function applied

Examples

# Compiling a C++ transform function takes a few seconds
if (requireNamespace("RcppXPtrUtils", quietly = TRUE)) {
  soft_clip <- RcppXPtrUtils::cppXPtr(
    "double softclip(double x) { return tanh(x * 2.0); }",
    depends = character()
  )

sound <- Sound$create_tone(frequency = 220, duration = 0.3, sampling_rate =
 16000)
  clipped <- apply_transform_xptr(sound, soft_clip)
}

Description

Apply a user-defined C++ window function to a Sound object, compiled via RcppXPtrUtils, instead of calling an R callback per sample. Requires the RcppXPtrUtils package.

Usage

apply_window_xptr(sound, window_func)

Arguments

Details

**ADVANCED API** - Requires RcppXPtrUtils package.

The window function receives normalized time (0 to 1) and returns a multiplier. Common window functions:

• Hamming: '0.54 - 0.46 * cos(2 * M_PI * t)'

• Hanning: '0.5 * (1 - cos(2 * M_PI * t))'

• Gaussian: 'exp(-18 * (t - 0.5)^2)'

• Triangular: '1 - fabs(2*t - 1)'

Value

Sound object with window function applied

Examples

# Compiling a C++ window function takes a few seconds
if (requireNamespace("RcppXPtrUtils", quietly = TRUE)) {
  gauss_window <- RcppXPtrUtils::cppXPtr(
    "double gauss(double t) {
      double x = t - 0.5;
      return exp(-18.0 * x * x);
    }",
    depends = character()
  )

  # Verify signature (optional but recommended)
  RcppXPtrUtils::checkXPtr(gauss_window, "double", "double")

sound <- Sound$create_tone(frequency = 220, duration = 0.3, sampling_rate =
 16000)
  windowed <- apply_window_xptr(sound, gauss_window)
}

Description

'as.data.frame()' methods for Praat object classes that expose their data as flat data frames (long format for 2-D matrix-like objects, one row per sample/point/frame for 1-D tiers and tracks).

Usage

## S3 method for class 'Discriminant'
as.data.frame(x, ...)

## S3 method for class 'Electroglottogram'
as.data.frame(x, ...)

## S3 method for class 'FormantModeler'
as.data.frame(x, ...)

## S3 method for class 'PCA'
as.data.frame(x, ...)

## S3 method for class 'PowerCepstrogram'
as.data.frame(x, ...)

## S3 method for class 'BarkSpectrogram'
as.data.frame(x, ...)

## S3 method for class 'Cepstrum'
as.data.frame(x, row.names = NULL, optional = FALSE, power = FALSE, ...)

## S3 method for class 'Cochleagram'
as.data.frame(x, ...)

## S3 method for class 'DTW'
as.data.frame(x, ...)

## S3 method for class 'KlattGrid'
as.data.frame(x, ...)

## S3 method for class 'LPC'
as.data.frame(x, ...)

## S3 method for class 'LongSound'
as.data.frame(x, ...)

## S3 method for class 'Matrix'
as.data.frame(x, ...)

## S3 method for class 'MelSpectrogram'
as.data.frame(x, ...)

## S3 method for class 'VocalTract'
as.data.frame(x, ...)

Arguments

Value

A data.frame. Column names vary by class; see each class's $as_data_frame() method or the corresponding 'autoplot.*' method for the exact columns used.

Examples

sound <- Sound$create_tone(frequency = 220, duration = 0.2, sampling_rate =
 16000)
cepstrum <- sound$to_cepstrum()
df <- as.data.frame(cepstrum)
head(df)

Description

S3 method for converting R6 Formant objects to data frames. Delegates to the R6 '$as_data_frame()' method.

Usage

## S3 method for class 'Formant'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data.table (inherits from data.frame) in long format, one row per (frame, formant number): columns 'time', 'formant' (1-based formant number), 'frequency' (Hz), 'bandwidth' (Hz). Matches 'as.data.frame.FormantPath()'.

Examples

sound <- Sound$create_tone(frequency = 220, duration = 0.3, sampling_rate =
 16000)
formant <- sound$to_formant_burg()
df <- as.data.frame(formant)
head(df)

Description

S3 method for converting R6 Intensity objects to data frames. Delegates to the R6 '$as_data_frame()' method.

Usage

## S3 method for class 'Intensity'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data.table (inherits from data.frame) with time and intensity columns

Examples

sound <- Sound$create_tone(frequency = 220, duration = 0.3, sampling_rate =
 16000)
intensity <- sound$to_intensity()
df <- as.data.frame(intensity)
head(df)

Description

S3 method for converting R6 Pitch objects to data frames. Delegates to the R6 '$as_data_frame()' method.

Usage

## S3 method for class 'Pitch'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'PointProcess'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'TextGrid'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'MFCC'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'LFCC'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data.table (inherits from data.frame) with pitch measurements

Functions

• as.data.frame(PointProcess): Convert PointProcess to data.frame

• as.data.frame(TextGrid): Convert TextGrid to data.frame

• as.data.frame(MFCC): Convert MFCC to data.frame

• as.data.frame(LFCC): Convert LFCC to data.frame

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.3, sampling_rate =
 16000)
pitch <- sound$to_pitch()
df <- as.data.frame(pitch)
head(df)

Description

Convert praat_formant to data.frame

Usage

## S3 method for class 'praat_formant'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

The values data.table (inherits from data.frame) from the formant object

Examples

x <- list(values = data.frame(
  time = c(0.1, 0.2), formant_number = c(1, 1),
  frequency = c(500, 520), bandwidth = c(80, 82)
))
class(x) <- "praat_formant"
as.data.frame(x)

Description

Convert praat_intensity to data.frame

Usage

## S3 method for class 'praat_intensity'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

The values data.table (inherits from data.frame) from the intensity object

Examples

x <- list(values = data.frame(time = c(0.1, 0.2), intensity_db = c(65.2,
 66.1)))
class(x) <- "praat_intensity"
as.data.frame(x)

Description

Converts a praat_sound object to a data frame with time and amplitude columns. This is useful for plotting and further analysis in R.

Usage

## S3 method for class 'praat_sound'
as.data.frame(x, ...)

Arguments

Value

A data.table (inherits from data.frame) with two columns:

time

Time in seconds

amplitude

Amplitude values

Examples

values <- sin(2 * pi * 220 * seq(0, 0.1, length.out = 1000))
snd <- create_sound_from_values(values, sampling_rate = 10000)
df <- as.data.frame(snd)
head(df)

Description

S3 method for converting R6 Sound objects to data frames. Delegates to the R6 '$as_data_frame()' method.

Usage

## S3 method for class 'Sound'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data.table (inherits from data.frame) with time, channel, and value columns

Examples

sound <- Sound$create_tone(frequency = 220, duration = 0.1, sampling_rate =
 8000)
df <- as.data.frame(sound)
head(df)

Description

ggplot2-style autoplot() and autolayer() methods for Praat objects. These provide a tidyverse-idiomatic interface for plotting, allowing flexible composition of multi-object visualizations.

Usage

## S3 method for class 'Sound'
autoplot(object, from_time = NULL, to_time = NULL, color = "steelblue", ...)

## S3 method for class 'Sound'
autolayer(object, from_time = NULL, to_time = NULL, color = "steelblue", ...)

## S3 method for class 'Pitch'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  color = "darkgreen",
  show_voicing = FALSE,
  ...
)

## S3 method for class 'Pitch'
autolayer(
  object,
  from_time = NULL,
  to_time = NULL,
  color = "darkgreen",
  geom = c("line", "point"),
  ...
)

## S3 method for class 'Formant'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  max_formant = 3,
  colors = NULL,
  ...
)

## S3 method for class 'Formant'
autolayer(
  object,
  from_time = NULL,
  to_time = NULL,
  max_formant = 3,
  colors = NULL,
  ...
)

## S3 method for class 'Intensity'
autoplot(object, from_time = NULL, to_time = NULL, color = "darkorange", ...)

## S3 method for class 'Intensity'
autolayer(object, from_time = NULL, to_time = NULL, color = "darkorange", ...)

## S3 method for class 'Spectrogram'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  from_freq = NULL,
  to_freq = NULL,
  dynamic_range = 70,
  ...
)

## S3 method for class 'Spectrogram'
autolayer(
  object,
  from_time = NULL,
  to_time = NULL,
  from_freq = NULL,
  to_freq = NULL,
  dynamic_range = 70,
  ...
)

## S3 method for class 'Spectrum'
autoplot(
  object,
  from_freq = NULL,
  to_freq = NULL,
  log_freq = FALSE,
  color = "navy",
  ...
)

## S3 method for class 'Spectrum'
autolayer(object, from_freq = NULL, to_freq = NULL, color = "navy", ...)

## S3 method for class 'Ltas'
autoplot(
  object,
  from_freq = NULL,
  to_freq = NULL,
  log_freq = FALSE,
  color = "darkred",
  ...
)

## S3 method for class 'Ltas'
autolayer(object, from_freq = NULL, to_freq = NULL, color = "darkred", ...)

## S3 method for class 'Harmonicity'
autoplot(object, from_time = NULL, to_time = NULL, color = "darkviolet", ...)

## S3 method for class 'Harmonicity'
autolayer(object, from_time = NULL, to_time = NULL, color = "darkviolet", ...)

## S3 method for class 'PointProcess'
autoplot(object, from_time = NULL, to_time = NULL, color = "black", ...)

## S3 method for class 'PointProcess'
autolayer(
  object,
  from_time = NULL,
  to_time = NULL,
  color = "black",
  ymin = 0,
  ymax = 1,
  ...
)

## S3 method for class 'PowerCepstrum'
autoplot(
  object,
  from_quefrency = NULL,
  to_quefrency = NULL,
  color = "darkblue",
  mark_peak = TRUE,
  ...
)

## S3 method for class 'PowerCepstrum'
autolayer(
  object,
  from_quefrency = NULL,
  to_quefrency = NULL,
  color = "darkblue",
  ...
)

## S3 method for class 'TextGrid'
autoplot(object, ...)

## S3 method for class 'TextGrid'
autolayer(
  object,
  tier = 1,
  from_time = NULL,
  to_time = NULL,
  color = "steelblue",
  alpha = 0.3,
  ...
)

## S3 method for class 'AmplitudeTier'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  color = "darkred",
  garnish = TRUE,
  ...
)

## S3 method for class 'AmplitudeTier'
autolayer(object, from_time = NULL, to_time = NULL, color = "darkred", ...)

## S3 method for class 'DurationTier'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  color = "steelblue",
  garnish = TRUE,
  ...
)

## S3 method for class 'DurationTier'
autolayer(object, from_time = NULL, to_time = NULL, color = "steelblue", ...)

## S3 method for class 'IntensityTier'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  color = "darkgreen",
  garnish = TRUE,
  ...
)

## S3 method for class 'IntensityTier'
autolayer(object, from_time = NULL, to_time = NULL, color = "darkgreen", ...)

## S3 method for class 'PitchTier'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  color = "blue",
  garnish = TRUE,
  ...
)

## S3 method for class 'PitchTier'
autolayer(object, from_time = NULL, to_time = NULL, color = "blue", ...)

## S3 method for class 'FormantTier'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  max_formant = 3L,
  colors = NULL,
  time_step = 0.005,
  style = c("speckle", "line"),
  garnish = TRUE,
  ...
)

## S3 method for class 'FormantTier'
autolayer(
  object,
  from_time = NULL,
  to_time = NULL,
  max_formant = 3L,
  colors = NULL,
  time_step = 0.005,
  style = c("speckle", "line"),
  ...
)

## S3 method for class 'FormantGrid'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  max_formant = 3L,
  colors = NULL,
  garnish = TRUE,
  ...
)

## S3 method for class 'FormantGrid'
autolayer(
  object,
  from_time = NULL,
  to_time = NULL,
  max_formant = 3L,
  colors = NULL,
  ...
)

## S3 method for class 'FormantPath'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  max_formant = 3L,
  colors = NULL,
  show_candidates = TRUE,
  garnish = TRUE,
  ...
)

## S3 method for class 'FormantPath'
autolayer(
  object,
  from_time = NULL,
  to_time = NULL,
  max_formant = 3L,
  colors = NULL,
  show_candidates = FALSE,
  ...
)

## S3 method for class 'Excitation'
autoplot(object, garnish = TRUE, color = "darkred", ...)

## S3 method for class 'Excitation'
autolayer(object, color = "darkred", ...)

## S3 method for class 'ComplexSpectrogram'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  from_freq = NULL,
  to_freq = NULL,
  dynamic_range = 70,
  garnish = TRUE,
  show_phase = FALSE,
  ...
)

## S3 method for class 'ComplexSpectrogram'
autolayer(
  object,
  from_time = NULL,
  to_time = NULL,
  from_freq = NULL,
  to_freq = NULL,
  dynamic_range = 70,
  ...
)

## S3 method for class 'Cepstrum'
autoplot(object, power = FALSE, garnish = TRUE, color = "darkblue", ...)

## S3 method for class 'Cepstrum'
autolayer(object, power = FALSE, color = "darkblue", ...)

## S3 method for class 'Cochleagram'
autoplot(object, from_time = NULL, to_time = NULL, garnish = TRUE, ...)

## S3 method for class 'Cochleagram'
autolayer(object, from_time = NULL, to_time = NULL, ...)

## S3 method for class 'PowerCepstrogram'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  quefrency_range = NULL,
  garnish = TRUE,
  ...
)

## S3 method for class 'PowerCepstrogram'
autolayer(
  object,
  from_time = NULL,
  to_time = NULL,
  quefrency_range = NULL,
  ...
)

## S3 method for class 'MFCC'
autoplot(object, coefficient_range = NULL, garnish = TRUE, ...)

## S3 method for class 'MFCC'
autolayer(object, coefficient_range = NULL, ...)

## S3 method for class 'LFCC'
autoplot(object, coefficient_range = NULL, garnish = TRUE, ...)

## S3 method for class 'LFCC'
autolayer(object, coefficient_range = NULL, ...)

## S3 method for class 'BarkSpectrogram'
autoplot(object, garnish = TRUE, ...)

## S3 method for class 'BarkSpectrogram'
autolayer(object, ...)

## S3 method for class 'MelSpectrogram'
autoplot(object, garnish = TRUE, ...)

## S3 method for class 'MelSpectrogram'
autolayer(object, ...)

## S3 method for class 'Matrix'
autoplot(
  object,
  x_col = NULL,
  y_col = NULL,
  fill_col = NULL,
  garnish = TRUE,
  ...
)

## S3 method for class 'Matrix'
autolayer(object, x_col = NULL, y_col = NULL, fill_col = NULL, ...)

## S3 method for class 'PCA'
autoplot(object, type = c("scree", "scores", "both"), garnish = TRUE, ...)

## S3 method for class 'PCA'
autolayer(object, ...)

## S3 method for class 'Discriminant'
autoplot(object, type = c("scree", "scores", "both"), garnish = TRUE, ...)

## S3 method for class 'Discriminant'
autolayer(object, ...)

## S3 method for class 'FormantModeler'
autoplot(object, from_track = 1L, to_track = 0L, garnish = TRUE, ...)

## S3 method for class 'FormantModeler'
autolayer(object, from_track = 1L, to_track = 0L, ...)

## S3 method for class 'Electroglottogram'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  color = "black",
  garnish = TRUE,
  ...
)

## S3 method for class 'Electroglottogram'
autolayer(object, from_time = NULL, to_time = NULL, color = "black", ...)

## S3 method for class 'LongSound'
autoplot(
  object,
  from_time = 0,
  to_time = 2,
  color = "black",
  garnish = TRUE,
  ...
)

## S3 method for class 'LongSound'
autolayer(object, from_time = 0, to_time = 2, color = "black", ...)

## S3 method for class 'DTW'
autoplot(object, garnish = TRUE, alpha_path = 0.8, ...)

## S3 method for class 'DTW'
autolayer(object, alpha_path = 0.8, ...)

## S3 method for class 'Polygon'
autoplot(
  object,
  garnish = TRUE,
  fill_polygon = FALSE,
  color = "black",
  fill_color = "grey80",
  ...
)

## S3 method for class 'Polygon'
autolayer(object, color = "black", ...)

## S3 method for class 'VocalTract'
autoplot(object, garnish = TRUE, plot_type = c("area", "line"), ...)

## S3 method for class 'VocalTract'
autolayer(object, ...)

## S3 method for class 'LPC'
autoplot(object, frame = 1L, garnish = TRUE, color = "darkred", ...)

## S3 method for class 'LPC'
autolayer(object, frame = 1L, color = "darkred", ...)

## S3 method for class 'KlattGrid'
autoplot(
  object,
  from_time = NULL,
  to_time = NULL,
  formant_type = c("all", "oral", "nasal", "frication", "tracheal", "delta"),
  max_formant = 6L,
  garnish = TRUE,
  ...
)

## S3 method for class 'KlattGrid'
autolayer(
  object,
  from_time = NULL,
  to_time = NULL,
  formant_type = c("oral", "nasal", "frication", "tracheal", "delta"),
  max_formant = 6L,
  ...
)

Arguments

Details

The autoplot/autolayer pattern enables flexible plot composition:

• autoplot(object) - Creates a complete ggplot

• autolayer(object) - Returns a layer to add to existing plots

This allows combining multiple objects:

autoplot(spectrogram) +
  autolayer(formant, max_formant = 3) +
  autolayer(pitch, color = "blue")

Value

A ggplot2 object

Examples

sound <- Sound$create_tone(frequency = 220, duration = 0.5, sampling_rate =
 16000)
p <- ggplot2::autoplot(sound)

pitch <- sound$to_pitch()
p2 <- ggplot2::autoplot(pitch)

Description

A Bark-scale spectrogram, used in psychoacoustic and perceptual analysis of speech.

Usage

BarkSpectrogram(.xptr = NULL)

Arguments

Value

A BarkSpectrogram object.

Examples

snd <- Sound$create_tone(frequency = 150, duration = 0.3)
bark <- snd$to_bark_spectrogram()

# Export as matrix
mat <- bark$as_matrix()

Description

Process multiple audio files with a custom function. This replaces Praat's pattern of creating Strings objects and looping over files.

Usage

batch_process(
  directory,
  pattern = "\\.wav$",
  func,
  recursive = FALSE,
  parallel = FALSE,
  ncores = NULL,
  progress = TRUE,
  ...
)

Arguments

Value

Data frame with results from all files

Examples

audio_dir <- tempfile("audio_")
dir.create(audio_dir)
tone <- Sound$create_tone(frequency = 150, duration = 0.3, sampling_rate =
 16000)
tone$save(file.path(audio_dir, "tone1.wav"))

results <- batch_process(
  directory = audio_dir,
  pattern = "\\.wav$",
  progress = FALSE,
  func = function(sound) {
    pitch <- sound$to_pitch()
    list(
      mean_f0 = pitch$get_mean(from_time = 0, to_time = 0, unit = "hertz"),
sd_f0 = pitch$get_standard_deviation(from_time = 0, to_time = 0, unit =
 "hertz")
    )
  }
)

Description

Functions for batch processing audio files, pairing Sound/TextGrid files, and extracting measurements across multiple files. These utilities replace the need for Praat's Strings and Table objects with R-idiomatic workflows.

Value

This is a documentation-only overview; see the individual functions (batch_process, create_file_list, extract_measurements, extract_measurements_custom, aggregate_measurements) for their return values.

Examples

# See individual functions, e.g. ?batch_process, ?create_file_list

Description

Compare performance of parallel vs sequential processing. Useful for determining optimal core count for your workload.

Usage

benchmark_parallel(files, analysis_func, core_counts = c(1, 2, 4))

Arguments

Value

Data frame with timing results

Examples

audio_dir <- tempfile("audio_")
dir.create(audio_dir)
tone <- Sound$create_tone(frequency = 150, duration = 0.3, sampling_rate =
 16000)
tone$save(file.path(audio_dir, "tone1.wav"))
files <- list.files(audio_dir, pattern = "\\.wav$", full.names = TRUE)

# CRAN examples should use at most 2 cores
results <- benchmark_parallel(
  files,
  function(s) s$to_pitch()$get_mean(0, 0, "hertz"),
  core_counts = c(1, 2)
)
print(results)

Description

Compute the 5 Harmonicity objects used by VQ's multiband HNR workflow once, then reuse them across repeated interval queries with [multiband_hnr_stats()].

Usage

build_multiband_harmonicity(
  sound,
  bands = c(0, 500, 1500, 2500, 3500),
  time_step = 0.005,
  min_pitch = 75
)

Arguments

Details

Use this when the same 'Sound' is queried over many '[from_time, to_time]' windows, e.g. a TextGrid with multiple voiced intervals. The expensive band-pass filtering and Harmonicity computation are done once; only the summary stats are repeated.

Value

Named list of 5 'Harmonicity' objects: 'full', 'band500', 'band1500', 'band2500', 'band3500' (or names derived from custom bands).

References

- VQ_measurements_V2.praat (Voice Quality measurements) - Maryn & Weenink (2015) - Multi-band HNR for voice quality

See Also

multiband_hnr_stats and calculate_multiband_hnr_ultra

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.5, sampling_rate =
 16000)

built <- build_multiband_harmonicity(sound)
hnr_full <- multiband_hnr_stats(built)

Description

Computes the smoothed cepstral peak prominence (CPPS, in dB) of a 'Sound' — a widely used acoustic measure of voice quality/breathiness. It performs the whole PowerCepstrogram-then-CPPS pipeline in a single call and returns the same value as 'sound$to_powercepstrogram(...)$get_cpps(...)' with matching parameters. You supply the analysis parameters directly and are responsible for passing valid values (see the arguments below).

Usage

calculate_cpps_fast(
  sound,
  subtract_tilt = TRUE,
  time_averaging_window = 0.001,
  quefrency_averaging_window = 5e-04,
  pitch_floor = 60,
  pitch_ceiling = 333.3,
  delta_f0 = 0.05,
  interpolation = "parabolic",
  qstart_fit = 0.003,
  qend_fit = 0.04,
  trend_line_type = "straight",
  fit_method = "robust",
  cepstrogram_pitch_floor = 60,
  time_step = 0.002,
  max_frequency = 5000,
  pre_emphasis_from = 50
)

Arguments

Details

Use this when analysing many files in a loop. For interactive or one-off use, the object API ('sound$to_powercepstrogram(...)$get_cpps(...)') is equivalent and validates its inputs more forgivingly; this function skips that validation, so pass well-formed parameters.

This is a **CPPS** helper: it builds a whole-sound PowerCepstrogram and then computes a smoothed peak-prominence summary. If you need a single-interval **CPP** value that matches Praat's 'To PowerCepstrum' workflow, extract the interval, convert it to a Spectrum, and call 'to_power_cepstrum()$get_peak_prominence()' instead. That path is much cheaper and is not the same metric.

Value

A single numeric CPPS value in dB.

Defaults differ from Praat's

These defaults follow the AVQI/clinical convention, **not** the defaults of Praat's 'PowerCepstrogram: Get CPPS...' dialog. On a 1 s test signal the two parameter sets give 9.92 dB and 4.82 dB respectively — a different measurement, not a rounding difference. Pass the Praat values explicitly to reproduce a Praat run:

| parameter | Praat default | pladdrr default | |—|—|—| | 'time_averaging_window' | 0.02 | 0.001 | | 'quefrency_averaging_window' | 0.0005 | 0.0005 | | 'pitch_floor' | 60 | 60 | | 'pitch_ceiling' | 330 | 333.3 | | 'qstart_fit' | 0.001 | 0.003 | | 'qend_fit' | 0.05 | 0.04 | | 'trend_line_type' | '"exponential"' | '"straight"' | | 'fit_method' | '"robust slow"' | '"robust"' |

The ‘fit_method' difference is deliberate beyond convention: Praat’s '"robust slow"' (Theil-Sen) is not reproducible — see the 'fit_method' argument.

Examples

sound <- Sound(system.file("extdata", "test.wav", package = "pladdrr"))

# Full-file CPPS calls on the 60 s demo file are CPU-heavy (> 5 s under
# R CMD check), so they live in \donttest{} (still run under
# --run-donttest).

# One-call CPPS with the default (AVQI-convention) parameters
calculate_cpps_fast(sound)

# The object API gives the identical value
pcep <- sound$to_powercepstrogram(60, 0.002, 5000, 50)
pcep$get_cpps()

# Reproduce Praat's own "Get CPPS..." defaults
calculate_cpps_fast(sound,
  time_averaging_window = 0.02, pitch_ceiling = 330,
  qstart_fit = 0.001, qend_fit = 0.05,
  trend_line_type = "exponential", fit_method = "least_squares"
)

# Single-interval CPP is a different, cheaper path
segment <- sound$extract_part(0, 0.5)
cpp <- segment$to_spectrum()$to_power_cepstrum()$get_peak_prominence(
  60, 333.3, "parabolic", 0.001, 0.05, "exponential decay", "robust slow"
)

Description

Computes CPPS from a 'Sound' in a single C++ call, building the PowerCepstrogram internally so no intermediate R object is created.

Returns the same value as calculate_cpps_fast() and as sound$to_powercepstrogram(...)$get_cpps(...). The three paths cost about the same: the R/C++ boundary crossing is negligible next to the per-frame trend fit, so pick whichever reads best at the call site.

Usage

calculate_cpps_ultra(
  sound,
  time_averaging_window = 0.001,
  quefrency_averaging_window = 5e-04,
  pitch_floor = 60,
  pitch_ceiling = 333.3,
  subtract_trend = TRUE,
  time_step = 0.002,
  max_quefrency = 0.04,
  tolerance = 0.05,
  interpolation = "parabolic",
  tilt_line_quefrency = 0.003,
  line_type = "straight",
  fit_method = "robust",
  pre_emphasis_from = 50,
  max_frequency = 5000
)

Arguments

Details

Implements the complete CPPS pipeline in one C++ call, following the approach used in AVQI v2.03 and v3.01: PowerCepstrogram creation and CPPS extraction are consolidated, and no intermediate R object is allocated.

This does **not** make it meaningfully cheaper than the other CPPS entry points: the per-frame robust trend fit ('SlopeSelector::getSlope_Siegel') dominates CPPS runtime and is shared by every path; consolidating the PowerCepstrogram creation only removes the R/C++ boundary crossing, which is a small fraction of the total cost. Treat the choice as a matter of call-site convenience, not performance.

The defaults here match calculate_cpps_fast() and therefore also deviate from Praat's dialog defaults — see the "Defaults differ from Praat's" section of calculate_cpps_fast.

This is still a **CPPS** helper. For a single-interval **CPP** measurement, use the segment's 'Spectrum -> PowerCepstrum -> get_peak_prominence()' path instead of 'calculate_cpps_ultra()'. It is both cheaper and closer to the Praat workflow used by voice-quality scripts that query one interval at a time.

**Use Cases:** - AVQI v2.03/v3.01 implementation - High-throughput voice quality analysis - CPPS monitoring in latency-sensitive pipelines

Value

Numeric CPPS value in dB

Algorithm choice

Not applicable — this function is pitch-independent. It builds a 'PowerCepstrogram' directly from the Sound ('Sound_to_PowerCepstrogram()') and never extracts a 'Pitch' object, so there is no AC/CC or 'veryAccurate' choice to document here. See the CPPS parameter default table in '/CLAUDE.md' for the (non-pitch) parameters that do vary by caller, and the Tier 4 Ultra algorithm table in 'inst/agents/AGENT_GUIDE.md' for how this compares to the pitch-based Ultra functions.

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.5, sampling_rate =
 16000)

# Tier 4 Ultra (same defaults as calculate_cpps_fast)
cpps <- calculate_cpps_ultra(sound)

# Should match calculate_cpps_fast() within 0.01 dB
cpps_fast <- calculate_cpps_fast(sound)
all.equal(cpps, cpps_fast, tolerance = 0.01)

Description

Vectorized calculation of interval durations (end - start). Uses SIMD instructions on large interval counts.

Usage

calculate_durations_simd_bridge(start_times, end_times)

Arguments

Value

Numeric vector of durations

Examples

starts <- c(0, 1, 2.5)
ends <- c(0.8, 2, 3.2)
calculate_durations_simd_bridge(starts, ends)

Description

Performs pitch extraction AND statistic calculation entirely in C++, avoiding intermediate R6 object creation and the separate 'to_pitch_cc()' and 'get_maximum()' calls.

This is a **Tier 4 "Ultra"** function for batch DSI (Dysphonia Severity Index) calculations where maximum F0 is the FH (Highest Frequency) component.

Usage

calculate_f0_stats_ultra(
  sound,
  stat,
  min_pitch = 75,
  max_pitch = 600,
  time_step = 0,
  voicing_threshold = 0.45
)

Arguments

Value

Single numeric value of the requested statistic in Hz

API Tier

This is a **Tier 4 "Ultra"** function. The entire pitch extraction and statistic computation happens in C++ with no intermediate R6 objects.

Algorithm choice

Pitch is always extracted with 'Sound_to_Pitch_rawCc()', ‘veryAccurate = TRUE', 'silenceThreshold = 0.03' (matching DSI201.praat’s 'To Pitch (cc)...' step). Only 'voicing_threshold' is configurable; the AC/CC choice and 'veryAccurate' are not. See the Tier 4 Ultra algorithm table in 'inst/agents/AGENT_GUIDE.md' for how this compares to the other Ultra functions.

See Also

[Sound] for creating Sound objects [get_durations_batch()] for MPT component of DSI

Examples

sound <- Sound$create_tone(frequency = 150, duration = 1, sampling_rate =
 16000)

# Get maximum F0 (DSI FH component)
max_f0 <- calculate_f0_stats_ultra(sound, stat = "max", min_pitch = 75,
 max_pitch = 600)

# Get mean F0
mean_f0 <- calculate_f0_stats_ultra(sound, stat = "mean")

Description

Calculate Interval Midpoints with SIMD

Usage

calculate_midpoints_simd_bridge(start_times, end_times)

Arguments

Value

Numeric vector of midpoints

Examples

calculate_midpoints_simd_bridge(c(0, 1, 2.5), c(0.8, 2, 3.2))

Description

Complete intensity pipeline in C++: Sound -> Pitch -> PointProcess -> TextGrid (VUV) -> Intensity -> Minimum in voiced regions, in one call instead of the equivalent Tier 2/3 workflow.

This is a **Tier 4 "Ultra"** function for batch DSI (Dysphonia Severity Index) calculations where minimum intensity is the IM (Intensity Minimum) component.

Usage

calculate_minimum_intensity_ultra(
  sound,
  min_pitch = 75,
  max_pitch = 600,
  time_step = 0,
  subtract_mean = TRUE
)

Arguments

Value

Minimum intensity in dB (in voiced regions only). Returns 'NA' if no voiced regions are detected.

API Tier

This is a **Tier 4 "Ultra"** function. The entire workflow (pitch extraction, PointProcess creation, VUV segmentation, intensity calculation, and minimum finding in voiced regions) happens in C++ with no intermediate R objects.

Algorithm choice

Pitch is always extracted with 'Sound_to_Pitch_rawCc()', 'veryAccurate = FALSE', 'silenceThreshold = 0.03', ‘voicingThreshold = 0.8' — matching DSI201.praat’s IM component, which uses a stricter voicing threshold than the jitter block. None of these are exposed as parameters (including 'voicing_threshold', unlike 'calculate_f0_stats_ultra()'). See the Tier 4 Ultra algorithm table in 'inst/agents/AGENT_GUIDE.md'.

See Also

[Sound] for creating Sound objects [calculate_f0_stats_ultra()] for FH component of DSI

Examples

sound <- Sound$create_tone(frequency = 150, duration = 1, sampling_rate =
 16000)

# Get minimum intensity in voiced regions (DSI IM component)
min_int <- calculate_minimum_intensity_ultra(sound, min_pitch = 75)

Description

Optimized multi-band HNR calculation for VQ (Voice Quality) measurements. Computes HNR (mean + standard deviation) for 5 frequency bands in a single call: full spectrum, 0-500 Hz, 0-1500 Hz, 0-2500 Hz, 0-3500 Hz.

Usage

calculate_multiband_hnr_ultra(
  sound,
  bands = c(0, 500, 1500, 2500, 3500),
  time_step = 0.005,
  min_pitch = 75,
  from_time = 0,
  to_time = 0
)

Arguments

Details

Use this when you only need one interval or whole-sound summary. For repeated interval queries on the same 'Sound', use [build_multiband_harmonicity()] once and then [multiband_hnr_stats()] for each interval.

Value

Named list with '*_mean' and '*_sd' values for each band.

Algorithm choice

Harmonicity is always computed with 'Sound_to_Harmonicity_cc()' (the CC method) for every band — there is no AC alternative and no way to configure it. This matches VQ_measurements_V2.praat lines 102-122. See the Tier 4 Ultra algorithm table in 'inst/agents/AGENT_GUIDE.md'.

References

- VQ_measurements_V2.praat (Voice Quality measurements) - Maryn & Weenink (2015) - Multi-band HNR for voice quality

See Also

build_multiband_harmonicity and multiband_hnr_stats for the reusable multi-interval path

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.5, sampling_rate =
 16000)

hnr_results <- calculate_multiband_hnr_ultra(sound)
hnr_results$full_mean

Description

Praat Cepstrum object with direct C++ module binding.

Details

The cepstrum is the inverse Fourier transform of the logarithm of the spectrum. Unlike PowerCepstrum, it preserves phase information.

Value

A Cepstrum object with methods for cepstral analysis and quefrency-domain processing.

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.3)
cepstrum <- sound$to_cepstrum()
spectrum <- cepstrum$to_spectrum()

Description

ggplot2-based visualizations for power cepstrum objects, replacing Praat's native graphics system with R's powerful plotting capabilities.

Value

This is a documentation-only overview; see the individual functions (plot_powercepstrum, create_cepstrum_report) for their return values.

Examples

# See individual functions, e.g. ?plot_powercepstrum

Description

Analyzes a Sound object for common quality issues and returns diagnostic metrics. This function provides basic quality control checks useful for validating recording quality in production pipelines.

Usage

check_audio_quality(
  sound,
  clipping_threshold = 0.99,
  intensity_floor = 100,
  time_step = 0
)

Arguments

Details

This function is designed to catch common recording problems:

**Clipping Detection**: Identifies if the signal exceeds a threshold (default 0.99). Clipped recordings have distorted peaks and should typically be re-recorded.

**Intensity Analysis**: Uses Praat's intensity measurement to assess signal strength. Very low mean intensity may indicate recording level problems.

**Dynamic Range**: The difference between maximum and minimum intensity can help identify recordings with poor signal-to-noise ratio or excessive compression.

**Quality Criteria** (general guidelines): - No clipping (is_clipped = FALSE) - Mean intensity: -20 to -10 dB for speech - Dynamic range: > 20 dB - Max amplitude: 0.7-0.9 range (good headroom without clipping)

Value

A list with the following components:

max_amplitude

Maximum absolute amplitude in the recording

is_clipped

Logical: TRUE if amplitude exceeds clipping_threshold

n_clipping_samples

Number of samples above clipping threshold

clipping_percentage

Percentage of samples that clip

mean_intensity_db

Mean intensity in dB

min_intensity_db

Minimum intensity in dB

max_intensity_db

Maximum intensity in dB

intensity_range_db

Dynamic range (max - min intensity)

rms_amplitude

Root mean square amplitude

duration

Total duration in seconds

sampling_frequency

Sampling frequency in Hz

Examples

sound <- Sound$create_tone(frequency = 220, duration = 0.5, sampling_rate =
 16000)
quality <- check_audio_quality(sound)

cat("Audio Quality Report:\n")
cat("  Duration:", quality$duration, "seconds\n")
cat("  Sampling rate:", quality$sampling_frequency, "Hz\n")
cat("  Clipped:", quality$is_clipped, "\n")
cat("  Max amplitude:", round(quality$max_amplitude, 3), "\n")
cat("  Mean intensity:", round(quality$mean_intensity_db, 1), "dB\n")
cat("  Dynamic range:", round(quality$intensity_range_db, 1), "dB\n")

Description

A Praat Cochleagram: the output of a bank of auditory filters modeling the basilar membrane, over time.

Arguments

Details

Frequency runs along the Bark scale (0-25.6 Bark) rather than Hertz, matching the perceptual frequency resolution of the ear. Create one from a Sound with sound$to_cochleagram() or sound$to_cochleagram_edb(); slice it at a time point to get an Excitation pattern, from which loudness can be read off.

Value

A Cochleagram object.

Usage

cochleagram <- sound$to_cochleagram()

Query methods

• get_start_time(), get_end_time(), get_duration() - time domain in seconds

• get_number_of_frames(), get_time_step() - time sampling

• get_time_from_column(i_col) - time at a 1-based frame index

• get_lowest_frequency(), get_highest_frequency() - frequency range in Bark

• get_number_of_frequency_bands(), get_frequency_step() - frequency sampling

• get_frequency_from_row() - frequency at a 1-based band index

• get_value_at_time_and_frequency(time, freq_bark) - excitation level at a point

• get_loudness_at_time(time) - loudness (sone) at a time

Transformation and export

• to_excitation(time) - excitation pattern (Excitation object) at a time

• get_difference(other, tmin, tmax) - distance between two cochleagrams

• as_matrix() - values as a numeric matrix (frequency bands x frames)

See Also

[Excitation], [Sound]

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.3, sampling_rate =
 44100)
cochleagram <- sound$to_cochleagram()
cochleagram$get_duration()
cochleagram$get_loudness_at_time(0.15)

Description

Create a ComplexSpectrogram object from a Sound: a phase-preserving spectrogram computed with a complex FFT.

Arguments

Value

An object of class ComplexSpectrogram (a list with methods, dispatched via the shared PraatObject pattern).

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.3)
cs <- ComplexSpectrogram(sound)
cs$get_amplitude(0.15, 150)

Description

Creates a multi-panel diagnostic plot combining power cepstrum, cepstrogram, and CPP time series for comprehensive analysis.

Usage

create_cepstrum_report(
  cepstrogram,
  time_slice = NULL,
  save_path = NULL,
  format = c("png", "pdf", "svg"),
  dpi = 300
)

Arguments

Value

A combined plot object (invisibly)

Examples

if (requireNamespace("gridExtra", quietly = TRUE)) {
sound <- Sound$create_tone(frequency = 150, duration = 0.6, sampling_rate =
 16000)
  cepstrogram <- sound$to_powercepstrogram(pitch_floor = 60)

  # Create comprehensive report at t = 0.3s (mid-signal)
  create_cepstrum_report(cepstrogram, time_slice = 0.3)
}

Description

Create a file list similar to Praat's "Create Strings as file list". Returns a simple character vector of file paths.

Usage

create_file_list(
  directory,
  pattern = NULL,
  full_names = TRUE,
  recursive = FALSE
)

Arguments

Value

Character vector of file paths

Examples

audio_dir <- tempfile("audio_")
dir.create(audio_dir)
tone <- Sound$create_tone(frequency = 150, duration = 0.3, sampling_rate =
 16000)
tone$save(file.path(audio_dir, "tone1.wav"))

# Equivalent to: Create Strings as file list: "list", "*.wav"
wav_files <- create_file_list(audio_dir, pattern = "\\.wav$")

Description

**DEPRECATED:** This S3 function is deprecated. Use the R6 interface instead: Sound$from_values(values, sampling_rate)

Usage

create_sound(values, sampling_rate = 44100, start_time = 0)

Arguments

Value

Sound R6 object

Examples

# Old S3 approach (DEPRECATED, shown for reference)
sound <- create_sound(c(0.1, 0.2), sampling_rate = 1000)

# New R6 approach (RECOMMENDED)
sound2 <- Sound$from_values(c(0.1, 0.2), sampling_rate = 1000)

Description

Creates a praat_sound object structure from R numeric data

Usage

create_sound_from_values(values, sampling_rate = 44100, start_time = 0)

Arguments

Value

List representing a praat_sound object with values and metadata

Examples

values <- sin(2 * pi * 220 * seq(0, 0.1, length.out = 1000))
snd <- create_sound_from_values(values, sampling_rate = 10000)

Description

Convenience function to create pre-defined window functions as compiled XPtrs. Requires the RcppXPtrUtils package.

Usage

create_window_xptr(
  type = c("hamming", "hanning", "gaussian", "triangular", "blackman", "rectangular"),
  sigma = 0.25
)

Arguments

Value

External pointer to compiled window function

Examples

# Compiling a C++ window function takes a few seconds
if (requireNamespace("RcppXPtrUtils", quietly = TRUE)) {
  hamming <- create_window_xptr("hamming")

sound <- Sound$create_tone(frequency = 220, duration = 0.3, sampling_rate =
 16000)
  windowed <- apply_window_xptr(sound, hamming)
}

Description

Linear Discriminant Analysis (LDA) for vowel classification, speaker identification, and other multivariate acoustic classification tasks.

Arguments

Details

Discriminant analysis is commonly used in phonetics for vowel classification, speaker identification, dialect/accent classification, and phoneme recognition.

Value

A Discriminant object with methods for querying discriminant functions, eigenvalues, and group statistics.

See Also

PCA

Examples

set.seed(1)
data <- matrix(c(rnorm(10, 500), rnorm(10, 700)), ncol = 1,
                dimnames = list(NULL, "f1"))
labels <- rep(c("a", "i"), each = 10)
disc <- discriminant_from_matrix(data, labels)
disc$get_number_of_groups()
disc$get_eigenvalues()

Description

Performs Linear Discriminant Analysis on a labeled numeric matrix.

Usage

discriminant_from_matrix(data, labels)

Arguments

Value

A Discriminant object

Examples

# NOTE: only a single predictor column is used here; multi-column
# matrices are currently unreliable (see Discriminant class docs).
set.seed(1)
data <- matrix(c(rnorm(10, 500), rnorm(10, 700)), ncol = 1,
                dimnames = list(NULL, "f1"))
labels <- rep(c("a", "i"), each = 10)
disc <- discriminant_from_matrix(data, labels)
disc$get_number_of_groups()

Description

Temporal alignment between two acoustic signals.

Usage

DTW(.xptr = NULL)

Arguments

Details

DTW aligns a candidate signal (x-axis) to a prototype or reference (y-axis), computing an optimal path through a distance matrix that minimizes the total distance while respecting slope constraints.

Value

A DTW object wrapping the alignment path and distance matrix.

Creating DTW objects

DTW objects are created by aligning two acoustic objects:

• sounds_to_dtw(reference, candidate) - align two sounds (most common)

• mfccs_to_dtw(mfcc1, mfcc2) - align MFCCs (speech recognition)

• spectrograms_to_dtw(spec1, spec2) - align spectrograms

• pitches_to_dtw(pitch1, pitch2) - align pitch contours

Time mapping

• $get_y_time_from_x_time(tx) - map candidate time to reference time

• $get_x_time_from_y_time(ty) - map reference time to candidate time

• $map_times(times, direction) - vectorized time mapping

TextGrid warping

• $warp_textgrid(textgrid) - warp annotation times

Path analysis

• $get_weighted_distance() - global alignment distance

• $get_path_length() - number of cells in optimal path

• $get_path() - full path as a data.frame

• $get_maximum_consecutive_steps("x"|"y") - path regularity

Slope constraints

Controls path flexibility:

• 1: No constraint (any slope)

• 2: 1/3 < slope < 3

• 3: 1/2 < slope < 2 (recommended)

• 4: 2/3 < slope < 3/2 (strict)

See Also

Sound, Pitch, Spectrogram, MFCC

Examples

# Basic alignment workflow
reference <- Sound$create_tone(frequency = 150, duration = 0.3)
candidate <- Sound$create_tone(frequency = 160, duration = 0.3)

# Create DTW alignment
dtw <- sounds_to_dtw(reference, candidate,
  analysis_width = 0.015,
  time_step = 0.005,
  band = 0.0,
  slope = 3
)

# Check alignment quality
cat("Distance:", dtw$get_weighted_distance(), "\n")

# Map time point from candidate to reference
ref_time <- dtw$get_y_time_from_x_time(0.1)

Description

Computes mean, standard deviation, min, and max of durations using SIMD.

Usage

duration_statistics_simd_bridge(durations)

Arguments

Value

List with mean, stdev, min, max

Examples

duration_statistics_simd_bridge(c(0.5, 0.8, 1.2, 0.3))

Description

Praat DurationTier object for duration manipulation, created via direct C++ module binding.

Arguments

Details

DurationTiers are used together with Manipulation objects to modify the duration/tempo of sounds. Values represent duration multiplication factors:

• 1.0 - normal speed

• 2.0 - half speed (doubled duration)

• 0.5 - double speed (halved duration)

Value

A DurationTier object with methods for duration and tempo manipulation via time-value points.

Examples

dt <- DurationTier(0, 1)
dt$add_point(0.25, 1.0)
dt$add_point(0.75, 1.5)
dt$get_number_of_points()
dt$get_value_at_time(0.5)

Description

Praat Electroglottogram (EGG) object. Measures electrical impedance across the larynx, varying with vocal fold contact during phonation.

Arguments

Details

Electroglottogram inherits from Sound and represents a specialized single-channel sound that records vocal fold contact area.

Value

An Electroglottogram object (triple-class c("Electroglottogram", "Sound", "PraatObject")) that inherits Sound's methods in addition to its own.

Examples

egg <- electroglottogram_create(xmin = 0, xmax = 1, nx = 16000, dx = 1 /
 16000, x1 = 0)
egg$get_duration()
egg$get_number_of_samples()
egg$is_valid()

Description

Create an Electroglottogram object

Usage

electroglottogram_create(xmin, xmax, nx, dx, x1)

Arguments

Value

Electroglottogram object

Examples

egg <- electroglottogram_create(xmin = 0, xmax = 1, nx = 16000, dx = 1 /
 16000, x1 = 0)
egg$get_duration()

Description

Represents a Praat auditory excitation pattern.

Arguments

Details

An excitation pattern is the perceptual loudness distribution across the auditory frequency range, measured on the Bark scale. It is produced from a Spectrum or a Cochleagram, not created directly.

Value

An Excitation object.

Query methods

• get_loudness() - total loudness in sones

• get_value_at_frequency(freq_bark) - excitation level at a given Bark frequency

• get_distance(other) - distance to another Excitation object

Conversion

• to_formant(max_formants = 20) - estimate formants from the excitation pattern

Export

• as_vector() - export as a numeric vector, one value per Bark bin

• as_data_frame() - export as a data.frame of frequency (Bark) and excitation

See Also

Spectrum, Formant

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.3)
spectrum <- sound$to_spectrum()
excitation <- spectrum$to_excitation()
excitation$get_loudness()

Description

Extract formants from multiple files in parallel.

Usage

extract_formant_parallel(
  files,
  n_cores = NULL,
  time_step = 0.005,
  max_formants = 5,
  max_frequency = 5500
)

Arguments

Value

List of Formant objects

Examples

audio_dir <- tempfile("audio_")
dir.create(audio_dir)
tone <- Sound$create_tone(frequency = 220, duration = 0.3, sampling_rate =
 16000)
tone$save(file.path(audio_dir, "tone1.wav"))
files <- list.files(audio_dir, pattern = "\\.wav$", full.names = TRUE)

# n_cores = 1 keeps this a single-process example (CRAN-safe)
formants <- extract_formant_parallel(files, n_cores = 1)

Description

**DEPRECATED:** This function is deprecated in favor of the R6 interface. Use 'sound$to_formant_burg()' instead.

Usage

extract_formants(
  sound,
  time_step = 0,
  max_formant = 5500,
  n_formants = 5,
  window_length = 0.025,
  pre_emphasis_from = 50
)

Arguments

Details

Analyzes formant frequencies (vocal tract resonances) from a sound object using Praat's Burg algorithm.

Value

Depends on the class of sound:

• If sound is an R6 Sound object (the normal case — Sound()/Sound$create_tone() always create one), this function delegates entirely to sound$to_formant_burg() and returns an R6 Formant object. This is what get_formant_at_time/get_mean_formant do NOT accept — those two expect the legacy list below.

• If sound is a legacy (pre-R6) praat_sound list, returns a plain, unclassed list with elements values (a data.frame with columns time, formant_number, frequency, bandwidth), n_frames, time_step, max_formant, and n_formants. This list is no longer given a "praat_formant" class (removed when the package's S3 object system was fully migrated to R6), so it will not satisfy is_praat_formant() / get_formant_at_time / get_mean_formant without manually adding class(x) <- "praat_formant" first.

Examples

# sound is an R6 Sound object here, so this delegates to to_formant_burg()
# and returns an R6 Formant object (see the second value's \value above).
sound <- Sound$create_tone(frequency = 220, duration = 0.5, sampling_rate =
 16000)
formants <- extract_formants(sound, max_formant = 5500)
f1_mean <- formants$get_mean(formant_number = 1)

# Equivalent, and the recommended way to spell it directly:
formants2 <- sound$to_formant_burg(max_frequency = 5500)
f1_mean2 <- formants2$get_mean(formant_number = 1)

Description

**DEPRECATED:** Use sound$to_intensity() instead.

Usage

extract_intensity(
  sound,
  time_step = 0,
  minimum_pitch = 100,
  subtract_mean = TRUE
)

Arguments

Value

Intensity R6 object

Examples

sound <- Sound$create_tone(frequency = 220, duration = 0.5, sampling_rate =
 16000)
intensity <- suppressWarnings(extract_intensity(sound))
intensity$get_mean(from_time = 0, to_time = 0)

Description

Extract intensity from multiple files in parallel.

Usage

extract_intensity_parallel(
  files,
  n_cores = NULL,
  minimum_pitch = 100,
  time_step = 0
)

Arguments

Value

List of Intensity objects

Examples

audio_dir <- tempfile("audio_")
dir.create(audio_dir)
tone <- Sound$create_tone(frequency = 220, duration = 0.3, sampling_rate =
 16000)
tone$save(file.path(audio_dir, "tone1.wav"))
files <- list.files(audio_dir, pattern = "\\.wav$", full.names = TRUE)

# n_cores = 1 keeps this a single-process example (CRAN-safe)
intensities <- extract_intensity_parallel(files, n_cores = 1)

Description

High-level function to extract acoustic measurements aligned with TextGrid intervals. Automates the common Praat workflow of measuring formants/pitch at interval midpoints.

Usage

extract_measurements(
  sound,
  textgrid,
  tier = 1,
  measurements = c("pitch", "formants", "intensity"),
  time_point = c("midpoint", "start", "end", "mean"),
  pitch_params = list(time_step = 0.01, pitch_floor = 75, pitch_ceiling = 600),
  formant_params = list(time_step = 0.01, max_formants = 5, max_frequency = 5500,
    window_length = 0.025, pre_emphasis = 50),
  intensity_params = list(minimum_pitch = 100, time_step = 0, subtract_mean = TRUE)
)

Arguments

Value

Data frame with one row per interval, columns for label and requested measurements.

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.6, sampling_rate =
 16000)
tg <- textgrid_create(0, 0.6, "phones")
tg$insert_boundary("phones", 0.3)
tg$set_interval_text("phones", 1, "a")
tg$set_interval_text("phones", 2, "e")

results <- extract_measurements(
  sound = sound,
  textgrid = tg,
  tier = 1,
  measurements = c("pitch", "formants"),
  time_point = "midpoint"
)

Description

Extract acoustic measurements from intervals or points in TextGrid annotations. This replaces complex Praat scripts that loop over TextGrid intervals.

Usage

extract_measurements_custom(
  sound,
  textgrid,
  tier,
  measures,
  interval_filter = NULL,
  aggregate_by = "interval"
)

Arguments

Value

Data frame with measurements for each interval/point

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.6, sampling_rate =
 16000)
tg <- textgrid_create(0, 0.6, "phones")
tg$insert_boundary("phones", 0.3)
tg$set_interval_text("phones", 1, "a")
tg$set_interval_text("phones", 2, "e")

measurements <- extract_measurements_custom(
  sound = sound,
  textgrid = tg,
  tier = "phones",
  measures = list(
    mean_f0 = function(snd, t1, t2) snd$to_pitch()$get_mean(0, 0, "hertz"),
    mean_intensity = function(snd, t1, t2) snd$to_intensity()$get_mean(0, 0)
  ),
  interval_filter = function(label) label %in% c("a", "e", "i", "o", "u")
)

Description

**DEPRECATED:** This S3 function is deprecated. Use the R6 interface instead: sound$to_pitch(time_step, pitch_floor, pitch_ceiling)

Usage

extract_pitch(sound, pitch_floor = 75, pitch_ceiling = 600, time_step = 0.01)

Arguments

Value

Pitch R6 object

Examples

# Old S3 approach (DEPRECATED, shown for reference)
sound <- Sound$create_tone(frequency = 150, duration = 0.5, sampling_rate =
 16000)
pitch <- extract_pitch(sound, pitch_floor = 75, pitch_ceiling = 300)

# New R6 approach (RECOMMENDED)
pitch2 <- sound$to_pitch(pitch_floor = 75, pitch_ceiling = 300)
mean_f0 <- pitch2$get_mean()

Description

Extract pitch from multiple files in parallel. Convenience wrapper around analyze_files_parallel.

Usage

extract_pitch_parallel(
  files,
  n_cores = NULL,
  pitch_floor = 75,
  pitch_ceiling = 600,
  time_step = 0
)

Arguments

Value

List of Pitch objects

Examples

audio_dir <- tempfile("audio_")
dir.create(audio_dir)
tone <- Sound$create_tone(frequency = 150, duration = 0.3, sampling_rate =
 16000)
tone$save(file.path(audio_dir, "tone1.wav"))
files <- list.files(audio_dir, pattern = "\\.wav$", full.names = TRUE)

# n_cores = 1 keeps this a single-process example (CRAN-safe)
pitches <- extract_pitch_parallel(files, n_cores = 1)

Description

Extract all intervals from a TextGrid tier that match specified text criteria, in a single call instead of a manual R loop.

Usage

extract_textgrid_intervals(
  textgrid,
  sound = NULL,
  tier,
  text_equals = NULL,
  text_contains = NULL,
  text_starts_with = NULL,
  extract_sounds = FALSE
)

Arguments

Value

List with components: - 'indices': Integer vector of matching interval indices - 'labels': Character vector of matching labels - 'start_times': Numeric vector of start times - 'end_times': Numeric vector of end times - 'n_total': Total number of intervals in tier - 'n_matched': Number of matching intervals - 'sounds': List of Sound objects (if extract_sounds = TRUE)

How It Works

A manual R loop makes one R<->C++ call per interval; this function does the whole tier scan in a single C++ call.

Comparison Types

Specify exactly ONE comparison criterion: - 'text_equals': Exact match (fastest) - 'text_contains': Substring search - 'text_starts_with': Prefix match

See Also

- [get_textgrid_labels_all()] to get all labels from a tier - [get_textgrid_interval_stats()] to compute statistics for all intervals

Examples

# Create sound and a voiced/unvoiced TextGrid
sound <- Sound$create_tone(frequency = 150, duration = 1, sampling_rate =
 16000)
pitch <- sound$to_pitch()
tg <- pitch$to_textgrid_vuv(0.02, 0.01)

# Extract all voiced intervals (batch), with the matching Sound parts
result <- extract_textgrid_intervals(
  textgrid = tg,
  sound = sound,
  tier = 1,
  text_equals = "V",
  extract_sounds = TRUE
)
voiced_sounds <- result$sounds

# Get interval durations without extracting sounds
result2 <- extract_textgrid_intervals(
  textgrid = tg,
  tier = 1,
  text_equals = "V",
  extract_sounds = FALSE
)
voiced_durations <- result2$end_times - result2$start_times

Description

Voice activity detection combining intensity-based detection with optional Zero Crossing Rate (ZCR) filtering. Returns concatenated voiced segments as a Sound object. This matches the AVQI v2.03/v3.01 voiced extraction.

Usage

extract_voiced_segments(
  sound,
  minimum_pitch = 50,
  time_step = 0.003,
  silence_threshold = -25,
  min_silent_interval = 0.1,
  min_sounding_interval = 0.1,
  zcr_threshold = 3000,
  zcr_window = 0.03,
  use_zcr = TRUE,
  return_textgrid = FALSE
)

Arguments

Details

The detection pipeline: 1. Intensity-based: Find segments above silence threshold 2. ZCR filtering (if 'use_zcr = TRUE'): Reject high-ZCR segments (unvoiced)

AVQI uses both intensity AND ZCR filtering. Set 'use_zcr = FALSE' for intensity-only detection.

Value

If 'return_textgrid = FALSE': Sound object with concatenated voiced segments. If 'return_textgrid = TRUE': List with 'sound' and 'textgrid' elements.

Examples

sound <- Sound$create_tone(frequency = 150, duration = 1, sampling_rate =
 16000)

# Full AVQI-compatible extraction (default)
voiced <- extract_voiced_segments(sound)

# Intensity-only (no ZCR filtering)
voiced_no_zcr <- extract_voiced_segments(sound, use_zcr = FALSE)

# With TextGrid output
result <- extract_voiced_segments(sound, return_textgrid = TRUE)
cat("Duration:", result$sound$get_duration(), "s\n")

Description

Complete AVQI voiced segment extraction pipeline in a single C++ call. Supports both AVQI v2.03 (simple intensity-based) and v3.01 (with ZCR filtering). Performs: Sound -> TextGrid (silence) -> Extract sounding -> Concatenate -> [v3.01: Window power/ZCR filtering] -> Final concatenation, in a single C++ call instead of a multi-step R implementation.

Usage

extract_voiced_segments_ultra(
  sound,
  version = "v3.01",
  min_pitch = 50,
  silence_threshold_db = -25,
  min_silent_duration = 0.1,
  min_sounding_duration = 0.1,
  power_threshold_factor = 0.3,
  max_zcr = 3000,
  window_width = 0.03
)

Arguments

Details

**TIER 4 ULTRA API**

This function implements the exact AVQI voiced extraction algorithm in a single C++ call. It replaces the R loops and multiple boundary crossings of the standard multi-step approach.

**Algorithm (AVQI v3.01):** 1. Detect silences using intensity-based TextGrid creation 2. Extract all "sounding" intervals 3. Concatenate sounding intervals -> "loud_sound" 4. Slide 30ms windows through loud_sound 5. Filter windows by: power > 30 6. Concatenate passing windows -> final voiced sound

**Algorithm (AVQI v2.03):** Steps 1-3 only (no window filtering)

**Version Differences:** - v2.03: Simpler, keeps most voiced content (~37s from 37s input) - v3.01: Aggressive ZCR filtering, removes fricatives (~25-30s from 37s input)

Value

Sound object containing only voiced segments (concatenated)

Algorithm choice

No pitch algorithm is used here — voiced/silence segmentation is Intensity-threshold based ('Sound_to_Intensity()' + 'silence_threshold_db' relative to the maximum), not derived from a 'Pitch' object. 'min_pitch' only controls the Intensity analysis window length (via ‘Sound_to_Intensity'’s own floor parameter), not a pitch-detection algorithm choice. See the Tier 4 Ultra algorithm table in 'inst/agents/AGENT_GUIDE.md'.

References

- AVQI v3.01: Maryn et al. (2017) - with ZCR filtering - AVQI v2.03: Original Praat script - intensity-based only

Examples

sound <- Sound$create_tone(frequency = 150, duration = 1, sampling_rate =
 16000)

# AVQI v3.01 (default, with ZCR filtering)
voiced_v3 <- extract_voiced_segments_ultra(sound, version = "v3.01")

# AVQI v2.03 (simple intensity-based)
voiced_v2 <- extract_voiced_segments_ultra(sound, version = "v2.03")

voiced_v3$get_total_duration()
voiced_v2$get_total_duration()

Description

Returns indices of intervals with duration in [min_dur, max_dur]. Uses SIMD for fast range comparison.

Usage

filter_by_duration_simd_bridge(durations, min_dur, max_dur)

Arguments

Value

Integer vector of 1-based indices into durations whose value falls within ⁠[min_dur, max_dur]⁠

Examples

filter_by_duration_simd_bridge(c(0.1, 0.5, 1.2, 0.3), 0.2, 0.8)

Description

Formant objects represent vocal tract resonance frequencies over time. Created from a Sound via formant tracking algorithms (Burg, Split-Levinson, or Willems). Formant frequencies and bandwidths are the primary acoustic correlates of vowel quality in speech.

Arguments

Value

A Formant object with methods for querying formant frequencies and bandwidths at time points or across the full contour.

Information

• get_number_of_frames() - number of analysis frames

• get_time_step() - time step between frames (s)

• get_min_num_formants(), get_max_num_formants() - formant count range per frame

Point queries (single time)

• get_value_at_time(formant_number, time, unit) - formant frequency at time

• get_bandwidth_at_time(formant_number, time, unit) - formant bandwidth at time

• get_all_values_at_time(time, max_formants, unit) - all formant values at a time point

Statistics (over time range)

• get_mean(formant_number, from_time, to_time, unit) - mean formant frequency

• get_standard_deviation(formant_number, from_time, to_time, unit) - standard deviation

• get_minimum(formant_number, from_time, to_time, unit) - minimum value

• get_maximum(formant_number, from_time, to_time, unit) - maximum value

• get_quantile(formant_number, quantile, from_time, to_time, unit) - quantile

• get_time_of_minimum(...), get_time_of_maximum(...) - time of extremum

Batch and vectorized

• get_formant_track(formant_number, unit) - full track for one formant

• get_bandwidth_track(formant_number, unit) - full bandwidth track

• get_values_at_times(formant_number, times, unit) - values at an arbitrary vector of times

• get_all_formant_tracks(max_formants, unit) - all formants as a matrix

Export

• as_data_frame(max_formants) - export as a data.frame, long format: one row per (frame, formant number), with columns time, formant, frequency (Hz), and bandwidth (Hz). Matches FormantPath$as_data_frame().

• save(filepath) - save to a Praat binary file

Transform

• to_formant_tier(formant_number) - extract one formant as a FormantTier

• to_formant_modeler() - create a polynomial trajectory model

• down_to_formant_tier() - extract all formants as a FormantTier

See Also

Sound, LPC, FormantPath, FormantModeler

Examples

# Self-contained example with generated tone
sound <- Sound$create_tone(duration = 1.0, frequency = 150, sampling_rate =
 44100)
formant <- sound$to_formant_burg(
  time_step = 0.01, max_number_of_formants = 5,
  maximum_formant = 5500, window_length = 0.025, pre_emphasis_from = 50
)
f1 <- formant$get_value_at_time(formant_number = 1, time = 0.5, unit =
 "hertz")

# The same analysis on a recording read from disk
sound <- Sound(system.file("extdata", "test.wav", package = "pladdrr"))
formant <- sound$to_formant_burg(
  time_step = 0.01, max_number_of_formants = 5,
  maximum_formant = 5500, window_length = 0.025, pre_emphasis_from = 50
)
f1_at_02s <- formant$get_value_at_time(formant_number = 1, time = 0.2, unit =
 "hertz")
mean_f1 <- formant$get_mean(formant_number = 1, from_time = 0, to_time = 0,
 unit = "hertz")

Description

Praat FormantGrid object: formant frequencies and bandwidths over time, editable at arbitrary time points.

Arguments

Details

Used for voice transformation and synthesis. This is the editable counterpart to the read-only Formant object.

Value

A FormantGrid object with methods for formant frequency and bandwidth manipulation.

Examples

fg <- FormantGrid(0, 1, number_of_formants = 3)
fg$add_formant_point(1, 0.5, 700)
fg$get_formant_at_time(1, 0.5)
fg$get_number_of_formants()

Description

Robust formant trajectory modeling using polynomial fits with outlier detection.

Arguments

Details

FormantModeler provides polynomial modeling of formant trajectories over time. It automatically identifies outliers and can find the optimal formant ceiling for a given sound, making it useful for robust formant analysis in noisy speech.

Value

A FormantModeler object with methods for polynomial modeling of formant trajectories with outlier detection.

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.5)
formant <- sound$to_formant_burg()
modeler <- formant$to_formant_modeler(tmin = 0, tmax = 0, num_tracks = 3,
 num_params = 3)
r2 <- modeler$get_coefficient_of_determination(1, 3)
f1_modeled <- modeler$get_track_model_values(1)

Description

A FormantPath object represents multiple formant tracking candidates with different ceiling frequencies, allowing for robust formant analysis by automatically selecting the optimal tracking path.

Arguments

Value

An object of class FormantPath wrapping the set of candidate formant tracks (list with methods; dispatched via the shared PraatObject pattern).

Examples

sound <- Sound$create_tone(frequency = 150, duration = 0.3)
fp <- FormantPath(sound)
fp$get_duration()

Description

Praat FormantTier object: formant frequencies and bandwidths at discrete time points, with interpolation between points.

Arguments

Details

The interpolated contour can be used to filter sounds for vowel modification or resynthesis.

Value

A FormantTier object with methods for formant frequency and bandwidth manipulation via time-value points.

Usage

FormantTier(tmin, tmax)              # create an empty FormantTier
FormantTier$from_formant(formant)    # convert from a Formant object

Query methods

• get_start_time(), get_end_time(), get_duration() - time range in seconds

• get_number_of_points() - number of time points

• get_min_num_formants(), get_max_num_formants() - formant count across points

• get_value_at_time(formant_number, time) - formant frequency in Hz

• get_bandwidth_at_time(formant_number, time) - bandwidth in Hz

Transformation

• filter_sound(sound, scale = TRUE) - filter a sound through the formants

• as_data_frame() - export to a data frame

• save(path) - save to file

Examples

# Create from Formant analysis
sound <- Sound$create_tone(frequency = 150, duration = 0.5)
formant <- sound$to_formant_burg()
ft <- FormantTier$from_formant(formant)

# Query formant values
f1 <- ft$get_value_at_time(1, 0.25)  # F1 at 0.25s
f2 <- ft$get_value_at_time(2, 0.25)  # F2 at 0.25s

# Filter a source sound
source <- Sound$create_tone(frequency = 100, duration = 0.5)  # Buzz
vowel <- ft$filter_sound(source)