Session Config - MediSync API

The config frame

Your first message after connecting must be a single JSON text frame with type: "config". It declares your audio format, an optional language hint, how speech should be chunked, and whether to separate speakers. Send it immediately on open — the server waits about 10 seconds for it.

{
  "type": "config",
  "audio":   { "encoding": "pcm_s16le", "sample_rate": 16000, "channels": 1 },
  "language": "de",
  "chunk":    { "strategy": "balanced" },
  "diarization": { "enabled": false, "max_speakers": 2 },
  "timeline_offset_seconds": 0
}

Unknown or extra top-level fields are rejected — a config with fields the server does not recognize fails validation and the socket is closed with a config_invalid error. Send only the fields documented below.

Fields

type

string

required

Must be the literal string "config".

audio

audio.encoding

string

default:"pcm_s16le"

Audio wire format. One of "pcm_s16le" (raw 16-bit little-endian PCM — preferred) or "wav".

audio.sample_rate

integer

default:"16000"

Sample rate in Hz. Accepted range 8000–48000. 16000 is recommended.

audio.channels

integer

default:"1"

Channel count. 1 (mono, recommended) or 2.

language

string

Optional ISO 639-1 language hint (for example "de", "en", "fr"). Case-insensitive. The service auto-detects language regardless, and the detected code is returned on each transcript as language_detected. An unrecognized code is tolerated as a soft hint (a warning is surfaced in session_ready). See supported languages.

chunk

Controls how the incoming stream is cut into finalized segments. Pick a strategy to trade latency against accuracy and density; you rarely need the explicit overrides.

chunk.strategy

string

default:"balanced"

One of:

"low_latency" — shortest segments, fastest captions.
"balanced" — the default; a good compromise of latency and accuracy.
"high_throughput" — longest segments, highest accuracy and text density (most context per segment).

chunk.target_seconds

number

Optional explicit target segment length, in seconds. Overrides the strategy’s target. Server-clamped to [0.5, 25].

chunk.max_seconds

number

Optional hard cap on segment length, in seconds. Overrides the strategy’s cap. Server-clamped to [target, 25].

Silence is trimmed and segments are cut on natural pauses automatically. You do not need to align your binary frames to any boundary — send audio in whatever size is convenient and the server re-frames it internally.

diarization

diarization.enabled

boolean

default:"false"

Turn speaker separation on or off. When on, transcript frames include a speakers array of per-speaker turns. Off by default.

diarization.max_speakers

integer

default:"2"

A hint for how many distinct speakers to expect (range 1–20). For a clinician/patient conversation, 2 is typical.

timeline_offset_seconds

number

default:"0"

A constant (seconds, >= 0) added to every emitted segment, word, and speaker timestamp for this session. Leave it at 0 for a normal session. On a reconnect mid-recording, set it to the last processed_until you received so all transcripts stay on one continuous absolute timeline with no client-side re-anchoring. See Reconnection.

Strategy behavior

low_latency

Emits short segments for the fastest possible captions. Best for live on-screen dictation where responsiveness matters most.

balanced

The default. Segments are long enough for strong accuracy while still feeling live. A good starting point for most integrations.

high_throughput

Emits longer segments with the most context, maximizing accuracy and text density. Best when a small extra delay is acceptable.

Defaults & clamping

If you omit a field, its default is applied. Numeric segment lengths are then clamped to server-safe bounds, and any adjustment is reported back in session_ready.warnings.

Field	Default	Notes
`audio.encoding`	`pcm_s16le`	`wav` also accepted
`audio.sample_rate`	`16000`	clamped to 8000–48000
`audio.channels`	`1`	1 or 2
`language`	(none)	auto-detect; hint only
`chunk.strategy`	`balanced`
`chunk.target_seconds`	(from strategy)	clamped to [0.5, 25]
`chunk.max_seconds`	(from strategy)	clamped to [target, 25]
`diarization.enabled`	`false`
`diarization.max_speakers`	`2`	1–20
`timeline_offset_seconds`	`0`	`>= 0`

