tl;dv Connector

Ingest tl;dv meeting recordings and speaker-segmented transcripts into CortexDB.

Captures tl;dv meetings and their speaker-segmented transcripts as CortexDB experiences — one episode per meeting, stamped with the meeting's real time so your meeting timeline is queryable alongside everything else.

Two ways to run this connector

Self-hosted — pip install cortexdb-connectors then cortexdb-sync sync tldv. Managed — CortexDB runs the same connector as a worker. See the Connectors overview.

1. Prepare credentials in tl;dv

tl;dv → Settings → API. Copy the API key. The connector sends it as the x-api-key header.

2. Configure (managed dashboard)

Settings → Connectors → Add Connector → tl;dv. Paste the API key, set the scope template (default org:<org>/source:tldv), and Start sync.

What gets written

One episode per meeting, episode_type = meeting, whose content is the meeting name followed by the transcript rendered as speaker-attributed turns.

Field	Value
`occurred_at`	The meeting's real `happenedAt` time, not ingest time
`actor`	The organizer's display name and email
`thread_id`	`tldv:meeting:<meeting_id>`
`entities`	One meeting entity, so you can scope by `{entity.meeting}`
`metadata`	`meeting_id`, `name`, and the tl;dv url

Visibility

Derived per meeting from tl;dv's own privacy signals — explicit private/visibility flags and invitee count — rather than a fixed level:

Signal	Visibility
Marked private, or a 1:1	`private`, with invitees as the allow-list
Limited invitee set	`restricted`, with invitees as the allow-list
Otherwise	`organization`

For hard per-meeting isolation, use a scope template containing {entity.meeting}.

Idempotency and history

tldv:<meeting_id>:<content-digest>

The key is content-versioned, which matters more here than for most sources: a meeting is often listed before its transcript is ready. When the transcript later arrives — or the meeting is re-transcribed or renamed — the content changes, so a new key is minted and the corrected version lands as retained history. A key based on the meeting id alone would reject it and error on every subsequent sync.

Real-time delivery (webhook)

tl;dv does not sign its payloads, so the receiver authenticates on a static header:

export TLDV_WEBHOOK_SECRET=<a long random string>
cortexdb-sync serve --port 8081

Point tl;dv's MeetingReady / TranscriptReady webhooks at POST https://<your-host>/webhooks/tldv/events with Authorization: Bearer <the same secret>. The webhook path builds its episode through the same builder as polling, so a meeting seen by both paths dedupes to one stored copy.

Run it yourself

pip install cortexdb-connectors
pip install cortexdb-cli && cortexdb init

export TLDV_API_KEY=...        # required

cortexdb-sync --api-url http://localhost:3141 sync tldv
cortexdb-sync --api-url http://localhost:3141 watch tldv --interval 300

Cursor state persists in ~/.cortexdb/sync_state.json.

Behaviour worth knowing

Late transcripts are handled — the connector re-lists a 24-hour window behind its stored cursor, so a meeting whose transcript becomes ready after a newer meeting advanced the cursor is still picked up.
Rate limits and outages are retried with backoff on 429/5xx, honouring Retry-After.
A failed transcript fetch is logged loudly rather than silently ingesting an empty body.
Deletions are not propagated — a meeting deleted in tl;dv remains in CortexDB as retained history (the append-only model).