voice-memo

# Voice Memo

Send native iMessage voice bubbles (not file attachments) using ElevenLabs TTS and BlueBubbles.

## Quick Start

Run the script with text and recipient:

```bash
scripts/send-voice-memo.sh "Your message here" +14169060839
```

This will:
1. Generate TTS audio via ElevenLabs (Rachel voice by default)
2. Convert to Opus CAF @ 24kHz (iMessage native format)
3. Send as native voice bubble via BlueBubbles

## Requirements

- BlueBubbles running locally with Private API enabled
- ElevenLabs API key (for TTS)
- macOS (for `afconvert` audio conversion)
- Environment variables in `~/.openclaw/.env`:
  ```bash
  ELEVENLABS_API_KEY=your-key-here
  BLUEBUBBLES_PASSWORD=your-password-here
  # Optional overrides:
  ELEVENLABS_VOICE_ID=21m00Tcm4TlvDq8ikWAM  # Rachel (default)
  ELEVENLABS_MODEL_ID=eleven_turbo_v2_5      # Turbo v2.5 (default)
  ```

## The Working Formula

**Critical parameters discovered 2026-02-19:**

| Parameter | Value | Why |
|-----------|-------|-----|
| chatGuid | `any;-;+PHONE` | NOT `iMessage;-;` (causes timeouts) |
| method | `private-api` | Required for native bubble |
| isAudioMessage | `true` | Required |
| Audio format | Opus @ 24kHz in CAF | iMessage native format |
| Pre-convert | Yes | Don't let BlueBubbles convert (wrong codec) |

## Voice Options

**Default voice:** Rachel (ElevenLabs)
- Voice ID: `21m00Tcm4TlvDq8ikWAM`
- Model: `eleven_turbo_v2_5` (fast, natural)
- Cost: ~$0.04 per 30s message

**Expressive tags:**
- `[laughs]` — natural laughter
- `[sighs]` — expressive sigh
- `[excited]` — energetic delivery

Example: `"[excited] Oh my god, it worked!"`

For full voice list and IDs, see [VOICES.md](references/VOICES.md).

## Bidirectional Voice Memos

**Sending (Amz → Amy):**
Use this skill. Native voice bubbles appear with waveform UI.

**Receiving (Amy → Amz):**
BlueBubbles auto-converts incoming voice memos to MP3. OpenClaw transcribes via Whisper. Transcribed text flows into conversation context automatically.

**Memory note...

# iMessage Voice Memo Skill for OpenClaw

Send **native iMessage voice bubbles** (not file attachments) via BlueBubbles.

![Voice Bubble Demo](https://img.shields.io/badge/Status-Working-brightgreen)
![Platform](https://img.shields.io/badge/Platform-macOS-blue)
![License](https://img.shields.io/badge/License-MIT-yellow)

## Features

- 🎤 **Native voice bubbles** — Appears with waveform, tap to play (not as file attachment)
- 🗣️ **ElevenLabs TTS** — Natural-sounding voice synthesis
- ⚡ **Fast** — End-to-end in ~0.4 seconds
- 🔄 **Bidirectional** — Send and receive voice memos via iMessage

## Requirements

- **macOS** (for `afconvert`)
- **BlueBubbles Server** running locally with **Private API enabled**
- **ElevenLabs API key** (for TTS)

## Installation

1. Clone this repo:
```bash
git clone https://github.com/amzzzzzzz/imessage-voice-memo-skill.git
cd imessage-voice-memo-skill
```

2. Copy the skill to your OpenClaw workspace:
```bash
cp -r . ~/.openclaw/workspace/skills/voice-memo-imessage/
```

3. Add required environment variables to `~/.openclaw/.env`:
```bash
ELEVENLABS_API_KEY=your-key-here
BLUEBUBBLES_PASSWORD=your-bluebubbles-password
```

4. Make the script executable:
```bash
chmod +x ~/.openclaw/workspace/skills/voice-memo-imessage/send-voice-memo.sh
```

## Usage

### Command Line
```bash
./send-voice-memo.sh "Hey, how's it going?" +1234567890
```

### From OpenClaw Agent
The agent can invoke this skill to send voice responses.

## How It Works

### The Working Formula

After extensive debugging, we discovered the exact parameters needed for native voice bubbles:

```bash
# 1. Generate TTS (ElevenLabs)
curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/{voice_id}" \
  -d '{"text": "...", "model_id": "eleven_turbo_v2_5"}'

# 2. Convert to Opus CAF @ 24kHz (REQUIRED format for iMessage)
afconvert input.mp3 output.caf -f caff -d opus@24000 -c 1

# 3. Send via BlueBubbles with EXACT parameters
curl -X POST ".../api/v1/message/attachment" \
  --for...