Screen Narrator

Live screen narration via Gemini vision + ElevenLabs TTS. 7 styles with per-style voices and ambient tracks.

Commands

Start

tmux new-session -d -s narrator "cd {baseDir} && 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 {baseDir} && python -m narrator wrestling -t 5m --control-file /tmp/narrator-ctl.json --status-file /tmp/narrator-status.json"

Change style

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

Change 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

Multiple commands

echo '[{"command": "style", "value": "noir"}, {"command": "profanity", "value": "high"}]' > /tmp/narrator-ctl.json

Check status

cat /tmp/narrator-status.json

Stop

tmux kill-session -t narrator

Styles

| Style | Vibe | |---|---| | sports | Punchy play-by-play announcer | | nature | David Attenborough documentary | | horror | Creeping dread, ominous foreshadowing | | noir | Hard-boiled detective narration | | reality_tv | Reality TV confessional booth | | asmr | Whispered meditation | | wrestling | BAH GAWD maximum hype announcer |

Control commands

| Command | Value | Example | |---|---|---| | style | Style name | {"command": "style", "value": "wrestling"} | | profanity | off, low, high | {"command": "profanity", "value": "low"} | | pause | (none) | {"command": "pause"} | | resume | (none) | {"command": "resume"} |

Common requests

• "narrate my screen" / "roast my screen" -> Start with sports
• "haunt my screen" -> Start with horror
• "narrate for 5 minutes" -> Use -t 5m
• "switch to wrestling" -> Write style command to control file
• "make it family friendly" -> Set profanity to off
• "pause" / "shut up" -> Pause command
• "stop narrating" -> tmux kill-session -t narrator