read-aloud

# read-aloud - Text to Speech with Playback

Convert text to speech and play it immediately. Automatically chunks long text.

## Usage

```bash
echo "Hello world" | read-aloud
cat document.txt | read-aloud --strip-md true
```

## Arguments

| Flag | Default | Description |
|------|---------|-------------|
| `--voice` | en-US-Neural2-J | Voice name |
| `--lang` | en-US | Language code |
| `--speed` | 1.0 | Speaking rate (0.25 to 4.0) |
| `--strip-md` | false | Strip markdown formatting |
| `--session-id` | (none) | Session ID for stop signal support |
| `--no-cache` | false | Bypass cache and always generate fresh audio |
| `--clear-cache` | false | Clear all cached audio files before running |

## Features

- **Auto-chunking**: Splits text >5000 bytes at sentence boundaries
- **Markdown stripping**: Remove `#`, `*`, `` ` ``, links, etc. for cleaner speech
- **Caching**: Audio files are cached in `~/.cache/read-aloud/` based on content hash (text + voice + lang + speed)
- **Stoppable**: With `--session-id`, creates `/tmp/read-aloud-{id}.running` and checks for `/tmp/read-aloud-{id}.stop` between chunks
- **Cleanup**: Temp files automatically deleted after playback (cached files are preserved)

## Stop Signal

When using `--session-id`, you can stop playback by creating a stop file:

```bash
# Start reading with session ID
echo "Long text..." | read-aloud --session-id abc123 &

# Stop it
touch /tmp/read-aloud-abc123.stop
```

The tool checks for the stop file between chunks and exits gracefully.

## Caching

Audio files are automatically cached to avoid repeated API calls:

- **Cache location**: `~/.cache/read-aloud/`
- **Cache key**: SHA256 hash of (text + voice + lang + speed)
- Subsequent reads of the same content play instantly from cache

```bash
# First read: calls TTS API, saves to cache
echo "Hello" | read-aloud

# Second read: plays from cache (instant, no API call)
echo "Hello" | read-aloud

# Bypass cache for fresh generation
echo "Hello" | read-aloud --no-cache true

# Clear all cached files
read-aloud --clear-cache true

# Check cache size
du -sh ~/.cache/read-aloud/
```

## Requirements

- Google Cloud Text-to-Speech API (uses `tts` tool)
- `mpg123` audio player: `sudo apt install mpg123`

## Examples

```bash
# Read a file
cat article.txt | read-aloud

# Read markdown cleanly
cat README.md | read-aloud --strip-md true

# Faster playback
cat notes.txt | read-aloud --speed 1.3

# Stoppable session
cat longdoc.txt | read-aloud --session-id mysession &
# Later: touch /tmp/read-aloud-mysession.stop

# Chain with other tools
cat error.log | explain-error | read-aloud
git diff | summarize | read-aloud
```

## Dependencies

- `tts` - for speech synthesis
- `mpg123` - for audio playback