Stream API - Eliza — ContextQMD

Endpoints

Method	Path	Description
POST	`/api/stream/live`	Start streaming (destination-managed)
POST	`/api/stream/offline`	Stop the active stream
GET	`/api/stream/status`	Current stream health and configuration
POST	`/api/stream/start`	Start streaming (direct RTMP)
POST	`/api/stream/stop`	Stop FFmpeg process
POST	`/api/stream/frame`	Pipe a raw image frame to FFmpeg
POST	`/api/stream/volume`	Set audio volume
POST	`/api/stream/mute`	Mute audio
POST	`/api/stream/unmute`	Unmute audio
GET	`/api/streaming/destinations`	List configured streaming destinations
POST	`/api/streaming/destination`	Set active streaming destination
GET	`/api/stream/overlay-layout`	Get overlay layout
POST	`/api/stream/overlay-layout`	Save overlay layout
GET	`/api/stream/voice`	Get voice (TTS) configuration
POST	`/api/stream/voice`	Save voice settings
POST	`/api/stream/voice/speak`	Manually trigger TTS on live stream
GET	`/api/stream/settings`	Get visual stream settings
POST	`/api/stream/settings`	Save visual stream settings

Stream Control

Start Stream (Destination-Managed)

POST /api/stream/live

Starts streaming using the configured destination adapter. Fetches RTMP credentials automatically from the active destination plugin.

Response:

json

{
  "ok": true,
  "live": true,
  "rtmpUrl": "rtmp://live.twitch.tv/app",
  "inputMode": "pipe",
  "audioSource": "tts",
  "destination": "twitch"
}

Stop Stream

POST /api/stream/offline

Stops the active stream and notifies the destination plugin.

Response:

json

{ "ok": true, "live": false }

Stream Status

GET /api/stream/status

Returns current stream health and configuration.

Response:

json

{
  "ok": true,
  "running": true,
  "ffmpegAlive": true,
  "uptime": 3742,
  "frameCount": 112260,
  "volume": 80,
  "muted": false,
  "audioSource": "tts",
  "inputMode": "pipe",
  "destination": "twitch"
}

Start Stream (Direct RTMP)

POST /api/stream/start

Backward-compatible explicit RTMP start with full parameter control. Prefer POST /api/stream/live for destination-managed starts.

Request body:

json

{
  "rtmpUrl": "rtmp://live.twitch.tv/app",
  "rtmpKey": "live_abc123",
  "inputMode": "testsrc",
  "resolution": "1280x720",
  "bitrate": "2500k",
  "framerate": 30
}

Field	Type	Required	Default	Notes
`rtmpUrl`	string	yes	—	Must start with `rtmp://` or `rtmps://`
`rtmpKey`	string	yes	—	Stream key
`inputMode`	string	no	`"testsrc"`	`"testsrc"`, `"avfoundation"`, or `"pipe"`
`resolution`	string	no	`"1280x720"`	Must match `/^\d{3,4}x\d{3,4}$/`
`bitrate`	string	no	`"2500k"`	Must match `/^\d+k$/`
`framerate`	number	no	`30`	Integer 1–60

Response:

json

{ "ok": true, "message": "Stream started" }

Stop Stream (Direct)

POST /api/stream/stop

Stops the active FFmpeg process and returns session uptime.

Response:

json

{ "ok": true, "uptime": 3742 }

uptime is in seconds.

Send Frame

POST /api/stream/frame

Pipes a raw JPEG/image frame buffer to FFmpeg. Used in pipe capture mode (desktop runtime page capture).

Request: Raw binary body (max 2 MB).

Response: 200 with empty body.

Errors: 400 empty body; 503 stream not running.

Stream Source

Get Stream Source

GET /api/stream/source

Returns the current stream capture source configuration.

Response:

json

{
  "source": {
    "type": "stream-tab",
    "url": "https://example.com"
  }
}

Field	Type	Description
`source.type`	string	Source type: `"stream-tab"`, `"screen"`, `"custom"`, etc.
`source.url`	string\|undefined	Custom URL when applicable

Set Stream Source

POST /api/stream/source

Switch the stream capture source.

Request body:

json

{
  "sourceType": "stream-tab",
  "customUrl": "https://example.com"
}

Field	Type	Required	Description
`sourceType`	string	no	Source type (default: `"stream-tab"`)
`customUrl`	string	no	Custom URL for the source

Response:

json

{
  "ok": true,
  "source": {
    "type": "stream-tab"
  }
}

Audio

Set Volume

