From 1c6bca86a457f7985d5851722ce67e7448ae4687 Mon Sep 17 00:00:00 2001 From: Rue <343175018+thatsrue@users.noreply.github.com> Date: Fri, 30 Oct 2026 21:07:59 -0400 Subject: [PATCH 1/3] fix(combine): refuse VTTs a run did not finish --- AGENTS.md | 4 ++- tests/test_combine.py | 34 +++++++++++++++++++++-- tests/test_session_env.py | 8 ++++++ transcript_combobulator/combine.py | 12 +++++++- transcript_combobulator/pipeline_cache.py | 17 ++++++++++++ 5 files changed, 71 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 83f4d4a..80ffd77 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,7 +66,9 @@ The standard pipeline: `transcript_combobulator.batch.main` → - **Partial transcription is a failure.** Any failed chunk raises before the manifest is written, so the cache cannot hide a transcript with gaps. A track with no speech at all is an empty - transcript, not an error. + transcript, not an error. whisper still writes that track's VTT, so a + manual `combobulator combine` refuses any VTT its folder's manifest does + not record as finished. - **Usernames match as whole tokens** in per-speaker dir names, so `wulf` never claims `5-wulfgar`. Batch runs hand combine the exact VTTs they produced; stale sibling dirs are ignored. diff --git a/tests/test_combine.py b/tests/test_combine.py index 8fce6d1..242af68 100644 --- a/tests/test_combine.py +++ b/tests/test_combine.py @@ -14,6 +14,11 @@ should_skip_content, validate_speaker_mapping, ) +from transcript_combobulator.pipeline_cache import ( + FINAL_STAGE, + get_manifest_path, + record_stage, +) VTT_SAMPLE = """WEBVTT @@ -32,6 +37,14 @@ def _write_vtt(path: Path, content: str) -> None: path.write_text(content, encoding="utf-8") +def _write_finished_vtt(path: Path, content: str) -> None: + """A VTT plus the completion record a finished pipeline run leaves.""" + _write_vtt(path, content) + record_stage( + get_manifest_path(path.parent, path.parent.name), FINAL_STAGE, "done", [path] + ) + + class TestNormalizeForDedup: def test_strips_punctuation_and_lowercases(self): assert _normalize_for_dedup("Hello, World!") == "hello world" @@ -239,7 +252,7 @@ def test_quote_marks_in_speaker_fields_survive(tmp_path, monkeypatch): monkeypatch.setenv("CHUNKS", "1") for stem in ("1-regis", "4-catti_brie"): (tmp_path / "night" / stem).mkdir(parents=True) - _write_vtt( + _write_finished_vtt( tmp_path / "night" / stem / f"{stem}.vtt", "WEBVTT\n\n00:00:01.000 --> 00:00:02.000\nRoll for initiative.\n\n", ) @@ -261,7 +274,7 @@ def _session(self, tmp_path, monkeypatch): stale = session / "3-cadderly-v0" for d in (current, stale): d.mkdir(parents=True) - _write_vtt( + _write_finished_vtt( d / "3-cadderly.vtt", "WEBVTT\n\n00:00:01.000 --> 00:00:02.000\nRoll for initiative.\n\n", ) @@ -285,6 +298,23 @@ def test_glob_fallback_sees_both(self, tmp_path, monkeypatch): assert out[0].read_text().count("Roll for initiative.") >= 1 assert len(list(session.glob("**/*.vtt"))) == 2 + def test_glob_refuses_a_track_whose_run_did_not_finish(self, tmp_path, monkeypatch): + """whisper writes the VTT when some chunks fail; combine must not merge it.""" + from transcript_combobulator.combine import combine_transcripts_from_env + + session, _, _ = self._session(tmp_path, monkeypatch) + partial = session / "5-danica" + partial.mkdir() + _write_vtt( + partial / "5-danica.vtt", + "WEBVTT\n\n00:00:03.000 --> 00:00:04.000\nI check for traps.\n\n", + ) + _set_mapping(monkeypatch, ["cadderly", "danica"]) + + with pytest.raises(CombineError, match="5-danica.vtt"): + combine_transcripts_from_env(tmp_path, "night") + assert not (session / "night-combined.txt").exists() + def test_missing_explicit_file_is_loud(self, tmp_path, monkeypatch): from transcript_combobulator.combine import combine_transcripts_from_env diff --git a/tests/test_session_env.py b/tests/test_session_env.py index ccdd5e8..447cd29 100644 --- a/tests/test_session_env.py +++ b/tests/test_session_env.py @@ -18,6 +18,11 @@ validate_speaker_mapping, ) from transcript_combobulator.config import ROOT_DIR, read_env_file +from transcript_combobulator.pipeline_cache import ( + FINAL_STAGE, + get_manifest_path, + record_stage, +) from transcript_combobulator.session_env import ( SessionEnvError, SessionEnvResult, @@ -664,6 +669,9 @@ def write_vtt(path: Path, lines: list[tuple[str, str]]) -> None: f"{when} --> {when[:-1]}9\n{text}\n" for when, text in lines ) path.write_text(body) + record_stage( + get_manifest_path(path.parent, path.parent.name), FINAL_STAGE, "done", [path] + ) def test_labels_can_be_fixed_after_transcription_by_recombining( diff --git a/transcript_combobulator/combine.py b/transcript_combobulator/combine.py index c00cd35..80f1719 100644 --- a/transcript_combobulator/combine.py +++ b/transcript_combobulator/combine.py @@ -18,6 +18,7 @@ SKIP_FILTERS, ) from transcript_combobulator.logging_config import get_logger +from transcript_combobulator.pipeline_cache import is_vtt_recorded_complete logger = get_logger(__name__) @@ -324,7 +325,8 @@ def combine_transcripts_from_env( ``vtt_files`` restricts the combine to exactly those transcripts. Batch runs pass the VTTs they produced so a stale per-speaker directory from an earlier export cannot double a speaker's lines. Without it every VTT - under the session directory is used, in sorted order. + under the session directory is used, in sorted order, and each must be + recorded complete in its folder's pipeline manifest. """ search_dir = base_dir / session_subdir if session_subdir else base_dir output_dir = search_dir @@ -336,6 +338,14 @@ def combine_transcripts_from_env( raise CombineError(f"Transcript files not found: {missing}") else: vtt_files = sorted(search_dir.glob("**/*.vtt")) + # whisper writes the VTT even when some chunks failed; only a + # finished run records it, so anything else may have gaps. + incomplete = [str(p) for p in vtt_files if not is_vtt_recorded_complete(p)] + if incomplete: + raise CombineError( + f"Transcripts not recorded complete: {incomplete}. A run failed " + "or was interrupted on these tracks; rerun it to finish them." + ) if not vtt_files: raise CombineError(f"No VTT files found in {search_dir}") diff --git a/transcript_combobulator/pipeline_cache.py b/transcript_combobulator/pipeline_cache.py index ab35597..d51d6a7 100644 --- a/transcript_combobulator/pipeline_cache.py +++ b/transcript_combobulator/pipeline_cache.py @@ -159,6 +159,23 @@ def is_pipeline_complete(input_path: Path, manifest_path: Path) -> bool: ) +def is_vtt_recorded_complete(vtt_path: Path) -> bool: + """Whether a finished run recorded this VTT in its folder's manifest. + + Needs no input audio, so it cannot check the fingerprint against the + current config. It does catch a VTT left by a run that failed or was + interrupted: such a run drops or never writes the final record. + """ + manifest_path = get_manifest_path(vtt_path.parent, vtt_path.parent.name) + record = load_manifest(manifest_path).get(FINAL_STAGE) + if not isinstance(record, dict): + return False + artifacts = record.get("artifacts") + if not isinstance(artifacts, list) or str(vtt_path.resolve()) not in artifacts: + return False + return all(isinstance(path, str) and Path(path).is_file() for path in artifacts) + + def write_pipeline_manifest( input_path: Path, manifest_path: Path, From bd20148667861d3ed591ff3947727d4f34604d98 Mon Sep 17 00:00:00 2001 From: Rue <343175018+thatsrue@users.noreply.github.com> Date: Fri, 30 Oct 2026 22:34:22 -0400 Subject: [PATCH 2/3] fix(combine): combine sessions made before stage records Refuse a VTT only on the marks a failed or interrupted run leaves: a chunk checkpoint, or a current-version manifest without a vtt record naming it. A folder with no manifest, or one from an older cache version, is combined as before. --- AGENTS.md | 8 +++- tests/test_combine.py | 50 +++++++++++++++++++---- tests/test_session_env.py | 8 ---- transcript_combobulator/combine.py | 8 ++-- transcript_combobulator/pipeline_cache.py | 36 +++++++++++----- 5 files changed, 78 insertions(+), 32 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 80ffd77..5dd7ab1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,8 +67,12 @@ The standard pipeline: `transcript_combobulator.batch.main` → manifest is written, so the cache cannot hide a transcript with gaps. A track with no speech at all is an empty transcript, not an error. whisper still writes that track's VTT, so a - manual `combobulator combine` refuses any VTT its folder's manifest does - not record as finished. + manual `combobulator combine` refuses a VTT whose folder holds a chunk + checkpoint (`_progress.jsonl`), or a current-version manifest + without a `vtt` record naming it: the marks a failed or interrupted run + leaves. A folder with no manifest, or one from an older cache version, + predates these records (cache version 3), so its VTT is combined as + before, unchecked. - **Usernames match as whole tokens** in per-speaker dir names, so `wulf` never claims `5-wulfgar`. Batch runs hand combine the exact VTTs they produced; stale sibling dirs are ignored. diff --git a/tests/test_combine.py b/tests/test_combine.py index 242af68..602a7c0 100644 --- a/tests/test_combine.py +++ b/tests/test_combine.py @@ -1,6 +1,7 @@ #!/usr/bin/env python3 """Tests for the transcript combination step.""" +import json from pathlib import Path import pytest @@ -17,6 +18,7 @@ from transcript_combobulator.pipeline_cache import ( FINAL_STAGE, get_manifest_path, + get_progress_path, record_stage, ) @@ -298,23 +300,55 @@ def test_glob_fallback_sees_both(self, tmp_path, monkeypatch): assert out[0].read_text().count("Roll for initiative.") >= 1 assert len(list(session.glob("**/*.vtt"))) == 2 - def test_glob_refuses_a_track_whose_run_did_not_finish(self, tmp_path, monkeypatch): - """whisper writes the VTT when some chunks fail; combine must not merge it.""" - from transcript_combobulator.combine import combine_transcripts_from_env - - session, _, _ = self._session(tmp_path, monkeypatch) - partial = session / "5-danica" - partial.mkdir() + def _danica(self, session: Path, monkeypatch) -> Path: + track = session / "5-danica" + track.mkdir() _write_vtt( - partial / "5-danica.vtt", + track / "5-danica.vtt", "WEBVTT\n\n00:00:03.000 --> 00:00:04.000\nI check for traps.\n\n", ) _set_mapping(monkeypatch, ["cadderly", "danica"]) + return track + + @pytest.mark.parametrize("left_by", ["interrupted", "failed_chunks"]) + def test_glob_refuses_a_track_whose_run_did_not_finish( + self, tmp_path, monkeypatch, left_by + ): + """whisper writes the VTT when some chunks fail; combine must not merge it.""" + from transcript_combobulator.combine import combine_transcripts_from_env + + session, _, _ = self._session(tmp_path, monkeypatch) + track = self._danica(session, monkeypatch) + if left_by == "interrupted": + # The run got as far as conversion; it never recorded the VTT. + record_stage( + get_manifest_path(track, track.name), + "conversion", + "done", + [track / "5-danica.vtt"], + ) + else: + get_progress_path(track, track.name).write_text('{"key": "k"}\n') with pytest.raises(CombineError, match="5-danica.vtt"): combine_transcripts_from_env(tmp_path, "night") assert not (session / "night-combined.txt").exists() + @pytest.mark.parametrize("manifest", [None, {"cache_version": 2}]) + def test_glob_combines_a_track_from_before_stage_records( + self, tmp_path, monkeypatch, manifest + ): + """Sessions made before per-stage records have nothing to check.""" + from transcript_combobulator.combine import combine_transcripts_from_env + + session, _, _ = self._session(tmp_path, monkeypatch) + track = self._danica(session, monkeypatch) + if manifest is not None: + get_manifest_path(track, track.name).write_text(json.dumps(manifest)) + + out = combine_transcripts_from_env(tmp_path, "night") + assert "I check for traps." in out[0].read_text() + def test_missing_explicit_file_is_loud(self, tmp_path, monkeypatch): from transcript_combobulator.combine import combine_transcripts_from_env diff --git a/tests/test_session_env.py b/tests/test_session_env.py index 447cd29..ccdd5e8 100644 --- a/tests/test_session_env.py +++ b/tests/test_session_env.py @@ -18,11 +18,6 @@ validate_speaker_mapping, ) from transcript_combobulator.config import ROOT_DIR, read_env_file -from transcript_combobulator.pipeline_cache import ( - FINAL_STAGE, - get_manifest_path, - record_stage, -) from transcript_combobulator.session_env import ( SessionEnvError, SessionEnvResult, @@ -669,9 +664,6 @@ def write_vtt(path: Path, lines: list[tuple[str, str]]) -> None: f"{when} --> {when[:-1]}9\n{text}\n" for when, text in lines ) path.write_text(body) - record_stage( - get_manifest_path(path.parent, path.parent.name), FINAL_STAGE, "done", [path] - ) def test_labels_can_be_fixed_after_transcription_by_recombining( diff --git a/transcript_combobulator/combine.py b/transcript_combobulator/combine.py index 80f1719..381ea15 100644 --- a/transcript_combobulator/combine.py +++ b/transcript_combobulator/combine.py @@ -18,7 +18,7 @@ SKIP_FILTERS, ) from transcript_combobulator.logging_config import get_logger -from transcript_combobulator.pipeline_cache import is_vtt_recorded_complete +from transcript_combobulator.pipeline_cache import is_vtt_unfinished logger = get_logger(__name__) @@ -325,8 +325,8 @@ def combine_transcripts_from_env( ``vtt_files`` restricts the combine to exactly those transcripts. Batch runs pass the VTTs they produced so a stale per-speaker directory from an earlier export cannot double a speaker's lines. Without it every VTT - under the session directory is used, in sorted order, and each must be - recorded complete in its folder's pipeline manifest. + under the session directory is used, in sorted order, and none may be + left by a run that failed or was interrupted (``is_vtt_unfinished``). """ search_dir = base_dir / session_subdir if session_subdir else base_dir output_dir = search_dir @@ -340,7 +340,7 @@ def combine_transcripts_from_env( vtt_files = sorted(search_dir.glob("**/*.vtt")) # whisper writes the VTT even when some chunks failed; only a # finished run records it, so anything else may have gaps. - incomplete = [str(p) for p in vtt_files if not is_vtt_recorded_complete(p)] + incomplete = [str(p) for p in vtt_files if is_vtt_unfinished(p)] if incomplete: raise CombineError( f"Transcripts not recorded complete: {incomplete}. A run failed " diff --git a/transcript_combobulator/pipeline_cache.py b/transcript_combobulator/pipeline_cache.py index d51d6a7..b1aa7ca 100644 --- a/transcript_combobulator/pipeline_cache.py +++ b/transcript_combobulator/pipeline_cache.py @@ -159,21 +159,37 @@ def is_pipeline_complete(input_path: Path, manifest_path: Path) -> bool: ) -def is_vtt_recorded_complete(vtt_path: Path) -> bool: - """Whether a finished run recorded this VTT in its folder's manifest. - - Needs no input audio, so it cannot check the fingerprint against the - current config. It does catch a VTT left by a run that failed or was - interrupted: such a run drops or never writes the final record. +def is_vtt_unfinished(vtt_path: Path) -> bool: + """Whether this VTT was left by a run that failed or was interrupted. + + Such a run leaves its chunk checkpoint, or a current-version manifest + without a final record naming this VTT (non-forced runs drop that record + before any work). A folder with no manifest, or one from an older cache + version, predates these records and is not flagged. Needs no input + audio, so it cannot check the fingerprint against the current config. """ - manifest_path = get_manifest_path(vtt_path.parent, vtt_path.parent.name) + output_dir, stem = vtt_path.parent, vtt_path.parent.name + if get_progress_path(output_dir, stem).is_file(): + return True + manifest_path = get_manifest_path(output_dir, stem) + if not manifest_path.is_file(): + return False + try: + with open(manifest_path, encoding="utf-8") as f: + manifest = json.load(f) + except (OSError, ValueError): + return True + if not isinstance(manifest, dict): + return True + if manifest.get("cache_version") != PIPELINE_CACHE_VERSION: + return False record = load_manifest(manifest_path).get(FINAL_STAGE) if not isinstance(record, dict): - return False + return True artifacts = record.get("artifacts") if not isinstance(artifacts, list) or str(vtt_path.resolve()) not in artifacts: - return False - return all(isinstance(path, str) and Path(path).is_file() for path in artifacts) + return True + return not all(isinstance(p, str) and Path(p).is_file() for p in artifacts) def write_pipeline_manifest( From c5e2eb794651a5bbbf75f5c8242dd1dc2094b1ed Mon Sep 17 00:00:00 2001 From: Rue <343175018+thatsrue@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:08:40 -0500 Subject: [PATCH 3/3] fix(pipeline): a run recorded complete clears any chunk checkpoint A run that completes without chunk inference (a silent track after a VAD or audio change) left an interrupted run's _progress.jsonl, so combine refused its finished VTT and later runs hit the cache without clearing it. Remove the checkpoint once the completion record is written. --- AGENTS.md | 6 ++-- tests/test_batch.py | 53 +++++++++++++++++++++++++++++ transcript_combobulator/pipeline.py | 3 ++ 3 files changed, 59 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a1bede6..77eb21a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -138,9 +138,9 @@ Transcription checkpoints per chunk to `_progress.jsonl` (header line with the inference fingerprint, then one JSON line per completed chunk). A rerun with the same fingerprint reuses those chunks (`status: resumed`) and transcribes only the missing ones; a truncated last line is ignored and that -chunk redone. The file is removed when every chunk succeeded and kept when -any failed, so a rerun retries only the failed -chunks. Verified by killing a real 2.9 h track mid-transcription and +chunk redone. The file is removed when every chunk succeeded, and by any run +recorded complete, and kept when any failed, so a rerun retries only the +failed chunks. Verified by killing a real 2.9 h track mid-transcription and resuming: output identical to the uninterrupted run. ## Batch Run Behaviour diff --git a/tests/test_batch.py b/tests/test_batch.py index fab6ba4..83913b2 100644 --- a/tests/test_batch.py +++ b/tests/test_batch.py @@ -3,6 +3,7 @@ import json import subprocess +from pathlib import Path from unittest.mock import patch import numpy as np @@ -460,6 +461,58 @@ def test_quiet_16k_mono_wav_is_peak_normalised(self, tmp_path): assert sample_rate == 16000 assert 0.98 <= float(np.abs(data).max()) <= 1.0 + def test_a_finished_run_clears_a_checkpoint_it_did_not_use(self, tmp_path): + """A run that completes without chunk inference (a silent track after a + settings change) still clears an interrupted run's checkpoint, so a + manual combine accepts its VTT.""" + from transcript_combobulator.pipeline import process_file as main + from transcript_combobulator.pipeline_cache import is_vtt_unfinished + + input_file = tmp_path / "input" / "3-regis.wav" + input_file.parent.mkdir() + sf.write( + str(input_file), np.zeros(16000, dtype=np.float32), 16000, subtype="PCM_16" + ) + output_dir = tmp_path / "output" / "3-regis" + output_dir.mkdir(parents=True) + progress = output_dir / "3-regis_progress.jsonl" + progress.write_text('{"key": "an interrupted run"}\n', encoding="utf-8") + vtt = output_dir / "3-regis.vtt" + transcription = { + "vtt_file": str(vtt), + "json_file": str(output_dir / "3-regis_transcription.json"), + "mapping_file": str(output_dir / "3-regis_mapping.json"), + } + + def silent_track(*args, **kwargs): + for path in transcription.values(): + Path(path).write_text( + "WEBVTT\n" if path.endswith(".vtt") else "{}", encoding="utf-8" + ) + return transcription + + with ( + patch( + "transcript_combobulator.pipeline.get_output_path_for_input", + return_value=output_dir, + ), + patch( + "transcript_combobulator.pipeline.is_pipeline_complete", + return_value=False, + ), + patch( + "transcript_combobulator.pipeline.process_audio", + return_value=(output_dir, []), + ), + patch( + "transcript_combobulator.pipeline.transcribe_segments", + side_effect=silent_track, + ), + ): + main(str(input_file)) + + assert not is_vtt_unfinished(vtt) + def test_cache_miss_removes_existing_audio_before_conversion(self, tmp_path): """Conversion cannot silently reuse a valid but stale derived WAV.""" from transcript_combobulator.pipeline import process_file as main diff --git a/transcript_combobulator/pipeline.py b/transcript_combobulator/pipeline.py index f12bea9..39939a6 100644 --- a/transcript_combobulator/pipeline.py +++ b/transcript_combobulator/pipeline.py @@ -251,6 +251,9 @@ def _progress_callback(phase: str, current: int, total: int) -> None: ] with _timed_stage(file_metrics, "manifest_write"): write_pipeline_manifest(input_file, manifest_path, artifacts) + # A run recorded complete leaves no checkpoint, including one an + # interrupted run left that this run never read (a silent track). + progress_path.unlink(missing_ok=True) file_metrics["artifact_count"] = len(artifacts) file_metrics["status"] = "processed"