Narrator

Live narration of your macOS screen activity with Gemini vision + ElevenLabs speech.

Screen Narrator

This skill maps to the upstream narrator repo implementation.

It runs Gemini-vision narration styles (sports, nature, horror, noir, reality_tv, asmr, wrestling) and ElevenLabs TTS, with optional dual-lane narration and live control via JSON files.

Source of truth

Use the repo install:

cd /Users/buddy/narrator
/Users/buddy/narrator/.venv/bin/python -m narrator sports --help

Setup

cd /Users/buddy/narrator
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Required environment:

• GEMINI_API_KEY
• ELEVENLABS_API_KEY
• optional: ELEVENLABS_VOICE_ID

Runtime control commands

Start live narration in a tmux session (preferred):

tmux new-session -d -s narrator "cd /Users/buddy/narrator && /Users/buddy/narrator/.venv/bin/python -m narrator sports --control-file /tmp/narrator-ctl.json --status-file /tmp/narrator-status.json"

Start with timer:

tmux new-session -d -s narrator "cd /Users/buddy/narrator && /Users/buddy/narrator/.venv/bin/python -m narrator wrestling --time 5m --control-file /tmp/narrator-ctl.json --status-file /tmp/narrator-status.json"

Change style on the fly:

echo '{"command": "style", "value": "horror"}' > /tmp/narrator-ctl.json

Set profanity:

echo '{"command": "profanity", "value": "low"}' > /tmp/narrator-ctl.json

Pause / resume:

echo '{"command": "pause"}' > /tmp/narrator-ctl.json
echo '{"command": "resume"}' > /tmp/narrator-ctl.json

Stop:

tmux kill-session -t narrator

Check status:

cat /tmp/narrator-status.json

Notes

• macOS only (screen capture + TTS/audio).
• This OpenClaw skill wrapper is aligned to the /Users/buddy/narrator implementation to avoid drift between docs and runtime.