POST /api/stream/volume

Request body:

json

{ "volume": 80 }

volume is an integer 0–100.

Response:

json

{ "ok": true, "volume": 80, "muted": false }

Mute

POST /api/stream/mute

Response:

json

{ "ok": true, "muted": true, "volume": 80 }

Unmute

POST /api/stream/unmute

Response:

json

{ "ok": true, "muted": false, "volume": 80 }

Destinations

List Destinations

GET /api/streaming/destinations

Returns all configured streaming destinations from the multi-destination registry. Each destination indicates whether it is the currently active target.

Response:

json

{
  "ok": true,
  "destinations": [
    { "id": "twitch", "name": "Twitch", "active": true },
    { "id": "youtube", "name": "YouTube", "active": false },
    { "id": "pumpfun", "name": "pump.fun", "active": false },
    { "id": "x", "name": "X/Twitter", "active": false }
  ]
}

Field	Type	Description
`destinations[].id`	string	Unique destination identifier
`destinations[].name`	string	Human-readable destination name
`destinations[].active`	boolean	Whether this destination is currently selected for streaming

The active destination defaults to the first registered destination when no explicit selection has been made.

Set Active Destination

POST /api/streaming/destination

Switches the active streaming destination at runtime. The selected destination is used for subsequent POST /api/stream/live calls to resolve RTMP credentials automatically.

Request body:

json

{ "destinationId": "twitch" }

Field	Type	Required	Description
`destinationId`	string	yes	ID of the destination to activate (must match a registered destination)

Response (200):

json

{
  "ok": true,
  "destination": { "id": "twitch", "name": "Twitch" }
}

Errors:

Status	Body	Condition
`400`	`{ "error": "destinationId is required" }`	Missing or empty `destinationId`
`404`	`{ "error": "Unknown destination: <id>" }`	No registered destination matches the provided ID
`500`	`{ "error": "<message>" }`	Unexpected server error

Overlays

Get Overlay Layout

GET /api/stream/overlay-layout

Query params:

Param	Type	Required	Description
`destination`	string	no	Destination ID for per-destination layouts

Response:

json

{
  "ok": true,
  "layout": {
    "version": 1,
    "widgets": [...]
  },
  "destinationId": "twitch"
}

Save Overlay Layout

POST /api/stream/overlay-layout

Request body:

json

{
  "layout": {
    "version": 1,
    "widgets": [...]
  }
}

Response:

json

{ "ok": true }

Voice (TTS-to-RTMP)

Get Voice Config

GET /api/stream/voice

Returns voice configuration and current speaking status.

Response:

json

{
  "ok": true,
  "enabled": true,
  "autoSpeak": true,
  "provider": "elevenlabs",
  "configuredProvider": "elevenlabs",
  "hasApiKey": true,
  "isSpeaking": false,
  "isAttached": true
}

Save Voice Settings

POST /api/stream/voice

Request body:

json

{
  "enabled": true,
  "autoSpeak": true,
  "provider": "elevenlabs"
}

Response:

json

{ "ok": true }

Speak Text

POST /api/stream/voice/speak

Manually trigger TTS on the live stream.

Request body:

json

{ "text": "Hello, stream!" }

Constraint	Value
Max text length	2000 characters
Rate limit	One at a time (429 if speaking)
Requires	Stream must be live, TTS bridge attached

Response:

json

{ "ok": true }

Errors: 400 text missing/too long; 429 already speaking; 503 bridge not attached.

Stream Source

Get Stream Source

GET /api/stream/source

Returns the current stream input source configuration.

Response:

json

{
  "source": {
    "type": "stream-tab",
    "url": null
  }
}

Set Stream Source

POST /api/stream/source

Switch the stream input source.

Request body:

json

{
  "sourceType": "custom-url",
  "customUrl": "https://example.com/stream"
}

Field	Type	Required	Description
`sourceType`	string	no	Source type (default: `"stream-tab"`)
`customUrl`	string	no	Custom URL for the source (only used with custom-url type)

Response:

json

{
  "ok": true,
  "source": {
    "type": "custom-url",
    "url": "https://example.com/stream"
  }
}

Visual Settings

Get Stream Settings

GET /api/stream/settings

Response:

json

{
  "ok": true,
  "settings": {
    "theme": "eliza",
    "avatarIndex": 0
  }
}

Save Stream Settings

POST /api/stream/settings

Request body:

json

{
  "settings": {
    "theme": "eliza",
    "avatarIndex": 2
  }
}

Response:

json

{ "ok": true }