--- title: "Getting Started with pladdrr: Phonetic Analysis in R" author: "pladdrr Package Authors" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Getting Started with pladdrr: Phonetic Analysis in R} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 5 ) ``` ## Introduction The `pladdrr` package provides direct access to Praat's phonetic analysis capabilities from R, without requiring Python. It implements core phonetic analysis objects (Sound, Pitch, Formant, Intensity) with an object-oriented interface (S3-based, with R6-like `$method()` syntax) that follows Praat's conventions. ## Installation ```{r eval = FALSE} # Install from source install.packages("pladdrr", type = "source") # Or install from GitHub # devtools::install_github("your-username/pladdrr") ``` ```{r} library(pladdrr) ``` ## Creating and Loading Sounds ### Generate Test Sounds The package includes functions to generate test signals: ```{r} # Generate a 440 Hz sine wave (A4 note) sound_a4 <- generate_sine_wave(frequency = 440, duration = 0.5, amplitude = 0.7, sampling_rate = 44100) print(sound_a4) ``` ```{r} # Generate white noise noise <- generate_noise(duration = 0.2, sampling_rate = 44100, amplitude = 0.3) print(noise) ``` ### Load Audio Files ```{r} # Load a WAV file using the object-oriented interface speech <- Sound$new(system.file("extdata", "test.wav", package = "pladdrr")) speech # For a stereo file, select a channel (1-indexed): # speech_left <- Sound$new("stereo.wav", channel = 1) # speech_right <- Sound$new("stereo.wav", channel = 2) ``` ## Basic Sound Properties Extract basic information from sound objects using object methods: ```{r} # Duration in seconds cat("Duration:", sound_a4$get_duration(), "seconds\n") # Sampling rate cat("Sampling rate:", sound_a4$get_sampling_frequency(), "Hz\n") # Number of samples cat("Samples:", sound_a4$get_number_of_samples(), "\n") # Number of channels cat("Channels:", sound_a4$get_number_of_channels(), "\n") ``` ## Sound Statistics Calculate amplitude statistics: ```{r} # Individual statistics cat("Mean amplitude:", sound_mean(sound_a4), "\n") cat("RMS amplitude:", sound_rms(sound_a4), "\n") cat("Min amplitude:", sound_min(sound_a4), "\n") cat("Max amplitude:", sound_max(sound_a4), "\n") # All statistics at once stats <- sound_statistics(sound_a4) print(stats) ``` ## Pitch Analysis Extract fundamental frequency ( F0) from speech or sustained tones using object methods: ```{r} # For speech, use typical settings # pitch <- speech$to_pitch(pitch_floor = 75, pitch_ceiling = 600) # For our test signal, we need to create a more complex sound # (pure sine waves may not be detected as voiced) # In real usage with speech: # mean_f0 <- pitch$get_mean() # min_f0 <- pitch$get_minimum() # max_f0 <- pitch$get_maximum() ``` ### Pitch Parameters ```{r} # Male voice pitch_male <- speech$to_pitch(pitch_floor = 50, pitch_ceiling = 300) # Female voice pitch_female <- speech$to_pitch(pitch_floor = 100, pitch_ceiling = 600) # Child voice pitch_child <- speech$to_pitch(pitch_floor = 150, pitch_ceiling = 800) ``` ### Querying Pitch Values ```{r} pitch <- speech$to_pitch(pitch_floor = 75, pitch_ceiling = 600) # Get F0 at specific time point f0_at_1s <- pitch$get_value_at_time(time = 0.5) # Get mean F0 over time range mean_f0_range <- pitch$get_mean(from_time = 0.1, to_time = 0.5) # Get minimum and maximum min_f0 <- pitch$get_minimum() max_f0 <- pitch$get_maximum() ``` ## Formant Analysis Analyze vocal tract resonances (formants) for vowel characterization: ```{r} # Extract formants (default settings for adult female) formants <- sound_a4$to_formant_burg(max_frequency = 5500, max_formants = 5) # Objects print nicely formants ``` ### Speaker-Specific Settings ```{r} # Adult male formants_male <- speech$to_formant_burg(max_frequency = 5000, max_formants = 5) # Adult female formants_female <- speech$to_formant_burg(max_frequency = 5500, max_formants = 5) # Child formants_child <- speech$to_formant_burg(max_frequency = 8000, max_formants = 5) ``` ### Querying Formant Values ```{r} # Get F1 and F2 at specific time (vowel quality) f1 <- formants$get_value_at_time(formant_number = 1, time = 0.25) f2 <- formants$get_value_at_time(formant_number = 2, time = 0.25) cat("F1:", round(f1, 1), "Hz\n") cat("F2:", round(f2, 1), "Hz\n") ``` ```{r} # Get mean formant over time range mean_f1 <- formants$get_mean(formant_number = 1, from_time = 0.1, to_time = 0.4) mean_f2 <- formants$get_mean(formant_number = 2, from_time = 0.1, to_time = 0.4) cat("Mean F1:", round(mean_f1, 1), "Hz\n") cat("Mean F2:", round(mean_f2, 1), "Hz\n") ``` ## Intensity Analysis Measure sound power (loudness) over time: ```{r} # Extract intensity intensity <- sound_a4$to_intensity(minimum_pitch = 100) # Objects print nicely intensity ``` ### Intensity Statistics ```{r} # Mean intensity mean_db <- intensity$get_mean() cat("Mean intensity:", round(mean_db, 2), "dB\n") # Intensity range min_db <- intensity$get_minimum() max_db <- intensity$get_maximum() cat("Intensity range:", round(min_db, 2), "-", round(max_db, 2), "dB\n") # Standard deviation sd_db <- intensity$get_standard_deviation() cat("SD intensity:", round(sd_db, 2), "dB\n") ``` ### Intensity at Specific Time ```{r} # Query intensity at time point int_at_time <- intensity$get_value_at_time(time = 0.25) cat("Intensity at 0.25s:", round(int_at_time, 2), "dB\n") # With interpolation (cubic) int_interp <- intensity$get_value_at_time(time = 0.25, interpolation = "cubic") cat("Intensity (interpolated):", round(int_interp, 2), "dB\n") ``` ## Working with Data Frames All analysis objects can be converted to data frames for plotting and further analysis: ```{r} # Convert to data frame using the object's method formant_df <- formants$as_data_frame() head(formant_df) ``` ```{r} intensity_df <- intensity$as_data_frame() head(intensity_df) ``` ## Visualization The `pladdrr` package provides ggplot2-based visualization functions ( `autoplot( )`/`autolayer()` methods, see `vignette("autoplot-autolayer")`) for its analysis objects. For detailed examples of creating plots, see `vignette("visualization")`, which covers: - Voice quality visualization (AVQI, DSI, CPP) - Formant analysis (vowel spaces, trajectories) - Pitch and intensity contours - Spectral analysis (spectrograms, spectra, LTAS) - TextGrid annotations - Multi-panel diagnostic reports ## Complete Workflow Example Here's a complete analysis workflow: ```{r} # 1. Load sound sound <- Sound$new(system.file("extdata", "test.wav", package = "pladdrr")) # 2. Extract all analyses pitch <- sound$to_pitch(pitch_floor = 75, pitch_ceiling = 600) formants <- sound$to_formant_burg(max_frequency = 5500, max_formants = 5) intensity <- sound$to_intensity(minimum_pitch = 75) # 3. Get measurements at vowel midpoint midpoint <- sound$get_duration() / 2 f0 <- pitch$get_value_at_time(time = midpoint) f1 <- formants$get_value_at_time(formant_number = 1, time = midpoint) f2 <- formants$get_value_at_time(formant_number = 2, time = midpoint) f3 <- formants$get_value_at_time(formant_number = 3, time = midpoint) int <- intensity$get_value_at_time(time = midpoint) # 4. Create summary vowel_data <- data.frame( F0 = f0, F1 = f1, F2 = f2, F3 = f3, Intensity = int ) print(vowel_data) ``` ## Comparing with Praat Scripts The package follows Praat's conventions, making it easy to translate Praat scripts: ### Praat Script ``` # Praat sound = Read from file: "sound.wav" pitch = To Pitch: 0.01, 75, 600 f0 = Get mean: 0, 0, "Hertz" ``` ### pladdrr Equivalent ```{r} # R with pladdrr sound <- Sound$new(system.file("extdata", "test.wav", package = "pladdrr")) pitch <- sound$to_pitch(time_step = 0.01, pitch_floor = 75, pitch_ceiling = 600) f0 <- pitch$get_mean(from_time = 0, to_time = 0, unit = "hertz") ``` ## Advanced Topics ### Custom Analysis Parameters ```{r} # Fine-tune formant detection formants <- sound$to_formant_burg( time_step = 0.005, # 5 ms steps max_frequency = 5500, # Adult female range max_formants = 5, # Track F1-F5 window_length = 0.025, # 25 ms window pre_emphasis_from = 50 # Pre-emphasis from 50 Hz ) # Fine-tune intensity intensity <- sound$to_intensity( minimum_pitch = 75, # Affects window length time_step = 0.01, # 10 ms steps (auto if 0) subtract_mean = FALSE # Absolute intensity in dB SPL ) ``` ### Handling NA Values Analysis methods return `NA` for undefined values (e.g. unvoiced pitch frames) rather than erroring: ```{r} # Pitch may be NA for unvoiced segments f0 <- pitch$get_value_at_time(time = 0.5) if (is.na(f0)) { cat("Unvoiced at this time point\n") } else { cat("F0:", f0, "Hz\n") } # Mean functions automatically exclude NA mean_f0 <- pitch$get_mean() # NA values excluded ``` ## Package Information ```{r} # Package version packageVersion("pladdrr") # Citation information citation("pladdrr") ``` ## See Also - Praat: - Package documentation: `help(package = "pladdrr")` - Function reference: `?Sound`, `?Pitch`, `?Formant`, `?Intensity` ## Conclusion This vignette covered the core `pladdrr` analysis objects: Sound, Pitch, Formant, and Intensity. The package exposes 38 Praat modules with 500+ methods in total (see `DESCRIPTION` and `help(package = "pladdrr")` for the full list), including auditory modeling, TextGrid annotation, voice quality assessment, and a persistent Praat script interpreter. For more information, see the individual function documentation and the package README.