---
title: "Meet adapter"
description: "How meetctl cuts, closes and sends the Meet far leg: the --far-cut, --turn-close, --provisional and --realtime flags, their defaults and rollbacks, and the fixture numbers behind each (latency, cpWER, labels, replaces)."
type: "living"
source: "docs/meetctl.md"
verified: "2026-11-14"
group: "Adapters and integrations"
---

> **Living doc**, checked against the code 2026-11-14

`meetctl` is the capture adapter of the Meet local path (ADR 0039). Its source is `tools/meet/meetctl.swift` and
`just build-meetctl` builds it. It takes the mic as the near leg and the browser's tapped output as the far leg,
decodes both with Parakeet, and sends [meeting.v1](/docs/contracts/meeting.v1) events to the Gateway. The full usage is
in [`reference/cli.md`](/docs/reference/cli#meetctl).

This page covers the four flags that decide **when a far line goes out and what it holds**, and two labels that write
rows and change no line. The numbers come from a scripted two-voice fixture replayed on the laptop. No live call is
measured yet.

Every flag here needs `--diarizer streaming --sortformer <meet-sortformer>`. The far leg is then labeled as it streams,
by FluidAudio's Sortformer with Vulpine's clock fix (`just build-meet-sortformer`). Without the stream, far lines are the
silence-aligned windows, labeled by polyvoice after the call.


## The flags

| flag | values (default first) | what it decides | rollback |
|---|---|---|---|
| `--far-cut` | `turns` \| `windows` | a far line is one speaker turn from the stream's marks, or one silence-aligned window | `windows` |
| `--turn-close` | `mark` \| `window` | a held turn closes when the stream marks the next speaker, or when that speaker's first window closes | `window` |
| `--provisional` | `first` \| `every` \| `off` | a line sent at a pause inside a held turn, later replaced by the turn's line | `off` |
| `--realtime` | (fixture mode only) | feed the fixture's legs at 1x wall time in 20 ms blocks and log each line's send time | leave it off |
| `--cut-mixed-share` | off \| a share in (0, 0.5] | a turn cut whose second voice holds at least that share of its seconds is labeled `mixed` (a row, not a line change) | leave it off |
| `--cut-uncertain-band` | off \| a margin in (0, 1) | a turn cut whose embedding margin is inside the band is labeled `uncertain`; no margin exists at runtime yet | leave it off |

### `--far-cut turns|windows`

- **`turns`**: the far leg's audio is held until the stream has marked it, then cut into one decoder window per
  speaker turn (`planFarTurns` in `meet_events.swift`). A turn runs from its first mark − 0.2 s to its last mark +
  0.2 s. A gap between turns is split at its middle, so no unmarked audio is dropped. A stretch that only another
  speaker holds is muted inside the cut. Where two turns overlap, both cuts keep the shared stretch. A flicker does
  not open a turn: a turn under 1 s between two turns of one other speaker, with no pause on either side, and under
  half of it spoken over that voice. Each cut goes out with its own speaker's live name (`far-1`, `far-2`, …).
- **`windows`**: one line per silence-aligned window (450 ms of silence closes it, 15 s cap), labeled by the speaker
  the stream marks most in it.
- **Measured**: `turns` takes the overlapping pair's cpWER from 59.5 % to **8.1 %** on the clean leg, and the whole
  far leg from 9.3 % to **1.9 %**.


### `--turn-close mark|window`

- **`mark`**: the open window's audio is held too. The turns are planned again each time the stream says more, over
  the audio it has consumed (`farTurnsAtMark`). A turn closes as soon as its own marks + 0.2 s end inside that audio
  and the next turn is past the flicker rule (a pause of 0.25 s before it, 1 s of marks, or a turn after it). The last
  turn still waits for the far leg to go quiet (0.65 s) or the 15 s cap.
- **`window`**: a held turn closes only when the next turn's first window closes.
- **A mark the stream takes back**: the close acts on tentative marks, which the stream can revise. The closed line
  stands and is never re-sent. A new line follows under the speaker who goes on, starting where the closed cut ended
  (`cutUntil`), so no audio lands in two lines. No `replaces` goes out beyond the provisional one. The receipt counts
  these closes (`marks_retracted`, `closed_cuts_revised`, `revised_s`).
- **An interjection** keeps its own line under its own live name. It is a turn under 1 s of marks, between two turns of
  one other speaker, spoken over that voice for at least half its marks, as one unbroken run of the stream's 80 ms
  frames. Its cut runs from one frame before its first mark to its last mark's end, with no pad. It never owns a
  provisional, and the after-call pass never re-sends it (`afterCallResend`). A back-channel the stream never marks is
  not forced; the fixture receipt counts it as `interjections_unlabeled`.
- **Measured**: with `mark`, the turn-close line goes out **2.0–3.1 s** after the speaker's last word at p50 and
  2.1–3.5 s at p90. With `window` it is 6.5–7.0 s and 9.4–12.2 s. The far lines are the same in both modes.


### `--provisional first|every|off`

- A provisional line goes out at a pause inside a held turn: a far window closed on 450 ms of silence and the far leg
  resumed before the turn closed. The turn's cut up to the pause is decoded and sent with the turn's live name. The
  turn-close line carries `replaces: {from_seq: p, to_seq: p}` for it, so the Gateway deletes it and the stored
  transcript holds the turn's line alone. `first`: one per turn, at its first pause. `every`: one at each pause, each
  replacing the one before. `off`: turn-close lines only, no `replaces` during the call.
- **Measured with `--turn-close mark`**: `off` gives first sight of a turn at 2.0–2.4 s p50. `first` and `every` take
  the p50 to 1.5–2.0 s. Every provisional line is replaced live, and no line is re-sent after the call. `first` is the
  default.


### `--realtime`

- Fixture mode only (`meetctl start --fixture <dir> --realtime`). Both legs are fed from the files at 1x wall time in
  20 ms blocks. There is no audio device and nothing is audible. Each segment's send time goes to `emitted.jsonl` in
  the session (seq, leg, time, the replaced seq; no text). The receipt's `realtime` block records the wall instant of
  far-leg second 0 (`t0_ms`) and the blocks fed more than 20 ms late. Without the flag a fixture is read at file
  speed, which says nothing about latency.
- The decoder loads at call start in every mode (`decode.ready_at_ms`). A slow load (up to 84 s under load on the
  laptop) happens before the first block, not at the first far line.

### `--cut-mixed-share S` and `--cut-uncertain-band B` (below the turn)

- These run the per-cut rule of `tools/meet/cut_labels.py` in Swift (`labelCut` in `meet_events.swift`). Both are
  off by default. A value out of range is refused before anything is spooled (`bad_cut_label_flag`); the ranges match
  the Python. Both flags need `--far-cut turns`; otherwise meetctl refuses with `cut_labels_need_turn_cut`.
- For each decoded turn cut, each flag that is on writes one row to the session's `meet_cuts.jsonl`. The rows hold
  numbers and reason words only:
  - `meet_cut_mixed {cut, mixed, share, threshold, source: diarizer}`. The share is the second voice's part of the
    stream's own segments inside the cut's audio, with the muted stretches left out.
  - `meet_cut_uncertain {cut, uncertain, margin: null, band, reason: no_margin}`. meetctl runs no embedder, so the
    band is a no-op that says so.
- One reason per cut, in the order tie > short > mixed > uncertain. The receipt's `stream_diarizer` counts
  `cuts_mixed` and `cuts_uncertain` apart, plus `cut_label_rows` and the flags in force.
- The rows label the cut only. A line's text, speaker and `replaces` are the same with the flags on or off.


## What the receipt says about a run

`meetctl`'s receipt (stdout, and the state file) carries counts only, never text:

- `stream_diarizer`: `far_cut`, `turn_close`, `turns`, `turns_overlapped`, `turns_forced`, `turns_closed_on_mark`,
  `marks_retracted`, `closed_cuts_revised`, `revised_s`, `interjections`, the stream's own label latencies, its peak
  footprint; with the cut flags, `cut_label_rows`, `cuts_mixed`, `cuts_uncertain` and the two flag values.
- `decode`: windows decoded, `provisional` and `provisional_replaced`, `load_ms`, `ready_at_ms`.
- `diarizer`: polyvoice's after-call pass, `replaces` (the lines re-sent with a corrected label), `interjections_kept`
  (interjection lines it would have relabelled, kept under the stream's name).
- `realtime` (fixture with `--realtime`): `t0_ms`, `fed_s`, `late_blocks`, `emitted_log`.

