polish-transcript

Polish transcript

The transcript the user has was produced by machine listening: names misspelled, terms misheard, punctuation scattered, a long stretch of speech strung together with commas all the way to the end. What they want is a draft they can safely build on: subtitles that break lines by it, a translation that splits sentences by it, a document exported from it. Polishing is a proofread read straight through from start to finish: fix what was misheard, correct the punctuation, and keep what the speaker actually said exactly as they said it.

There are two ways this most easily goes wrong. One is over-editing: casually turning spoken language into written language, deleting filler words, condensing wordy sentences, even translating embedded foreign-language phrases. The text looks better, but the subtitles no longer match the audio, and what the audience hears is not what they see. The other is moving the text of one word onto a different word, or adding or deleting words: every word carries a timestamp, and once words are misaligned, the timing of the whole subtitle segment is wrong.

1. When to do it

Before translating and building the subtitle layer. Sentences are cut by punctuation, so changing punctuation changes sentence breaks; once the sentence breaks change, the sentence fingerprints recorded by the translation no longer match. So polish first, write back, then run documents_read again to get the new sentences for translation.
When this video already has a translation, most sentences will need retranslating after polishing. Tell the user this first, then start.
Skip when the user says not to polish, or when this transcript has already been polished (edited by the user, or done in this session). When skipping polishing, still do the speaker real-name step in Section 7.

2. Only word-for-word edits are allowed

Use documents_read to read the transcript whose kind is speech (when there are several, match the one to the source material the user mentioned). The body's words are a sequence of words, each with an id, start and end time, speaker, and text; punctuation is attached to the words' text: sentence-final punctuation at the end of the last word of a sentence, opening quotes and opening brackets at the start of the first word.

When writing back, change only the words' text:

Keep each word's id, time, and speaker as is; the number and order of words stay unchanged; write back all other fields in the body exactly as read.
Allowed: replace a word's text with the correct spelling (typos, homophone or near-homophone mishearings, spelling, capitalization, proper names); add, change, or delete punctuation before or after a word's text; restore spaces within an obviously run-together foreign-language phrase in a word's text by word (still within that word's text, not translated).
Not allowed: merge or split words, add or delete words, reorder words, move text onto a different word, or change a word's text to an empty string.
When one error spans several words, if the correct spelling can be distributed across those words with each word still having text, distribute it (for example, in a character-by-character transcript, change 「深」「度」「雪」「洗」 to 「深」「度」「学」「习」; in a word-segmented transcript, change Chat GBT to Chat GPT). If it cannot be distributed (a word would have to be deleted or an extra word added to match), do not force the edit; list this spot and the correct spelling in the delivery notes.

Why so strict: every subtitle line and every translated sentence aligns to these words' timings. You are changing characters; the timeline must not move.

3. Before starting

Read through the whole text first and settle these points; revise the whole text according to them. They do not go into the final product:

Background reference: first use videos_inspect to look at the source material's assets[].source(only for material imported from a link): title, publisher (uploader), description (description), and the author's chapters. It is background reference, not manuscript content, and not absolutely authoritative: the accurate spellings of names of people, organizations, products, and terms in it are strong correction hints, and you should follow them only when the speaker is clearly referring to them; never add words or facts to the manuscript just because they appear in the description. Spellings explicitly specified by the user are still hard requirements and take precedence over it.
Content summary: explain in one or two sentences what this video is about. What a misheard word originally was can mostly be judged from it: in a video about machine learning, "深度雪洗" can only be "深度学习".
Terms and proper names: identify several incorrect spellings of the same term, person name, or product name, and unify them throughout the text into one correct spelling. First use speech_glossary_candidates to list suspected misheard spellings against the glossary enabled for the video (entries withmode as semantic must be checked one by one against the context); its discovered lists proper names with inconsistent spellings, which can serve as clues; it is only a candidate list, not exhaustive and not necessarily correct. Spellings explicitly specified by the user are hard requirements and must be followed verbatim: do not distort them, do not change spelling or capitalization, and do not add or remove spaces. When the context cannot determine it, do not guess; keep it as is.
Source language: take the language of the transcription document. The polished text must still be in this language; never translate it. Words from other languages mixed in by the speaker are kept as is, and words in the source language are not replaced with another language.

