Skip to content

Release Notes: v2.7.1 — Transcripts In, Without the Reformatting

A focused release for anyone arriving at Potato with speech already transcribed. Potato now reads 21 transcript and subtitle formats directly — up from 6 — loads them from sidecar files next to your media instead of requiring every transcript to be inlined into your data JSON, and ships a potato transcripts converter for turning a directory of ASR output into a ready-to-annotate data file. All four transcript-consuming schemas now accept the same formats.

Everything here is pure standard library. No new dependencies, and ASR and diarization still run upstream of Potato — it reads what your pipeline produced, it does not transcribe.

21 input formats

ASR output — Whisper JSON, WhisperX / diarized JSON, whisper.cpp JSON, Whisper TSV, AWS Transcribe, Deepgram, AssemblyAI, Rev.ai, SPoRC.

Subtitles and captions — SubRip (.srt), WebVTT (.vtt), SubStation Alpha (.ass, .ssa), TTML / DFXP, YouTube json3, YouTube srv1/srv2/srv3.

Forced alignment (import) — NIST CTM, Praat TextGrid, ELAN EAF. EAF and TextGrid export already shipped, so tiered annotations now round-trip: import an existing alignment, correct it in Potato, export back to your ELAN or Praat workflow.

Detection is driven by the shape of the data, not the file extension, so inline transcripts keep working exactly as before. Word-level timings and per-segment confidence are now preserved where the source provides them; formats that are natively word-level (CTM, Deepgram, AssemblyAI) group words into turns on speaker change plus a pause threshold.

Sidecar transcript files

A transcript no longer has to be pasted into your data file. Point at it:

{"id": "int_001", "conversation": {"audio": "media/int_001.mp3", "transcript": "media/int_001.srt"}}

Paths resolve relative to task_dir and are validated against directory traversal. A display option transcript_is_path: auto | true | false overrides the heuristic when inline text happens to look like a path.

potato transcripts — bulk converter

potato transcripts ./whisper_out --media-dir ./audio -o data/interviews.json
potato transcripts ./captions --media-url-prefix https://cdn.example.org/ -o data/talks.json --emit-config

Globs a directory of transcripts, pairs each to its media by basename (or builds a URL), derives item ids from filenames, and writes a Potato data file. --dry-run reports the detected format, turn count, and speakers found per file without writing anything — which is also the diagnostic to reach for when a transcript renders as one undifferentiated bubble.

One format vocabulary across four schemas

audio_dialogue, speech_transcript, voice_interaction, and tiered_annotation previously each parsed transcript data their own way and accepted different subsets of formats for no stated reason. They now share the normalizer through a server-side _transcripts index attached at render time, so whatever one accepts, all four accept. Existing configs are unaffected — each schema keeps its prior parsing as a fallback.

tiered_annotation additionally gains opt-in transcript seeding (transcript_field, transcript_tier): a tier is pre-populated from the transcript so annotators correct an existing alignment instead of re-segmenting from scratch. Seeded intervals are not auto-saved — they become annotations only when the annotator touches them, so an untouched seed is never misattributed as human work.

Documentation

  • Transcript & Subtitle Formats — the reference: every format with its detection rule and what it contributes, the normalized turn model, sidecar rules, all config keys, an explicit not supported list, and troubleshooting keyed to real symptoms.
  • Working with Transcripts — the task guide, with two entry paths that converge: "I ran Whisper on my audio" and "I have YouTube subtitles."
  • audio_annotation.md, video_annotation.md, audio_dialogue.md, and export_formats.md updated and cross-linked. audio_dialogue.md was linked from the docs index but missing from the mkdocs nav entirely — now fixed, along with the missing v2.7.0 nav entry.
  • New example: examples/audio/transcript-formats/, six formats side by side over sidecar paths.

Fixes

  • user_input() / user_input_leave() ReferenceError. The instance-jump input in the base templates wired onfocusin/onfocusout to two functions that are not defined anywhere in the codebase, throwing two console exceptions every time an annotator focused the box. Removed from all five affected templates. front_end.py matches that exact markup to implement allow_jumping_to_id: false, so both of its replacement strings were updated in lockstep.

Upgrade

pip install --upgrade potato-annotation==2.7.1

No configuration changes are required. Every previously accepted transcript shape is still accepted, byte-for-byte.