For agents – Manual

Deliver a script

TalkPatch has an inbox: ~/Library/Application Support/TalkPatch/Inbox/. Drop a .md or .txt file (UTF-8) in there and the running app picks it up within a second as a new script, selects it and moves the file to Inbox/Importiert/. If a script with that title already exists, its text is replaced: new version, same identifier, no restart. With the app closed, it happens at the next start.

cat > "$HOME/Library/Application Support/TalkPatch/Inbox/my-video.md" <<'TXT'
# My video

## Intro
Hello and welcome. Today it's about three things.

> Camera: close, smile

## Main part
First ...
TXT

Format

Line starts with	Meaning	Visible	Read aloud	Voice tracking
`# Title` (first line only)	script title; without it the file name is used	no	no	no
`## Chapter name`	chapter, reachable by key, remote or Stream Deck	yes	no	excluded
`> Stage direction`	a note to the speaker	editor only	no	excluded
everything else	prompter text	yes	yes	yes

No other Markdown. Umlauts as real characters. Write numbers the way they should be read out.

Live control

The running app offers a local HTTP API, the same one the Stream Deck plugin uses. It is reachable on your own Mac only (loopback) and protected by a token that is generated fresh at every start.

What	Value
Discovery	`~/Library/Application Support/TalkPatch/control.json` → `{"apiVersion":1,"port":43219,"token":"…"}`
State	`GET http://127.0.0.1:43219/v1/state`
Commands	`POST /v1/commands` with `{"name":"…","value":…}` or `{"commands":[…]}`; the response contains the new state
Auth	header `Authorization: Bearer <token>`

C="$HOME/Library/Application Support/TalkPatch/control.json"
TOKEN=$(python3 -c "import json;print(json.load(open('$C'))['token'])")
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:43219/v1/state
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"commands":[{"name":"setChapter","value":2},{"name":"perform","value":"togglePlayback"}]}' \
  http://127.0.0.1:43219/v1/commands

Commands: perform (togglePlayback, stop, reset, previousChapter, nextChapter, lineBack, lineForward, faster, slower, toggleSpeech, togglePrompter, toggleRingLight, toggleRecording, toggleRecordingPause, …), selectScript, setChapter, seek, setSpeed/adjustSpeed, setFontSize/adjustFontSize, setTextWidth/adjustTextWidth, setPrompterVisible, setHeadingsVisible, setSpeechTracking, setRingLight, adjustRingLightSize, setRecordingMode, setUI (panels, editor, camera, notch, window size), screenshot (own window as PNG).

Never edit library.json directly while the app is running: it writes after every change and overwrites anything edited from outside.