Skip to content

Add organization-level transcription vocabulary - #4422

Open
nick-rundoo wants to merge 1 commit into
CapSoftware:mainfrom
nick-rundoo:org-transcription-vocabulary
Open

nick-rundoo wants to merge 1 commit into
CapSoftware:mainfrom
nick-rundoo:org-transcription-vocabulary

Conversation

@nick-rundoo

@nick-rundoo nick-rundoo commented Nov 20, 2026 •

Copy link
Copy Markdown

Heads up: this PR was generated by Claude (Claude Code), not hand-written. We use Cap at our company and needed this, so we figured we'd offer it. Totally fine to close it if it doesn't fit your plans.

Problem

Company and product names get mangled in transcripts. For us, "Rundoo" comes out as "Rundu" and our assistant "Dooey" as "Dewey", on roughly 40% of our Caps. Only a Cap's owner can edit its captions, so an org can't fix this centrally.

Change

An org-level Transcription vocabulary setting (Organization Settings → Preferences → Playback and AI), passed to AssemblyAI as keyterms_prompt on org video transcriptions.

  • Stored in organizations.settings.transcriptionVocabulary (JSON column, no migration).
  • Used by the main transcribe workflow, the edit-transcript backfill, and live transcription. Developer API transcripts are unchanged.
  • sanitizeTranscriptionVocabulary trims, dedupes case-insensitively, and drops terms over 50 chars / 6 words. It caps the list at 100, which is within AssemblyAI's limits for both universal-3-5-pro (1,000) and the universal-2 fallback (200).
  • keyterms_prompt is only sent when the list is non-empty.
  • Saved through the same path as AI generation language, so it uses the same permission and Pro gating.

Testing

  • Unit tests added in transcribe-language.test.ts (options with and without vocabulary, sanitizer cases); the related vitest files pass.
  • Not run: the settings UI in a browser, or a live AssemblyAI call.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 4/5

Fix the unwanted autosaves and satisfy the comments rule before merging.

Findings

  1. P1 Settings save without edits ▶
  2. P2 Comment repeats the code ▶
Fix with agent prompt
### Issue 1
apps/web/app/(org)/dashboard/settings/organization/components/CapSettingsCard.tsx:114-116
**Settings save without edits.** `mergeSettings` now creates a fresh `transcriptionVocabulary` array every time. On mount, the reset effect replaces `lastSavedSettings.current`, but the autosave effect still holds the earlier debounced settings. Its per-key `!==` check treats the two identical lists as different and sends a save without any user edit. The save refreshes the settings, which repeats this mismatch and can keep sending writes and success notices. Compare vocabulary contents, and skip stale debounced values when resetting from server settings.

### Issue 2
packages/web-domain/src/Language.ts:127-133
**Comment repeats the code.** This new JSDoc lists the inputs and steps already shown by `sanitizeTranscriptionVocabulary`. The repository rule says to default to no comments and explicitly bans comments that narrate the code. Remove this block, or replace it with non-obvious context that the implementation cannot explain.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds an organization-wide vocabulary to help transcripts spell company names, product names, and jargon correctly.

  • Organization managers can save a vocabulary for transcription.
  • Organization vocabulary guides regular, backfill, and live video transcription.

The settings page needs an autosave fix before merging. One added comment also conflicts with the repository’s comments rule.

Reviews (1) · Last reviewed commit: "Add organization-level transcription voc..." · Reviewed by Greptile

Orgs can set a list of terms (company/product names, jargon) in
Organization Settings > Preferences. The list is stored in
organizations.settings.transcriptionVocabulary (JSON column, no migration)
and passed to AssemblyAI as keyterms_prompt on every org video
transcription: the main transcribe workflow, the edit-transcript backfill,
and live transcription. Developer API transcripts have no org and are
unchanged.

Terms are sanitized by sanitizeTranscriptionVocabulary (web-domain):
trimmed, empties dropped, deduped case-insensitively, max 50 chars and 6
words per term, max 100 terms. keyterms_prompt is only sent when the list
is non-empty. Saving follows the AI generation language path (org settings
manager permission, Pro gated).

AssemblyAI limits: keyterms_prompt takes up to 1,000 terms (6 words each)
on universal-3-5-pro and up to 200 terms on universal-2, per AssemblyAI's
models reference, so it is valid on both models in the speech_models
fallback and the 100-term cap fits either. It cannot be combined with
`prompt` on async requests; Cap sends no prompt. assemblyai SDK 4.36.4
types it as keyterms_prompt?: string[] (its docs still say Slam-1).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated
cap-status Skipped Skipped Nov 20, 2026 1:59am UTC

@vercel
vercel Bot temporarily deployed to Preview – cap-status November 20, 2026 01:59 Inactive
Comment on lines +114 to +116
transcriptionVocabulary: sanitizeTranscriptionVocabulary(
settings?.transcriptionVocabulary,
),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Settings save without edits. mergeSettings now creates a fresh transcriptionVocabulary array every time. On mount, the reset effect replaces lastSavedSettings.current, but the autosave effect still holds the earlier debounced settings. Its per-key !== check treats the two identical lists as different and sends a save without any user edit. The save refreshes the settings, which repeats this mismatch and can keep sending writes and success notices. Compare vocabulary contents, and skip stale debounced values when resetting from server settings.

Knowledge Base Used: Web product and collaborative workspace

Prompt To Fix With AI
This is a comment left during a code review.
Path: apps/web/app/(org)/dashboard/settings/organization/components/CapSettingsCard.tsx
Line: 114-116

Comment:
**Settings save without edits.** `mergeSettings` now creates a fresh `transcriptionVocabulary` array every time. On mount, the reset effect replaces `lastSavedSettings.current`, but the autosave effect still holds the earlier debounced settings. Its per-key `!==` check treats the two identical lists as different and sends a save without any user edit. The save refreshes the settings, which repeats this mismatch and can keep sending writes and success notices. Compare vocabulary contents, and skip stale debounced values when resetting from server settings.

**Knowledge Base Used:** [Web product and collaborative workspace](https://app.greptile.com/-/switch-tenant?tenant=cap&next=%2Fcustom-context%2Fknowledge-base%2Fcapsoftware%2Fcap%2F-%2Fdocs%2Fweb-product.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Comment on lines +127 to +133
/**
* Normalizes organization transcription vocabulary (company names, product
* names, jargon) into the list sent to AssemblyAI as `keyterms_prompt`.
* Accepts an array or a comma/newline separated string. Terms are trimmed,
* empty and over-long terms dropped, duplicates removed case-insensitively,
* and the list capped at TRANSCRIPTION_VOCABULARY_MAX_TERMS.
*/

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Comment repeats the code. This new JSDoc lists the inputs and steps already shown by sanitizeTranscriptionVocabulary. The repository rule says to default to no comments and explicitly bans comments that narrate the code. Remove this block, or replace it with non-obvious context that the implementation cannot explain.

Context Used: CLAUDE.md (source)

Prompt To Fix With AI
This is a comment left during a code review.
Path: packages/web-domain/src/Language.ts
Line: 127-133

Comment:
**Comment repeats the code.** This new JSDoc lists the inputs and steps already shown by `sanitizeTranscriptionVocabulary`. The repository rule says to default to no comments and explicitly bans comments that narrate the code. Remove this block, or replace it with non-obvious context that the implementation cannot explain.

**Context Used:** CLAUDE.md ([source](https://github.com/capsoftware/cap/blob/main/CLAUDE.md))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

This branch was previously deployed

1 inactive deployment
Preview – cap-status — 3a21ef49 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant