Complete block reference (25 blocks)

TurboWarp OpenAI Realtime

Talk with the OpenAI Realtime API by voice or text from TurboWarp, and let the model call functions written in blocks. The API key stays in a localhost relay.

Before you start

  1. Start @kubohiroya/capability-proxy on 127.0.0.1 with the openai provider configured. Note the eight-digit pairing code it prints.
  2. Load turbowarp-openai-realtime-api.js as a custom extension with Run without sandbox enabled.

First conversation

configure local relay [http://127.0.0.1:8787]
pair local relay with one-time code [12345678]
connect to Realtime with microphone [on]
send text [Hello!]

when assistant finishes responding
say (last assistant response)

Functions as tools

Write a define function script and choose export as tool. NAME, DESCRIPTION, and the JSON args schema must be typed directly into the hat. When the model calls the tool, read arguments with function argument and send the result with return.

define function [get_score] description [Returns the player's score.] args schema [{"type":"object","properties":{}}] export as [tool]
return (join [{"score":] (join (score) [}]))

Safety

Full block reference: README.

OpenAI Realtime: complete block reference

All 25 blocks are documented below, including compatibility blocks and blocks available through optional features. Select a block to read its behavior, arguments, default values, and menu choices. Each block has a permanent link.

configure local relay [ENDPOINT]

Sets the loopback origin of the local capability-proxy relay. Clears any previous pairing.

Block type: COMMAND. Opcode: configureRelay. Permanent link

ArgumentTypeDefault valueMenu choices
ENDPOINTSTRINGhttp://127.0.0.1:8787

pair local relay with one-time code [CODE]

Exchanges the eight-digit code printed by the relay for a session token kept only in memory.

Block type: COMMAND. Opcode: pairRelay. Permanent link

ArgumentTypeDefault valueMenu choices
CODESTRING00000000

local relay paired?

Reports whether an unexpired relay session token is held in memory.

Block type: BOOLEAN. Opcode: isRelayPaired. Permanent link

This block has no arguments.

set instructions to [TEXT]

Sets the system instructions used by the next connection.

Block type: COMMAND. Opcode: setInstructions. Permanent link

ArgumentTypeDefault valueMenu choices
TEXTSTRINGYou are a friendly assistant. Answer briefly.

set voice to [VOICE]

Sets the output voice used by the next connection.

Block type: COMMAND. Opcode: setVoice. Permanent link

ArgumentTypeDefault valueMenu choices
VOICESTRINGmarin
  • alloy
  • ash
  • ballad
  • cedar
  • coral
  • echo
  • marin
  • sage
  • shimmer
  • verse

Fixed literal fields: MODE. Editing UI and preservation rules.

set output to [MODE]

Chooses spoken audio or text-only responses for the next connection.

Block type: COMMAND. Opcode: setOutputMode. Permanent link

ArgumentTypeDefault valueMenu choices
MODESTRINGaudio
  • audio
  • text

set model to [MODEL]

Chooses the Realtime model for the next connection. The relay only accepts models its operator allows; empty uses the relay default.

Block type: COMMAND. Opcode: setModel. Permanent link

ArgumentTypeDefault valueMenu choices
MODELSTRINGgpt-realtime-2.1-mini
  • gpt-realtime-2.1-mini
  • gpt-realtime-2.1

Fixed literal fields: SECONDS. Editing UI and preservation rules.

set session time limit to [SECONDS] seconds

Disconnects automatically after this many seconds from the next connection on. 0 disables the limit.

Block type: COMMAND. Opcode: setSessionTimeLimit. Permanent link

ArgumentTypeDefault valueMenu choices
SECONDSNUMBER600

Fixed literal fields: MICROPHONE. Editing UI and preservation rules.

connect to Realtime with microphone [MICROPHONE]

Mints an ephemeral key through the relay and opens a WebRTC session. Exported functions become tools.

Block type: COMMAND. Opcode: connect. Permanent link

ArgumentTypeDefault valueMenu choices
MICROPHONESTRINGon
  • on
  • off

disconnect from Realtime

Closes the WebRTC session, stops the microphone, and fails pending function calls.

Block type: COMMAND. Opcode: disconnect. Permanent link

This block has no arguments.

connected to Realtime?

Reports whether the Realtime session is open.

Block type: BOOLEAN. Opcode: isConnected. Permanent link

This block has no arguments.

Realtime connection state

Reports disconnected, connecting, connected, or failed.

Block type: REPORTER. Opcode: connectionState. Permanent link

This block has no arguments.

Realtime model

Reports the model the relay used for the current or last connection.

Block type: REPORTER. Opcode: currentModel. Permanent link

This block has no arguments.

session elapsed seconds

Reports seconds since the current session connected, or 0 when disconnected.

Block type: REPORTER. Opcode: sessionElapsed. Permanent link

This block has no arguments.

when session time limit is reached

Starts after the session time limit disconnects the session.

Block type: HAT. Opcode: whenSessionTimeLimitReached. Permanent link

This block has no arguments.

send text [TEXT]

Adds a user text message to the conversation and asks for a response.

Block type: COMMAND. Opcode: sendText. Permanent link

ArgumentTypeDefault valueMenu choices
TEXTSTRINGHello!

when assistant finishes responding

Starts when a response that contains assistant text or transcript completes.

Block type: HAT. Opcode: whenResponseDone. Permanent link

This block has no arguments.

last assistant response

Reports the text or audio transcript of the most recent completed assistant response.

Block type: REPORTER. Opcode: lastResponseText. Permanent link

This block has no arguments.

Fixed literal fields: EXPORT. Editing UI and preservation rules.

define function [NAME] description [DESCRIPTION] args schema [SCHEMA] export as [EXPORT]

Defines a function value. With export as tool, the model can call it; NAME, DESCRIPTION, and SCHEMA must be literal text.

Block type: HAT. Opcode: defineFunction. Permanent link

ArgumentTypeDefault valueMenu choices
NAMESTRINGget_score
DESCRIPTIONSTRINGReturns the player's current score.
SCHEMASTRING{"type":"object","properties":{}}
EXPORTSTRINGtool
  • tool
  • none

function argument [PATH]

Inside a function, reports the argument at a dotted path such as city or items.0.name.

Block type: REPORTER. Opcode: functionArgument. Permanent link

ArgumentTypeDefault valueMenu choices
PATHSTRINGcity

function arguments JSON

Inside a function, reports all arguments as JSON text.

Block type: REPORTER. Opcode: functionArgumentsJson. Permanent link

This block has no arguments.

return [VALUE]

Inside a function, returns a value and ends the script. JSON text is returned as JSON; other text is returned as a string.

Block type: COMMAND. Opcode: returnValue. Permanent link

ArgumentTypeDefault valueMenu choices
VALUESTRING{"score":10}

Fixed literal fields: FIELD. Editing UI and preservation rules.

Realtime usage [FIELD]

Reports token usage totals since the last reset. costUSD is an estimate from published prices; the OpenAI dashboard is authoritative.

Block type: REPORTER. Opcode: usageValue. Permanent link

ArgumentTypeDefault valueMenu choices
FIELDSTRINGcostUSD
  • costUSD
  • responses
  • inputTokens
  • outputTokens
  • cachedInputTokens
  • textInputTokens
  • audioInputTokens
  • textOutputTokens
  • audioOutputTokens

reset Realtime usage

Clears the usage totals.

Block type: COMMAND. Opcode: resetUsage. Permanent link

This block has no arguments.

last Realtime error

Reports the most recent relay, connection, or API error, or an empty string.

Block type: REPORTER. Opcode: lastError. Permanent link

This block has no arguments.

Repository guide and examples

Fixed input editing

With a compatible TurboWarp GUI, enable fixed-input forms to edit only standard literal fields. Numbers use complete finite JSON number tokens; menu fields use existing choices. Connected reporters and unavailable fields stay read-only and are never evaluated. Saving an unchanged form preserves exact existing raw values, including legacy spellings and unknown choices. Invalid drafts stay in the same editing session; cancel, project/target replacement, or block removal discards them. Disabling the GUI feature flag restores native field editing. This form does not run blocks, open network/audio/key/QR sessions, resolve names, or edit Schema arguments.