Getting Started with speechmatics

Authentication

The package uses the Speechmatics API, which requires an API key. Sign up at https://www.speechmatics.com/ to get one, then set it as an environment variable:

Sys.setenv(SPEECHMATICS_API_KEY = "your-key-here")

For persistent use, add it to your .Renviron file:

SPEECHMATICS_API_KEY=your-key-here

Basic transcription

sm_transcribe() submits an audio file, waits for the result, and writes the transcript to a text file in your working directory:

library(speechmatics)

audio <- system.file("extdata", "testrecording.mp3", package = "speechmatics")
sm_transcribe(audio)
#> ✔ Submitting 'testrecording.mp3'
#> ℹ Job ID: "2om9psu1np"
#> ✔ Waiting for transcription [5.8s]
#> ✔ Saved to testrecording.txt

You can also specify the output path:

sm_transcribe(audio, "my_transcript.txt")
#> ✔ Submitting 'testrecording.mp3'
#> ℹ Job ID: "2om9psu1np"
#> ✔ Waiting for transcription [5.8s]
#> ✔ Saved to my_transcript.txt

Configuration

Use sm_transcription_config() to control language, quality, and diarization:

# French, enhanced quality
sm_transcribe(
  audio,
  config = sm_transcription_config(language = "fr", quality = "enhanced")
)
#> ✔ Submitting 'testrecording.mp3'
#> ℹ Job ID: "2om9psu1np"
#> ✔ Waiting for transcription [6.1s]
#> ✔ Saved to testrecording.txt

Speaker diarization

Speaker diarization identifies who said what from a single audio channel:

sm_transcribe(
  audio,
  config = sm_transcription_config(diarization = sm_diarize_speaker())
)
#> ✔ Submitting 'testrecording.mp3'
#> ℹ Job ID: "3kn7xr2abc"
#> ✔ Waiting for transcription [7.2s]
#> ✔ Saved to testrecording.txt

Channel diarization

Channel diarization separates speakers that are already on different audio channels:

sm_transcribe(
  audio,
  config = sm_transcription_config(
    diarization = sm_diarize_channel(labels = c("Agent", "Caller"))
  )
)
#> ✔ Submitting 'testrecording.mp3'
#> ℹ Job ID: "5pq2mt4def"
#> ✔ Waiting for transcription [6.5s]
#> ✔ Saved to testrecording.txt

Managing jobs

You can work with jobs directly using the lower-level functions:

# list all jobs
jobs <- sm_list_jobs()
jobs
#>           id status               created_at             data_name duration
#> 1 2om9psu1np   done 2026-06-06T08:12:19.089Z     testrecording.mp3        3
#> 2 w06jp9mjvm   done 2026-06-04T10:19:28.351Z               idea-morning-walk.mp3     2037
#> 3 xco00nzvpq   done 2026-06-01T11:33:28.303Z conf-talk.mp3     1501
#>   language operating_point diarization
#> 1       en        standard        <NA>
#> 2       en        enhanced     speaker
#> 3       en        enhanced     speaker

# get a transcript in different formats
sm_get_transcript("2om9psu1np")
#> [1] "Hi. This is a test recording."

sm_get_transcript("2om9psu1np", format = "srt")
#> [1] "1\n00:00:00,000 --> 00:00:02,000\nHi. This is a test recording.\n"

sm_get_transcript("2om9psu1np", format = "json-v2")
#> $format
#> [1] "2.9"
#>
#> $job
#> $job$created_at
#> [1] "2026-06-06T08:12:19.089Z"
#>
#> $job$data_name
#> [1] "testrecording.mp3"
#>
#> $results
#> $results[[1]]
#> $results[[1]]$alternatives
#> $results[[1]]$alternatives[[1]]
#> $results[[1]]$alternatives[[1]]$confidence
#> [1] 1
#>
#> $results[[1]]$alternatives[[1]]$content
#> [1] "Hi"
#>
#> ...

# delete a job
sm_delete_job("2om9psu1np")