4. Three things done by default

Typos and misheard words: obvious recognition errors, spelling, homophone or near-homophone mishearings, and incorrectly split word boundaries. Change only with contextual evidence; disfluent or nonstandard colloquial expressions are not recognition errors by themselves, and pronouns, tense, and colloquial grammar are kept as is.
Terms and proper names: unify according to Section 3.
Punctuation and sentence segmentation: correct punctuation according to meaning; each time a complete meaning is finished, close it with the sentence-final punctuation of this writing system.
- Do not break the sentence after a dangling conjunction, preposition, or unfinished introductory phrase (for example, because.、of.、当。、和。): attach it to the following clause and break only after the meaning is complete.
- Pauses are only a reference: people often breathe in the middle of a sentence; segment by meaning, not because of a pause.
- Do not keep connecting a long passage with commas all the way through: a long passage without sentence-final punctuation will be hard-split into very long sentences, making both subtitles and translations hard to read.
- Do not leave conflicting adjacent punctuation (for example, 。，、，。、,,、.,); keep only one that expresses the boundary.
- Punctuation and spacing follow the conventions of this writing system: Chinese and Japanese use full-width punctuation with no spaces between characters; alphabetic scripts such as Latin and Cyrillic use half-width punctuation attached to the preceding word; other scripts follow their common writing conventions, and when unsure, retain the punctuation style already present in the transcription rather than applying another script's punctuation.

Compare the segmentation (just for illustration):

Bad:我们当时试了三种方案，第一种是直接上大模型，成本太高，第二种是蒸馏，效果掉得厉害，最后用的是第三种，就是混合的，

Good:我们当时试了三种方案。第一种是直接上大模型，成本太高。第二种是蒸馏，效果掉得厉害。最后用的是第三种，就是混合的。

Not a single word was changed, only the punctuation; but the former will be split into a subtitle that cannot fit, while each sentence in the latter can stand alone as one subtitle and be translated separately.

5. Things not done by default

Fix grammar(subject-verb agreement, articles, tense, etc.): do only when the user asks, fix only clear errors, do not change meaning or tone; do not fix cases that require adding or removing words to make them work, list those in the delivery notes.
Remove verbal tics, tighten wordiness: this requires deleting words, which cannot be done in the transcript. If the user wants no verbal tics or long pauses in the video, that is editing: follow cut spoken-word (talking-head-cut), or use edits_apply's proposeCuts to propose cuts, cutting the timeline without changing the transcript.
Rewriting, summarizing, reordering, adding content, translating: do none of these.

When the user asks for any of these, first explain how it will affect the subtitles and translation, then do the part that can be done.

6. Write back

Collect the changed words as [{id,text}] and write them back to the same transcript (documentId) with edits_apply's updateWords, committing in a single transaction. Upload only the changed words, not the full words array or the complete body. Use the video revision from videos_inspect for expectedRevision; reuse the commandId on retries of the same transaction.
A version conflict means the user just made changes: re-read and redo on the new body; do not overwrite the user's changes with the old body.
After writing, run documents_read once more and check the sentences split out in translationBasis: no whole paragraph merged into one sentence, and nothing broken mid-sentence; if wrong, fix the punctuation again.

7. Speaker real names

When the transcript distinguishes speakers, the body's speakers[] gives each speaker an id and name. Automatic diarization only assigns placeholder names; after the polish is written back, the last thing is to replace placeholder names with real names. Names appear in every subtitle and every exported file, so this step relies only on evidence, never guessing.