Do not hard-code specific segment lengths unless you have a reason to. Choosing a strategy and letting the server pick the target keeps your integration forward-compatible.

session_ready

Once your config is validated, the server replies with session_ready, echoing the effective (validated and clamped) configuration and any warnings. This is your signal to start streaming audio.

{
  "type": "session_ready",
  "session_id": "f0c1a9b2c3d4e5f6a7b8c9d0e1f2a3b4",
  "effective": {
    "language": "de",
    "diarization": false,
    "chunk": {
      "strategy": "balanced",
      "target_seconds": 5.0,
      "max_seconds": 20.0
    },
    "timeline_offset_seconds": 0
  },
  "server": {
    "max_segment_seconds": 25.0,
    "protocol_version": "2.0"
  },
  "warnings": []
}

session_id

string

Unique identifier for this session.

effective

object

The configuration the server actually applied, after defaults and clamping.

Show effective

language

string | null

The language hint in effect, or null if none was provided.

diarization

boolean

Whether speaker separation is on for this session.

chunk

object

The chunking policy in effect: strategy, target_seconds, and max_seconds.

timeline_offset_seconds

number

The absolute-timeline offset applied to every emitted timestamp.

server

object

Server-side limits and metadata: max_segment_seconds (the hard maximum segment length) and protocol_version (currently "2.0").

warnings

string[]

Human-readable notes about adjustments the server made — for example a clamped segment length, or an unrecognized language hint. Empty when nothing was changed.

The effective object may include additional server-selected fields beyond those listed here. Treat any field you do not recognize as opaque and ignore it — your integration should key only on the documented fields.

Example: a clamped config

If you request chunk.target_seconds: 40, the server clamps it and tells you:

{
  "type": "session_ready",
  "session_id": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
  "effective": {
    "language": "en",
    "diarization": true,
    "chunk": { "strategy": "high_throughput", "target_seconds": 25.0, "max_seconds": 25.0 },
    "timeline_offset_seconds": 0
  },
  "server": { "max_segment_seconds": 25.0, "protocol_version": "2.0" },
  "warnings": [
    "target_seconds clamped to [0.5, 25.0]",
    "max_seconds clamped to [25.0, 25.0]"
  ]
}

Supported languages

Language is auto-detected; the language field is only a hint. The following European languages are recognized (ISO 639-1). Mid-conversation language switches are handled automatically.

Language	Code	Language	Code	Language	Code
Bulgarian	`bg`	Greek	`el`	Portuguese	`pt`
Croatian	`hr`	Hungarian	`hu`	Romanian	`ro`
Czech	`cs`	Italian	`it`	Russian	`ru`
Danish	`da`	Latvian	`lv`	Slovak	`sk`
Dutch	`nl`	Lithuanian	`lt`	Slovenian	`sl`
English	`en`	Maltese	`mt`	Spanish	`es`
Estonian	`et`	Polish	`pl`	Swedish	`sv`
Finnish	`fi`	German	`de`	Ukrainian	`uk`
French	`fr`

Passing a code outside this set is not an error — it is accepted as a soft hint (with a warning in session_ready), and detection still runs.

Next steps

Messages

Stream audio and read transcript, ack, backpressure, and status frames.

Reconnection

Use timeline_offset_seconds to resume on one continuous timeline.

​The config frame

​Fields

​type

​audio

​language

​chunk

​diarization

​timeline_offset_seconds

​Strategy behavior

low_latency

balanced

high_throughput

​Defaults & clamping

​session_ready

​Example: a clamped config

​Supported languages

​Next steps

Messages

Reconnection

The config frame

Fields

type

audio

language

chunk

diarization

timeline_offset_seconds

Strategy behavior

Defaults & clamping

session_ready

Example: a clamped config

Supported languages

Next steps