hear.1

.Dd March 27, 2024
.Dt HEAR 1
.Os Darwin
.Sh NAME
.Nm hear
.Nd macOS speech recognition via the command line
.Sh SYNOPSIS
.Nm
.Op Fl hvdmps
.Op Fl i Ar audio_file
.Op Fl l Ar locale
.Op Fl x Ar exit_word
.Sh DESCRIPTION
.Nm
is a command line interface for the built-in speech recognition
capabilities in macOS. It supports transcription of both audio files
and microphone input. If no input file is provided, the default behaviour
is to transcribe from the default audio input device, typically the
microphone.
.Pp
The following flags are supported:
.Bl -tag -width -indent
.It Fl s -supported
Print list of supported locales for speech recognition and exit.
.It Fl l -locale Ar loc
Specify speech recognition language (locale). Default is 'en-US'.
.It Fl i -input Ar audio_file
Input audio file. All formats supported by CoreAudio should work (e.g. WAV, MP3,
AAC, CAF, AIFF, ALAC, etc.).
.It Fl d -device
Only use on-device offline speech recognition. The default is to use whatever
the macOS Speech Recognition API thinks is best, which may include sending data
to Apple servers. When on-device is not enabled, there may be a hard limit to
the length of audio that can be transcribed in a single session. As of writing
(2024) this is about 500 characters or so.
.It Fl m -mode
Enable single-line output mode (only applies when the input is default audio
input device, e.g. microphone).
.It Fl p -punctuation
Add punctuation to speech recognition results.
.It Fl x -exit Ar exit_word
Set exit word. This causes the program to exit when a speech recognition result
ends with the specified word.
.It Fl t -timeout Ar seconds
Exit if no recognition results are received within the specified number of seconds.
.It Fl h -help
Print help and exit.
.It Fl v -version
Print program name and version, and exit.
.El
.Pp
Returns 0 on success and greater than 0 on error or failure.
.Sh SEE ALSO
.Xr say 1
.Xr afplay 1
.Sh AUTHORS
.An Sveinbjorn Thordarson <sveinbjorn@sveinbjorn.org>