Placeholder names: "Speaker n" auto-generated by the transcription flow and its equivalents in other interface languages (Speaker 1、Sprecher 1、Parlante 1 "Speaker + number" forms like these), numbered labels from the recognition service (SPEAKER_00、S1、spk-1), and names that are empty or equal to the id (regardless of case). Any other name was set by the user or someone else; leave it alone.
When to do it: required when there is more than one speaker and placeholder names remain; skip when there is only one speaker or no placeholder names remain. When skipping polish as described in section 1, still do this step: it only changes names, not the body. When evidence can identify them, do not deliver a multi-person video with placeholder names.
Where evidence comes from: about the first 400 words of the transcript; about 60 words before and 120 words after each speaker's first utterance; the source material's title, publisher, and description (section 3); name cards or captions in video frames: first use frames already fetched in this task; when metadata names participants but the transcript does not match them to voices, use videos_frames to fetch frames from the first one or two minutes and at each speaker's first utterance to look for name cards. A name card must clearly indicate that this person is speaking; a name that merely appears on screen does not count.
What counts as evidence: self-introduction ("I'm...", "my name is ..."); introduction by another party ("today we have...", "welcome, ..."); this speaker's response immediately after being named; a signature-style sign-off; source metadata uniquely identifying one of them. When metadata lists several guests but cannot tell which voice is whose, evidence in the transcript is also needed. Participant lists, speaking order, speaker numbers, and the topic itself do not count as evidence; conversely, when the title or description names participants, this step is even more necessary: find evidence for each person and match names to voices.
How to write the name: Use the form actually used in the material, usually the full name; if there is no full name, use the form that appears (for example, only the given name); keep the original text and spelling, do not translate or transliterate; do not add titles, honorifics, organizations, parentheses, quotation marks, or explanations; no more than 40 characters. If the material has no name but explicitly states a role (host of a certain program, interviewer, narrator), a short role label may be used; do not invent a role based only on the way the dialogue looks.
Do not guess: If unsure, keep the placeholder name. A wrong guess is worse than leaving it: the wrong name will appear in every subtitle and every exported file.
One person with several ids: Automatic separation may split the same person into several ids. When each id has evidence, give them the same name; do not merge ids.
Write back: Use renameSpeakers in edits_apply, giving the documentId of the same transcript and speakers as [{id,name}]; write several at once, and do not upload words or the body text. Use the currently verified video revision as expectedRevision. On a revision conflict, re-read according to section 6.

8. What to avoid

Do not change colloquial speech into written language, do not delete verbal tics, do not condense, and do not translate mixed foreign languages.
Do not merge, split, add, delete, or reorder any words, and do not move text onto other words.
Do not add anything to the transcript just because a name or expression appears in the description.
Do not break sentences after dangling conjunctions or prepositions, and do not let a long passage run on with commas to the end.
Do not guess the speaker's name; do not add titles or parentheses to names.
Do not overwrite a version the user has just edited with the old body text.

9. Delivery

Explanation: how many places were changed; which terms and proper names were unified; which clauses were added.
List the places that could not be changed because of the one-word-to-one-word constraint (original text, what it should be) and the places left unchanged because of uncertainty.
Speakers: who was given a real name and on what evidence (one sentence); who has no evidence and is still a placeholder name.
When translating next, use documents_read again on the transcript after this write-back.

10. Self-check

The number of words, ids, timings, and speakers match what was read, and there are no words with empty text.
Nothing was translated, rewritten, reordered, or deleted; by default no grammar was changed and no verbal tics were deleted.
Terms and proper names are consistent throughout, and the spellings the user specified appear verbatim.
Every sentence ends with end-of-sentence punctuation, there are no dangling breaks, and there are no conflicting adjacent punctuation marks; punctuation and spaces follow the conventions of this language.
After write-back, it was read again, and the sentences cut by translationBasis are of appropriate length.
With multiple speakers, there are no placeholder names left for speakers who could have been identified; every name written has evidence, with no titles or parentheses; names chosen by the user were not changed.