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.

The key on the wire is derived

The key format above is this connector's internal record identity: it decides which source record an event belongs to. The idempotency_key actually sent to CortexDB is a derived cxsrc:<56 hex> value that also hashes the content, labels, observed time and actor, so an unchanged redelivery converges on the same event while any edit lands as a new one, even where the key format itself is not content-versioned. Every event also carries a source descriptor with the record's fingerprint. See Source identity and keys.

Real-time delivery (webhook)

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

pip install 'cortexdb-connectors[webhooks]'   # serve needs starlette + uvicorn
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).