Allow outputting transcriptions to a file

Author: richiejp

README.md

@@ -11,7 +11,7 @@ VoxInput is meant to be used with [LocalAI](https://localai.io), but it will fun
 ## Features
 
 - **Speech-to-Text Daemon**: Runs as a background process to listen for signals to start or stop recording audio.
-- **Audio Capture and Playback**: Records audio from the microphone and plays it back for verification.
+- **Audio Capture**: Records audio from the microphone or any other device, including audio you are listening to.
 - **Transcription**: Converts recorded audio into text using a local or remote transcription service.
 - **Text Automation**: Simulates typing the transcribed text into an application using [`dotool`](https://git.sr.ht/~geb/dotool).
 - **Voice Activity Detection**: In realtime mode VoxInput uses VAD to detect speech segments and automatically transcribe them.
@@ -24,11 +24,15 @@ VoxInput is meant to be used with [LocalAI](https://localai.io), but it will fun
 - `dotool` (for simulating keyboard input)
 - `OPENAI_API_KEY` or `VOXINPUT_API_KEY`: Your OpenAI API key for Whisper transcription. If you have a local instance with no key, then just leave it unset.
 - `OPENAI_BASE_URL` or `VOXINPUT_BASE_URL`: The base URL of the OpenAI compatible API server: defaults to `http://localhost:8080/v1`
-- `OPENAI_WS_BASE_URL` or `VOXINPUT_WS_BASE_URL`: The base URL of the realtime websocket API: defaults to `ws://localhost:8080/v1/realtime`
-- OpenAI Realtime API support - VoxInput's realtime mode with VAD requires a [websocket endpoint that support's OpenAI's realtime API in transcription only mode](https://github.com/mudler/LocalAI/pull/5392). You can disable realtime mode with `--no-realtime`.
-
-Note that the VoxInput env vars take precedence over the OpenAI ones.
-
+- `XDG_RUNTIME_DIR`: Required for PID and state files in `$XDG_RUNTIME_DIR`.
+- `VOXINPUT_LANG`: Language code for transcription (defaults to empty).
+- `VOXINPUT_TRANSCRIPTION_MODEL`: Transcription model (default: `whisper-1`).
+- `VOXINPUT_TRANSCRIPTION_TIMEOUT`: Timeout duration (default: `30s`).
+- `VOXINPUT_SHOW_STATUS`: Show GUI notifications (`yes`/`no`, default: `yes`).
+- `VOXINPUT_CAPTURE_DEVICE`: Specific audio capture device name (run `voxinput devices` to list).
+- `VOXINPUT_OUTPUT_FILE`: Path to save the transcribed text to a file instead of typing it with dotool.
+
+**Note**: `VOXINPUT_` vars take precedence over `OPENAI_` vars.
 Unless you don't mind running VoxInput as root, then you also need to ensure the following is setup for `dotool`
 
 - Your user is in the `input` user group
@@ -78,36 +82,50 @@ The pop-up window showing when recording has begun can be disabled by setting `V
 
 ### Commands
 
-- **`listen`**: Starts the speech-to-text daemon.
+- **`listen`**: Start speech to text daemon.
+  - `--replay`: Play the audio just recorded for transcription (non-realtime mode only).
+  - `--no-realtime`: Use the HTTP API instead of the realtime API; disables VAD.
+  - `--no-show-status`: Don't show when recording has started or stopped.
+  - `--output-file <path>`: Save transcript to file instead of typing.
   ```bash
   ./voxinput listen
   ```
 
-- **`record`**: Sends a signal to the daemon to start recording audio then exits. In realtime mode this will start transcription.
+- **`record`**: Tell existing listener to start recording audio. In realtime mode it also begins transcription.
   ```bash
   ./voxinput record
   ```
 
-- **`write`** or **`stop`**: Sends a signal to the daemon to stop recording. When not in realtime mode this triggers transcription.
+- **`write`** or **`stop`**: Tell existing listener to stop recording audio and begin transcription if not in realtime mode. `stop` alias makes more sense in realtime mode.
   ```bash
   ./voxinput write
   ```
 
-- **`toggle`**: Toggle recording on/off (start recording if idle, stop if recording). Only works in realtime mode.
+- **`toggle`**: Toggle recording on/off (start recording if idle, stop if recording).
   ```bash
   ./voxinput toggle
   ```
 
-- **`status`**: Show whether the server is listening and if it's currently recording. Only works in realtime mode.
+- **`status`**: Show whether the server is listening and if it's currently recording.
   ```bash
   ./voxinput status
   ```
 
-- **`help`**: Displays help information.
+- **`devices`**: List capture devices.
+  ```bash
+  ./voxinput devices
+  ```
+
+- **`help`**: Show help message.
   ```bash
   ./voxinput help
   ```
 
+- **`ver`**: Print version.
+  ```bash
+  ./voxinput ver
+  ```
+
 ### Example Realtime Workflow
 
 1. Start the daemon in a terminal window:
@@ -146,6 +164,42 @@ The pop-up window showing when recording has begun can be disabled by setting `V
 
 4. The transcribed text will be typed into the active application.
 
+### Example Workflow: Transcribing an Online Meeting or Video Stream
+
+To create a transcript of an online meeting or video stream by capturing system audio:
+
+1. List available capture devices:
+
+   ```bash
+   ./voxinput devices
+   ```
+
+   Identify the monitor device, e.g., "Monitor of Built-in Audio Analog Stereo".
+
+2. Start the daemon specifying the device and output file:
+
+   ```bash
+   VOXINPUT_CAPTURE_DEVICE="Monitor of Built-in Audio Analog Stereo" ./voxinput listen --output-file meeting_transcript.txt
+   ```
+
+   Note: Add `--no-realtime` if you prefer the HTTP API.
+
+3. Start recording:
+
+   ```bash
+   ./voxinput record
+   ```
+
+4. Play your online meeting or video stream; the system audio will be captured.
+
+5. Stop recording:
+
+   ```bash
+   ./voxinput stop
+   ```
+
+6. The transcript is now in `meeting_transcript.txt`.
+
 ### Quick start with LocalAI
 
 1. Follow https://localai.io/installation/ to install LocalAI, the simplest way is using Docker:
@@ -183,10 +237,6 @@ The realtime mode has a UI to display various actions being taken by VoxInput. H
 - `SIGUSR2`: Stop recording and transcribe audio.
 - `SIGTERM`: Stop the daemon.
 
-## Limitations
-
-- Uses the default audio input, make sure you have the device you want to use set as the default on your system.
-
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

flake.lock

@@ -114,15 +114,16 @@ func waitForSessionUpdated(ctx context.Context, conn *openairt.Conn) error {
 }
 
 type ListenConfig struct {
-	PIDPath string
-	APIKey string
-	HTTPAPIBase string
-	WSAPIBase string
-	Lang string
-	Model string
-	Timeout time.Duration
-	UI *gui.GUI
+	PIDPath       string
+	APIKey        string
+	HTTPAPIBase   string
+	WSAPIBase     string
+	Lang          string
+	Model         string
+	Timeout       time.Duration
+	UI            *gui.GUI
 	CaptureDevice string
+	OutputFile    string
 }
 
 func listen(config ListenConfig) {
@@ -349,6 +350,21 @@ Listen:
 
 				log.Println("main: received transcribed text: ", text)
 
+				if config.OutputFile != "" {
+					f, err := os.OpenFile(config.OutputFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
+					if err != nil {
+						log.Printf("Failed to open output file %s: %v\n", config.OutputFile, err)
+						continue
+					}
+					if _, err := fmt.Fprintln(f, text); err != nil {
+						log.Printf("Failed to write to output file: %v\n", err)
+					}
+					if err := f.Close(); err != nil {
+						log.Printf("Failed to close output file: %v\n", err)
+					}
+					continue
+				}
+
 				dotool := exec.CommandContext(ctx, "dotool")
 				stdin, err := dotool.StdinPipe()
 				if err != nil {

listen.go

@@ -36,19 +36,32 @@ func main() {
 
 	switch cmd {
 	case "help":
-		fmt.Println("Available commands:")
-		fmt.Println("  listen - Start speech to text daemon")
-		fmt.Println("           --replay play the audio just recorded for transcription")
-		fmt.Println("           --no-realtime use the HTTP API instead of the realtime API; disables VAD")
-		fmt.Println("           --no-show-status don't show when recording has started or stopped")
-		fmt.Println("  record - Tell existing listener to start recording audio. In realtime mode it also begins transcription")
-		fmt.Println("  write  - Tell existing listener to stop recording audio and begin transcription if not in realtime mode")
-		fmt.Println("  stop   - Alias for write; makes more sense in realtime mode")
-		fmt.Println("  toggle - Toggle recording on/off (start recording if idle, stop if recording)")
-		fmt.Println("  status - Show whether the server is listening and if it's currently recording")
-		fmt.Println("  devices - List capture devices")
-		fmt.Println("  help   - Show this help message")
-		fmt.Println("  ver    - Print version")
+		fmt.Println(`Available commands:
+  listen - Start speech to text daemon
+           --replay play the audio just recorded for transcription
+           --no-realtime use the HTTP API instead of the realtime API; disables VAD
+           --no-show-status don't show when recording has started or stopped
+           --output-file <path> Write transcribed text to file instead of keyboard
+  record - Tell existing listener to start recording audio. In realtime mode it also begins transcription
+  write  - Tell existing listener to stop recording audio and begin transcription if not in realtime mode
+  stop   - Alias for write; makes more sense in realtime mode
+  toggle - Toggle recording on/off (start recording if idle, stop if recording)
+  status - Show whether the server is listening and if it's currently recording
+  devices - List capture devices
+  help   - Show this help message
+  ver    - Print version
+
+Environment variables:
+  VOXINPUT_API_KEY or OPENAI_API_KEY - OpenAI API key (default: sk-xxx)
+  VOXINPUT_BASE_URL or OPENAI_BASE_URL - HTTP API base URL (default: http://localhost:8080/v1)
+  VOXINPUT_WS_BASE_URL or OPENAI_WS_BASE_URL - WebSocket API base URL (default: ws://localhost:8080/v1/realtime)
+  VOXINPUT_LANG or LANG - Language code for transcription (default: none)
+  VOXINPUT_TRANSCRIPTION_MODEL or TRANSCRIPTION_MODEL - Transcription model (default: whisper-1)
+  VOXINPUT_TRANSCRIPTION_TIMEOUT or TRANSCRIPTION_TIMEOUT - Transcription timeout (default: 30s)
+  VOXINPUT_SHOW_STATUS or SHOW_STATUS - Show status notifications (yes/no, default: yes)
+  VOXINPUT_CAPTURE_DEVICE - Name of the capture device (default: system default; use 'devices' to list)
+  VOXINPUT_OUTPUT_FILE - File to write transcribed text to (instead of keyboard)
+  XDG_RUNTIME_DIR - Directory for PID and state files (required, standard XDG variable)`)
 		return
 	case "ver":
 		fmt.Printf("v%s\n", strings.TrimSpace(string(version)))
@@ -75,7 +88,9 @@ func main() {
 		timeoutStr := getPrefixedEnv([]string{"VOXINPUT", ""}, "TRANSCRIPTION_TIMEOUT", "30s")
 		showStatus := getPrefixedEnv([]string{"VOXINPUT", ""}, "SHOW_STATUS", "yes")
 		captureDeviceName := getPrefixedEnv([]string{"VOXINPUT"}, "CAPTURE_DEVICE", "")
-		
+
+		outputFile := getPrefixedEnv([]string{"VOXINPUT"}, "OUTPUT_FILE", "")
+
 		timeout, err := time.ParseDuration(timeoutStr)
 		if err != nil {
 			log.Println("main: failed to parse timeout", err)
@@ -101,21 +116,34 @@ func main() {
 		replay := slices.Contains(os.Args[2:], "--replay")
 		realtime := !slices.Contains(os.Args[2:], "--no-realtime")
 
+		var outputFileArg string
+		for i := 2; i < len(os.Args); i++ {
+			arg := os.Args[i]
+			if arg == "--output-file" && i+1 < len(os.Args) {
+				outputFileArg = os.Args[i+1]
+				break
+			}
+		}
+		if outputFileArg != "" {
+			outputFile = outputFileArg
+		}
+
 		if realtime {
 			ctx, cancel := context.WithCancel(context.Background())
 			ui := gui.New(ctx, showStatus)
 
 			go func() {
 				listen(ListenConfig{
-					PIDPath: pidPath,
-					APIKey: apiKey,
-					HTTPAPIBase: httpApiBase,
-					WSAPIBase: wsApiBase,
-					Lang: lang,
-					Model: model,
-					Timeout: timeout,
-					UI: ui,
+					PIDPath:       pidPath,
+					APIKey:        apiKey,
+					HTTPAPIBase:   httpApiBase,
+					WSAPIBase:     wsApiBase,
+					Lang:          lang,
+					Model:         model,
+					Timeout:       timeout,
+					UI:            ui,
 					CaptureDevice: captureDeviceName,
+					OutputFile:    outputFile,
 				})
 				cancel()
 			}()

main.go

@@ -1 +1 @@
-0.7.1
+0.8.0