npm package: @sorenpeng/rtstt
Description: Real-time speech-to-text CLI tool using OpenAI Realtime API
Author: sorenpeng
Latest version: 1.0.0

# RTSTT - Real-Time Speech-to-Text

```
██████╗ ████████╗███████╗████████╗████████╗
██╔══██╗╚══██╔══╝██╔════╝╚══██╔══╝╚══██╔══╝
██████╔╝   ██║   ███████╗   ██║      ██║   
██╔══██╗   ██║   ╚════██║   ██║      ██║   
██║  ██║   ██║   ███████║   ██║      ██║   
╚═╝  ╚═╝   ╚═╝   ╚══════╝   ╚═╝      ╚═╝   
                                           
   Real-Time Speech-To-Text with OpenAI
```

A command-line tool for real-time speech-to-text transcription using OpenAI's Realtime API. Follows Unix philosophy: does one thing well, outputs to stdout, and is easily composable with other tools.

## Features

- 🎙️ Real-time audio capture from system microphone
- 🔄 Live transcription using OpenAI Realtime API
- 📝 Output to stdout (perfect for piping)
- 💾 Optional file output
- 🔧 Cross-platform support (Linux, macOS, Windows)
- ⚡ Low latency streaming transcription
- 🎛️ Configurable audio settings

## Installation

### Prerequisites

#### Linux (Recommended)
```bash
# Ubuntu/Debian
sudo apt install alsa-utils

# Arch Linux
sudo pacman -S alsa-utils

# CentOS/RHEL/Fedora
sudo dnf install alsa-utils
```

#### macOS/Windows
```bash
# Install ffmpeg
# macOS with Homebrew
brew install ffmpeg

# Windows with Chocolatey
choco install ffmpeg

# Or download from https://ffmpeg.org/download.html
```

### Install RTSTT

```bash
npm install -g @SorenPeng/rtstt
```

### Setup

1. Get your OpenAI API key from [OpenAI Platform](https://platform.openai.com/api-keys)
2. Set the environment variable:

```bash
export OPENAI_API_KEY="your_api_key_here"
```

Or create a `.env` file:
```bash
cp .env.example .env
# Edit .env and add your API key
```

## Usage

### Basic Usage

```bash
# Start real-time transcription
rtstt

# Save transcription to file
rtstt --out transcript.txt

# Quiet mode (suppress status messages)
rtstt --quiet
```

### Advanced Usage

```bash
# Use specific model
rtstt --model gpt-4o-realtime-preview

# Custom audio settings
rtstt --rate 24000 --chunks 0.1

# Linux: specify audio device
rtstt --device hw:1,0
```

### Composable Examples

```bash
# Search for keywords in real-time
rtstt | grep -i "important"

# Log with timestamps
rtstt | ts '[%H:%M:%S]' >> meeting_notes.txt

# Pipe to other tools
rtstt --quiet | tee >(grep "action item" >> tasks.txt)

# Use with fzf for searchable transcription
rtstt --out history.txt | fzf --tac
```

## Command Line Options

| Option | Alias | Default | Description |
|--------|-------|---------|-------------|
| `--model` | `-m` | `gpt-4o-realtime-preview` | OpenAI model to use |
| `--rate` | `-r` | `16000` | Audio sample rate in Hz |
| `--device` | `-d` | | Audio input device (Linux only) |
| `--chunks` | `-c` | `0.2` | Audio chunk duration in seconds |
| `--out` | `-o` | | Output file to append transcription |
| `--quiet` | `-q` | `false` | Suppress status messages |
| `--help` | `-h` | | Show help |

## Audio Requirements

The tool captures audio in the following format (optimized for OpenAI Realtime API):
- **Sample Rate**: 16 kHz (configurable)
- **Bit Depth**: 16-bit
- **Channels**: Mono
- **Format**: PCM (little-endian)

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `OPENAI_API_KEY` | OpenAI API key (required) | - |
| `RTSTT_MODEL` | Default model to use | `gpt-4o-realtime-preview` |
| `RTSTT_BASE_URL` | Custom API base URL | `wss://api.openai.com` |

## Troubleshooting

### Audio Issues

#### Linux
```bash
# List audio devices
arecord -l

# Test recording
arecord -f S16_LE -r 16000 -c 1 -t raw /dev/null

# Check ALSA configuration
cat /proc/asound/cards
```

#### macOS
```bash
# List audio devices
ffmpeg -f avfoundation -list_devices true -i ""

# Test recording
ffmpeg -f avfoundation -i ":0" -t 5 test.wav
```

#### Windows
```bash
# List audio devices
ffmpeg -list_devices true -f dshow -i dummy

# Test recording
ffmpeg -f dshow -i audio="Microphone" -t 5 test.wav
```

### Common Issues

1. **"OPENAI_API_KEY environment variable is required"**
   - Set your OpenAI API key as environment variable
   - Or create a `.env` file with your key

2. **"Failed to start audio recording"**
   - Install audio tools (alsa-utils on Linux, ffmpeg on macOS/Windows)
   - Check microphone permissions
   - Try different audio device with `--device`

3. **"Failed to connect to OpenAI API"**
   - Check internet connection
   - Verify API key is correct and has Realtime API access
   - Check if you have sufficient credits

## Development

```bash
# Clone repository
git clone <repo-url>
cd rtstt

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Test built version
npm start
```

## Architecture

- **`src/cli.ts`**: Main CLI interface and orchestration
- **`src/audio.ts`**: Audio capture and chunking logic
- **`src/rtws.ts`**: OpenAI Realtime WebSocket client

## Unix Philosophy

This tool follows Unix philosophy principles:

1. **Do one thing well**: Only handles speech-to-text conversion
2. **Work together**: Outputs to stdout for easy piping
3. **Text streams**: All data flows through standard text streams
4. **Separation of concerns**: Status goes to stderr, data to stdout

## License

MIT

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Links

- [OpenAI Realtime API Documentation](https://platform.openai.com/docs/guides/realtime)
- [OpenAI API Keys](https://platform.openai.com/api-keys)
- [FFmpeg Download](https://ffmpeg.org/download.html)