Type: Package
Title: A Wrapper for the Phonetic Software 'Praat'
Version: 3.2.4
Date: 2024-12-07
Description: It allows running 'Praat' scripts from R and it provides some wrappers for basic plotting. It also adds support for literate markdown tangling. The package is designed to bring reproducible phonetic research into R.
License: MIT + file LICENSE
URL: https://github.com/stefanocoretta/speakr
BugReports: https://github.com/stefanocoretta/speakr/issues
Encoding: UTF-8
RoxygenNote: 7.3.2
Imports: cli, ggplot2, lifecycle, quarto, readr, stringr, tibble
Suggests: knitr, rmarkdown
VignetteBuilder: knitr
Language: en-US
NeedsCompilation: no
Packaged: 2024-12-07 10:53:56 UTC; ste
Author: Stefano Coretta ORCID iD [aut, cre]
Maintainer: Stefano Coretta <stefano.coretta@gmail.com>
Repository: CRAN
Date/Publication: 2024-12-07 11:10:04 UTC

speakr: A Wrapper for the Phonetic Software 'Praat'

Description

It allows running 'Praat' scripts from R and it provides some wrappers for basic plotting. It also adds support for literate markdown tangling. The package is designed to bring reproducible phonetic research into R.

Author(s)

Maintainer: Stefano Coretta stefano.coretta@gmail.com (ORCID)

See Also

Useful links:

Install the Literate Markdown Tangler extension

Description

It installs the Quarto extension Literate Markdown Tangler, which provides users with literate programming tools.

Usage

add_lmt()

Value

Nothing. Used for its side effects.

Examples

## Not run: 
add_lmt()

## End(Not run)

Print path to 'Praat'.

Description

[Deprecated]

Now speakr uses options() to set the path to 'Praat'.

Usage

get_praat_path()

Open files with 'Praat'.

Description

It opens a file or list of files in the 'Praat' GUI.

Usage

praat_open(...)

Arguments

...

A character vector with the path to the file. Include multiple vector arguments to open multiple files.

Value

Nothing. Used for its side effects.

Examples

## Not run: 
# Open a single file

script <- system.file("extdata", "get-formants.praat", package = "speakr")
praat_open(script)

# Open multiple files

wav <- system.file("extdata", "vowels.wav", package = "speakr")
tg <- system.file("extdata", "vowels.TextGrid", package = "speakr")
praat_open(wav, tg)

## End(Not run)

Get system path to 'Praat'.

Description

The function returns the path to the 'Praat' executable depending on the system. If the operating system is not supported, the package gracefully

Usage

praat_path()

Value

The path to the 'Praat' executable.

Plot waveform and spectrogram

Description

Plot waveform and spectrogram

Usage

praat_plot(
  file,
  wav,
  tg = NULL,
  start = 0,
  end = NULL,
  width = 5,
  format = "png",
  f0 = FALSE,
  f0_min = 0,
  f0_max = 500,
  spec_max = 5000
)

Arguments

file

Output file path as a string.

wav

Wav file path as a string.

tg

TextGrid file path as a string. If NULL (the default), a TextGrid is plotted if a TextGrid file with the same name as the wav file is found. No TextGrid is plotted otherwise.

start

Start time of the plotting window in seconds.

end

End time of the plotting window in seconds. If NULL (the default), plot the entire duration.

width

Width of the plot in inches.

format

Output file format (png by default, or pdf).

f0

Whether to plot f0 (FALSE by default).

f0_min

If f0 = TRUE, minimum f0 value (0 by default).

f0_max

If f0 = TRUE, maximum f0 value (500 by default).

spec_max

Maximum frequency for the spectrogram (5000 by default).

Value

Nothing. It is used for its side effects.

Examples

## Not run: 
wav <- system.file("extdata", "vowels.wav", package = "speakr")

praat_plot("vowels.png", wav, f0 = TRUE, f0_max = 200, end = 3)

## End(Not run)

Run a 'Praat' script.

Description

It runs a 'Praat' script, with optional arguments passed to the script.

Usage

praat_run(script, ..., capture = FALSE)

Arguments

script

A character vector containing the script name.

...

List of arguments to be passed to the script.

capture

If set to TRUE, the standard output of the script (for example, from writeInfo) can be saved into a variable in R. If FALSE (the default) the output is logged to the console.

Value

If the 'Praat' script returns standard output this is returned as a character vector. Also, if the script has instructions to create files, these will be created.

Examples

## Not run: 
script <- system.file("extdata", "get-formants.praat", package = "speakr")

# Run get-formants.praat with argument "Hertz" and log to console.
praat_run(script, "Hertz")

# Run get-formants.praat with arguments and save in R variable.
library(readr)
formants <- praat_run(script, "Hertz", 0.03, capture = TRUE) %>%
  read_csv()

## End(Not run)

Set path to 'Praat'.

Description

[Deprecated]

Now speakr uses options() to set the path to 'Praat'.

Usage

set_praat_path(path, default.path = FALSE)

Start 'Praat'.

Description

It opens the 'Praat' GUI.

Usage

start_praat()

Value

Nothing. Used for its side effects.

Examples

## Not run: 
# Open Praat GUI.
start_praat()

## End(Not run)

Use Praat plotting script

Description

This allows the user to save a copy of the Praat plotting script on disk so that they can make changes and customise the plot.

Usage

use_praat_plot_script(file, ...)

Arguments

file

Path including file name to which the script is copied.

...

Further arguments passed to file.copy.

Value

Nothing. It is used for its side effects.