README.Rmd

---
output:
  github_document:
    html_preview: false
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
library(readr)
library(ggplot2)
library(magrittr)
theme_set(theme_minimal())
library(speakr)
```

# speakr: A Wrapper for the Phonetic Software Praat <img src='man/figures/logo.png' style="float: right;" height="120" />

<!-- badges: start -->
`r badger::badge_cran_release("speakr", "blue")`
`r badger::badge_cran_checks("speakr")`
[![R-CMD-check](https://github.com/stefanocoretta/speakr/workflows/R-CMD-check/badge.svg)](https://github.com/stefanocoretta/speakr/actions)
`r badger::badge_devel(color = "orange")`
`r badger::badge_doi(doi = "10.5281/zenodo.4014768", color = "blue")`
[![R-CMD-check](https://github.com/stefanocoretta/speakr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/stefanocoretta/speakr/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

With speakr, you can run Praat scripts in R and capture their `infoLine` output.

## Installation

You can install the released version of speakr from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("speakr")
```

If you want to install a stable(ish) development version, use:

``` r
remotes::install_github("stefanocoretta/speakr@devel", build_vignettes = TRUE)
```

## Use

For a quick start, check out the vignette with:

``` r
vignette("run-praat", "speakr")
```

On macOS, Linux and Windows, the path to praat is set automatically to the default installation path.
If you have installed Praat in a different location, or if your operating system is not supported, you can set the path to Praat with `options(speakr.praat.path)`.

For example:

``` r
options(speakr.praat.path = "./custom/praat.exe")
```

You can either run this command every time you start a new R session, or you can add the command to your `.Rprofile` (recommended).

## Example

Use `prat_run()` to run a Praat script, and `capture = TRUE` to capture the output of the `write/appendInfoLine` commands in the script.
Everything is set in the Praat script as usual, so you don't have to learn a new language to perform tasks you already know how to perform.

```{r run-script}
script <- system.file("extdata", "get-formants-args.praat", package = "speakr")

formants <- praat_run(script, "Hertz", 0.03, capture = TRUE) %>%
  read_csv()
```

Let's check the tibble `formants`.

```{r formants}
formants
```

And let's make a vowel plot.

```{r vowel-plot}
formants %>%
  ggplot(aes(F2, F1, label = vowel)) +
  geom_label(size = 10) +
  labs(
    title = "Vowel plot",
    x = "F2 (Hertz)",
    y = "F1 (Hertz)"
  ) +
  scale_x_reverse(position = "top", limits = c(2250, 700)) +
  scale_y_reverse(position = "right", limits = c(900, 150)) +
  coord_fixed()
```

## Simple plotting utility

You can plot a sound file and TextGrid using Praat's plotting facilities.

```{r plotting, eval=FALSE}
wav <- system.file("extdata", "vowels.wav", package = "speakr")

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

You can include the plot in an Rmarkdown file with knitr.

```{r fig}
knitr::include_graphics("man/figures/vowels.png")
```