spaces-listener

Record, transcribe, and summarize X/Twitter Spaces — live or replays. Supports multiple concurrent recordings.

Commands

# Start recording (runs in background)
spaces listen <url>

# Record multiple Spaces at once
spaces listen "https://x.com/i/spaces/1ABC..."
spaces listen "https://x.com/i/spaces/2DEF..."

# List all active recordings
spaces list

# Check specific recording status
spaces status 1

# Stop a recording
spaces stop 1
spaces stop all

# Clean stale pid/meta files
spaces clean

# Transcribe when done
spaces transcribe ~/Desktop/space.m4a --model medium

# Summarize an existing transcript
spaces summarize ~/Desktop/space_transcript.txt

# Skip summarization
spaces transcribe ~/Desktop/space.m4a --no-summarize

Requirements

brew install yt-dlp ffmpeg openai-whisper

For summaries, set OPENAI_API_KEY (transcription still works without it).

How It Works

1. Each spaces listen starts a new background recording with a unique ID
2. Recordings persist even if you close terminal
3. Run spaces list to see all active recordings
4. When done, spaces stop <id> or spaces stop all
5. Transcribe with spaces transcribe <file>
6. Summaries are generated automatically after transcription (skip with --no-summarize)

Output

Each space gets its own folder under ~/Dropbox/ClawdBox/XSpaces/:

~/Dropbox/ClawdBox/XSpaces/
  space_username_2026-02-03_1430/
    recording.m4a     — audio
    recording.log     — progress log
    transcript.txt    — transcript
    summary.txt       — summary

Critical: Agent Usage Rules

NEVER set a timeout on Space downloads. Spaces can be hours long. yt-dlp stops automatically when the Space ends — don't kill it early.

The correct workflow:

1. Run spaces listen <url> — it starts a background process and returns immediately
2. Set a cron job (every 5–10 min) to check spaces list
3. When recording shows "No active recordings", it's done
4. Transcribe the audio file, summarize, notify the user
5. Delete the cron job

Do NOT:

• Use exec with a timeout for downloads
• Run competing download processes for the same Space
• Kill the download process manually (unless the user asks)

Audio is staged in /tmp/spaces-listener-staging/ during recording, then automatically copied to the final Dropbox output dir when complete. This avoids Dropbox file-locking issues during long downloads.

Whisper Models