From fb0519c5610881ffef0550ae254217e2d9333d3c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 27 Apr 2026 19:58:55 -0500 Subject: [PATCH] Implemented a module to detect filler segments, and skip them for purposes of same-speaker segment coalescing --- README.md | 18 ++++-- internal/builtin/postprocess.go | 18 ++++++ internal/builtin/registry.go | 1 + internal/cli/merge_test.go | 87 +++++++++++++++++++++++++++ internal/coalesce/coalesce.go | 20 ++++--- internal/coalesce/coalesce_test.go | 35 +++++++++++ internal/config/config.go | 2 +- internal/filler/filler.go | 56 +++++++++++++++++ internal/filler/filler_test.go | 96 ++++++++++++++++++++++++++++++ 9 files changed, 319 insertions(+), 14 deletions(-) create mode 100644 internal/filler/filler.go create mode 100644 internal/filler/filler_test.go diff --git a/README.md b/README.md index aca79dc..fd9da0d 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ Optional flags: - `--input-reader`: input reader module. Default: `json-files`. - `--output-modules`: comma-separated output modules. Default: `json`. - `--preprocessing-modules`: comma-separated preprocessing modules. Default: `validate-raw,normalize-speakers,trim-text`. -- `--postprocessing-modules`: comma-separated postprocessing modules. Default: `detect-overlaps,resolve-overlaps,backchannel,coalesce,detect-overlaps,autocorrect,assign-ids,validate-output`. +- `--postprocessing-modules`: comma-separated postprocessing modules. Default: `detect-overlaps,resolve-overlaps,backchannel,filler,coalesce,detect-overlaps,autocorrect,assign-ids,validate-output`. - `--coalesce-gap`: maximum same-speaker gap in seconds for `coalesce`. Default: `3.0`. ## Input JSON Format @@ -151,7 +151,7 @@ The merged output uses the current seriatim envelope: "input_reader": "json-files", "input_files": ["eric.json", "mike.json"], "preprocessing_modules": ["validate-raw", "normalize-speakers", "trim-text"], - "postprocessing_modules": ["detect-overlaps", "resolve-overlaps", "backchannel", "coalesce", "detect-overlaps", "autocorrect", "assign-ids", "validate-output"], + "postprocessing_modules": ["detect-overlaps", "resolve-overlaps", "backchannel", "filler", "coalesce", "detect-overlaps", "autocorrect", "assign-ids", "validate-output"], "output_modules": ["json"] }, "segments": [ @@ -216,7 +216,7 @@ Overlap behavior: ## Overlap Resolution -The default postprocessing pipeline runs `detect-overlaps`, then `resolve-overlaps`, then `backchannel`, then `coalesce`, then a second `detect-overlaps` pass. +The default postprocessing pipeline runs `detect-overlaps`, then `resolve-overlaps`, then `backchannel`, then `filler`, then `coalesce`, then a second `detect-overlaps` pass. For each detected overlap group, `resolve-overlaps` uses preserved WhisperX word timing to build smaller word-run replacement segments: @@ -247,13 +247,23 @@ The default pipeline runs `backchannel` before `coalesce`. It tags short acknowl Backchannel matching is case-insensitive, trims surrounding whitespace, and requires a matching acknowledgement phrase, no more than three whitespace-delimited words, and duration no greater than `1.0` second. +## Fillers + +The default pipeline runs `filler` after `backchannel` and before `coalesce`. It tags short filler utterances with: + +```json +"categories": ["filler"] +``` + +Filler matching is case-insensitive, trims surrounding whitespace, and requires only filler tokens such as `um`, `uh`, `er`, `erm`, `ah`, `eh`, `hmm`, `mm`, or repeated combinations of those tokens. Matching segments must contain no more than three whitespace-delimited words and have duration no greater than `1.0` second. + ## Coalescing The default pipeline runs `coalesce` before the second overlap detection pass. It merges adjacent same-speaker segments in the transcript's current order when `next.start - current.end <= --coalesce-gap`. Coalesced segments use `source_ref` values such as `coalesce:1`, include `derived_from`, and omit `source_segment_index`. -Different-speaker backchannel segments do not block coalescing of surrounding same-speaker segments. When same-speaker segments are coalesced, any `backchannel` category from the merged inputs is dropped from the coalesced segment. +Different-speaker backchannel and filler segments do not block coalescing of surrounding same-speaker segments. When same-speaker segments are coalesced, any `backchannel` or `filler` category from the merged inputs is dropped from the coalesced segment. ## Autocorrect diff --git a/internal/builtin/postprocess.go b/internal/builtin/postprocess.go index 41913c5..1d76278 100644 --- a/internal/builtin/postprocess.go +++ b/internal/builtin/postprocess.go @@ -8,6 +8,7 @@ import ( "gitea.maximumdirect.net/eric/seriatim/internal/backchannel" "gitea.maximumdirect.net/eric/seriatim/internal/coalesce" "gitea.maximumdirect.net/eric/seriatim/internal/config" + "gitea.maximumdirect.net/eric/seriatim/internal/filler" "gitea.maximumdirect.net/eric/seriatim/internal/model" "gitea.maximumdirect.net/eric/seriatim/internal/overlap" "gitea.maximumdirect.net/eric/seriatim/internal/report" @@ -116,6 +117,23 @@ func (backchannelPostprocessor) Process(ctx context.Context, in model.MergedTran }, nil } +type fillerPostprocessor struct{} + +func (fillerPostprocessor) Name() string { + return "filler" +} + +func (fillerPostprocessor) Process(ctx context.Context, in model.MergedTranscript, cfg config.Config) (model.MergedTranscript, []report.Event, error) { + if err := ctx.Err(); err != nil { + return model.MergedTranscript{}, nil, err + } + + out, tagged := filler.Apply(in) + return out, []report.Event{ + report.Info("postprocessing", "filler", fmt.Sprintf("tagged %d filler segment(s)", tagged)), + }, nil +} + type coalescePostprocessor struct{} func (coalescePostprocessor) Name() string { diff --git a/internal/builtin/registry.go b/internal/builtin/registry.go index 7faf232..e58a642 100644 --- a/internal/builtin/registry.go +++ b/internal/builtin/registry.go @@ -14,6 +14,7 @@ func NewRegistry() *pipeline.Registry { registry.RegisterPostprocessor(detectOverlaps{}) registry.RegisterPostprocessor(resolveOverlaps{}) registry.RegisterPostprocessor(backchannelPostprocessor{}) + registry.RegisterPostprocessor(fillerPostprocessor{}) registry.RegisterPostprocessor(coalescePostprocessor{}) registry.RegisterPostprocessor(assignIDs{}) registry.RegisterPostprocessor(noopPostprocessor{name: "validate-output"}) diff --git a/internal/cli/merge_test.go b/internal/cli/merge_test.go index 132e997..9b4da8a 100644 --- a/internal/cli/merge_test.go +++ b/internal/cli/merge_test.go @@ -91,6 +91,7 @@ func TestMergeWritesMergedOutputAndReport(t *testing.T) { "detect-overlaps", "resolve-overlaps", "backchannel", + "filler", "coalesce", "detect-overlaps", "autocorrect", @@ -625,6 +626,45 @@ func TestMergeTagsBackchannelSegments(t *testing.T) { } } +func TestMergeTagsFillerSegments(t *testing.T) { + dir := t.TempDir() + input := writeJSONFile(t, dir, "input.json", `{ + "segments": [ + {"start": 1, "end": 1.5, "text": " Um uh "}, + {"start": 6, "end": 7, "text": "not filler"} + ] + }`) + output := filepath.Join(dir, "merged.json") + reportPath := filepath.Join(dir, "report.json") + + err := executeMerge( + "--input-file", input, + "--output-file", output, + "--report-file", reportPath, + ) + if err != nil { + t.Fatalf("merge failed: %v", err) + } + + var transcript model.FinalTranscript + readJSON(t, output, &transcript) + if len(transcript.Segments) != 2 { + t.Fatalf("segment count = %d, want 2", len(transcript.Segments)) + } + if !equalStrings(transcript.Segments[0].Categories, []string{"filler"}) { + t.Fatalf("segment categories = %v, want [filler]", transcript.Segments[0].Categories) + } + if len(transcript.Segments[1].Categories) != 0 { + t.Fatalf("unexpected categories = %v", transcript.Segments[1].Categories) + } + + var rpt report.Report + readJSON(t, reportPath, &rpt) + if !hasReportEvent(rpt, "postprocessing", "filler", "tagged 1 filler segment(s)") { + t.Fatal("expected filler report event") + } +} + func TestMergeCoalescesAroundDifferentSpeakerBackchannel(t *testing.T) { dir := t.TempDir() inputA := writeJSONFile(t, dir, "a.json", `{ @@ -672,6 +712,53 @@ func TestMergeCoalescesAroundDifferentSpeakerBackchannel(t *testing.T) { } } +func TestMergeCoalescesAroundDifferentSpeakerFiller(t *testing.T) { + dir := t.TempDir() + inputA := writeJSONFile(t, dir, "a.json", `{ + "segments": [ + {"start": 1, "end": 2, "text": "first"}, + {"start": 3, "end": 4, "text": "second"} + ] + }`) + inputB := writeJSONFile(t, dir, "b.json", `{ + "segments": [ + {"start": 2.2, "end": 2.5, "text": "um"} + ] + }`) + speakers := writeYAMLFile(t, dir, "speakers.yml", `match: + - speaker: Alice + match: ["a.json"] + - speaker: Bob + match: ["b.json"] +`) + output := filepath.Join(dir, "merged.json") + + err := executeMerge( + "--input-file", inputA, + "--input-file", inputB, + "--speakers", speakers, + "--output-file", output, + ) + if err != nil { + t.Fatalf("merge failed: %v", err) + } + + var transcript model.FinalTranscript + readJSON(t, output, &transcript) + if len(transcript.Segments) != 2 { + t.Fatalf("segment count = %d, want 2", len(transcript.Segments)) + } + if transcript.Segments[0].Speaker != "Alice" || transcript.Segments[0].Text != "first second" { + t.Fatalf("first segment = %#v, want coalesced Alice", transcript.Segments[0]) + } + if len(transcript.Segments[0].Categories) != 0 { + t.Fatalf("coalesced segment categories = %v, want none", transcript.Segments[0].Categories) + } + if transcript.Segments[1].Speaker != "Bob" || !equalStrings(transcript.Segments[1].Categories, []string{"filler"}) { + t.Fatalf("second segment = %#v, want Bob filler", transcript.Segments[1]) + } +} + func TestSpeakerMatchingUsesFirstMatchingRuleCaseInsensitive(t *testing.T) { dir := t.TempDir() input := writeJSONFile(t, dir, "2026-04-19-Adam_Rakestraw.json", `{ diff --git a/internal/coalesce/coalesce.go b/internal/coalesce/coalesce.go index 52c12f2..70ac074 100644 --- a/internal/coalesce/coalesce.go +++ b/internal/coalesce/coalesce.go @@ -27,24 +27,24 @@ func Apply(in model.MergedTranscript, gap float64) (model.MergedTranscript, Summ coalescedID := 0 current := newRun(in.Segments[0]) - pendingBackchannels := make([]model.Segment, 0) + pendingSkipped := make([]model.Segment, 0) for _, segment := range in.Segments[1:] { if current.canMerge(segment, gap) { current.add(segment) continue } - if segment.Speaker != current.speaker() && hasCategory(segment, "backchannel") { - pendingBackchannels = append(pendingBackchannels, segment) + if segment.Speaker != current.speaker() && hasAnyCategory(segment, "backchannel", "filler") { + pendingSkipped = append(pendingSkipped, segment) continue } coalescedID = appendRun(&out, current, coalescedID, &summary) - out.Segments = append(out.Segments, pendingBackchannels...) - pendingBackchannels = pendingBackchannels[:0] + out.Segments = append(out.Segments, pendingSkipped...) + pendingSkipped = pendingSkipped[:0] current = newRun(segment) } coalescedID = appendRun(&out, current, coalescedID, &summary) - out.Segments = append(out.Segments, pendingBackchannels...) + out.Segments = append(out.Segments, pendingSkipped...) return out, summary } @@ -129,10 +129,12 @@ func segmentRef(segment model.Segment) string { return segment.Source } -func hasCategory(segment model.Segment, category string) bool { +func hasAnyCategory(segment model.Segment, categories ...string) bool { for _, existing := range segment.Categories { - if existing == category { - return true + for _, category := range categories { + if existing == category { + return true + } } } return false diff --git a/internal/coalesce/coalesce_test.go b/internal/coalesce/coalesce_test.go index cff3ebf..e004813 100644 --- a/internal/coalesce/coalesce_test.go +++ b/internal/coalesce/coalesce_test.go @@ -151,6 +151,20 @@ func TestApplyDropsBackchannelCategoryFromMergedSameSpeakerRun(t *testing.T) { } } +func TestApplyDropsFillerCategoryFromMergedSameSpeakerRun(t *testing.T) { + first := segment("a.json", 0, "Alice", 1, 2, "um") + first.Categories = []string{"filler"} + second := segment("a.json", 1, "Alice", 2.5, 3, "more") + + got, _ := Apply(model.MergedTranscript{Segments: []model.Segment{first, second}}, 3) + if len(got.Segments) != 1 { + t.Fatalf("segment count = %d, want 1", len(got.Segments)) + } + if got.Segments[0].Categories != nil { + t.Fatalf("categories = %v, want nil", got.Segments[0].Categories) + } +} + func TestApplySkipsDifferentSpeakerBackchannelAsMergeBlocker(t *testing.T) { first := segment("a.json", 0, "Alice", 1, 2, "first") backchannel := segment("b.json", 0, "Bob", 2.2, 2.5, "yeah") @@ -172,6 +186,27 @@ func TestApplySkipsDifferentSpeakerBackchannelAsMergeBlocker(t *testing.T) { } } +func TestApplySkipsDifferentSpeakerFillerAsMergeBlocker(t *testing.T) { + first := segment("a.json", 0, "Alice", 1, 2, "first") + filler := segment("b.json", 0, "Bob", 2.2, 2.5, "um") + filler.Categories = []string{"filler"} + second := segment("a.json", 1, "Alice", 3, 4, "second") + + got, summary := Apply(model.MergedTranscript{Segments: []model.Segment{first, filler, second}}, 3) + if summary.OriginalSegmentsMerged != 2 || summary.CoalescedSegments != 1 { + t.Fatalf("summary = %#v", summary) + } + if len(got.Segments) != 2 { + t.Fatalf("segment count = %d, want 2", len(got.Segments)) + } + if got.Segments[0].Text != "first second" { + t.Fatalf("first output text = %q, want first second", got.Segments[0].Text) + } + if got.Segments[1].Text != "um" || !reflect.DeepEqual(got.Segments[1].Categories, []string{"filler"}) { + t.Fatalf("second output segment = %#v", got.Segments[1]) + } +} + func TestApplyDifferentSpeakerNonBackchannelStillBlocksMerge(t *testing.T) { first := segment("a.json", 0, "Alice", 1, 2, "first") bob := segment("b.json", 0, "Bob", 2.2, 2.5, "interruption") diff --git a/internal/config/config.go b/internal/config/config.go index 4ebc641..c1a8077 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -14,7 +14,7 @@ const ( DefaultInputReader = "json-files" DefaultOutputModules = "json" DefaultPreprocessingModules = "validate-raw,normalize-speakers,trim-text" - DefaultPostprocessingModules = "detect-overlaps,resolve-overlaps,backchannel,coalesce,detect-overlaps,autocorrect,assign-ids,validate-output" + DefaultPostprocessingModules = "detect-overlaps,resolve-overlaps,backchannel,filler,coalesce,detect-overlaps,autocorrect,assign-ids,validate-output" DefaultOverlapWordRunGap = 0.75 DefaultWordRunReorderWindow = 0.4 DefaultCoalesceGap = 3.0 diff --git a/internal/filler/filler.go b/internal/filler/filler.go new file mode 100644 index 0000000..3ad6e94 --- /dev/null +++ b/internal/filler/filler.go @@ -0,0 +1,56 @@ +package filler + +import ( + "regexp" + "strings" + + "gitea.maximumdirect.net/eric/seriatim/internal/model" +) + +const Category = "filler" + +var patterns = []*regexp.Regexp{ + regexp.MustCompile(`(?i)^(um+|uh+|er+|erm+|ah+|eh+|hmm+|mm+|mmm+)$`), + regexp.MustCompile(`(?i)^(um+|uh+|er+|erm+|ah+|eh+|hmm+|mm+|mmm+)(\s+(um+|uh+|er+|erm+|ah+|eh+|hmm+|mm+|mmm+))*$`), +} + +// Apply tags short filler segments. +func Apply(in model.MergedTranscript) (model.MergedTranscript, int) { + tagged := 0 + for index := range in.Segments { + if !matches(in.Segments[index]) || hasCategory(in.Segments[index], Category) { + continue + } + in.Segments[index].Categories = append(in.Segments[index].Categories, Category) + tagged++ + } + return in, tagged +} + +func matches(segment model.Segment) bool { + text := strings.TrimSpace(segment.Text) + if text == "" { + return false + } + if len(strings.Fields(text)) > 3 { + return false + } + if segment.End-segment.Start > 1.0 { + return false + } + for _, pattern := range patterns { + if pattern.MatchString(text) { + return true + } + } + return false +} + +func hasCategory(segment model.Segment, category string) bool { + for _, existing := range segment.Categories { + if existing == category { + return true + } + } + return false +} diff --git a/internal/filler/filler_test.go b/internal/filler/filler_test.go new file mode 100644 index 0000000..2a7a6b0 --- /dev/null +++ b/internal/filler/filler_test.go @@ -0,0 +1,96 @@ +package filler + +import ( + "reflect" + "testing" + + "gitea.maximumdirect.net/eric/seriatim/internal/model" +) + +func TestApplyTagsVerySafeFillers(t *testing.T) { + for _, text := range []string{"um", "uhhh", "ER", "ermm", "ah", "eh", "hmmm", "mm", "mmm"} { + t.Run(text, func(t *testing.T) { + got, tagged := Apply(transcript(segment(text, 1, 1.5))) + if tagged != 1 { + t.Fatalf("tagged = %d, want 1", tagged) + } + assertCategories(t, got.Segments[0], []string{Category}) + }) + } +} + +func TestApplyTagsRepeatedFillers(t *testing.T) { + got, tagged := Apply(transcript(segment("um uh hmm", 1, 1.8))) + if tagged != 1 { + t.Fatalf("tagged = %d, want 1", tagged) + } + assertCategories(t, got.Segments[0], []string{Category}) +} + +func TestApplyMatchesTrimAwareCaseInsensitive(t *testing.T) { + got, tagged := Apply(transcript(segment(" UM uh ", 1, 1.5))) + if tagged != 1 { + t.Fatalf("tagged = %d, want 1", tagged) + } + assertCategories(t, got.Segments[0], []string{Category}) +} + +func TestApplyDoesNotTagNonMatches(t *testing.T) { + for _, text := range []string{"um okay", "uh-huh", "hmm, okay"} { + t.Run(text, func(t *testing.T) { + got, tagged := Apply(transcript(segment(text, 1, 1.5))) + if tagged != 0 { + t.Fatalf("tagged = %d, want 0", tagged) + } + assertCategories(t, got.Segments[0], nil) + }) + } +} + +func TestApplyRejectsWordCountOverThree(t *testing.T) { + got, tagged := Apply(transcript(segment("um uh er ah", 1, 1.5))) + if tagged != 0 { + t.Fatalf("tagged = %d, want 0", tagged) + } + assertCategories(t, got.Segments[0], nil) +} + +func TestApplyRejectsDurationOverOneSecond(t *testing.T) { + got, tagged := Apply(transcript(segment("um", 1, 2.1))) + if tagged != 0 { + t.Fatalf("tagged = %d, want 0", tagged) + } + assertCategories(t, got.Segments[0], nil) +} + +func TestApplyPreservesExistingCategoriesAndAvoidsDuplicate(t *testing.T) { + existing := segment("um", 1, 1.2) + existing.Categories = []string{"manual", Category} + + got, tagged := Apply(transcript(existing)) + if tagged != 0 { + t.Fatalf("tagged = %d, want 0", tagged) + } + assertCategories(t, got.Segments[0], []string{"manual", Category}) +} + +func transcript(segments ...model.Segment) model.MergedTranscript { + return model.MergedTranscript{Segments: segments} +} + +func segment(text string, start float64, end float64) model.Segment { + return model.Segment{ + Source: "input.json", + Speaker: "Alice", + Start: start, + End: end, + Text: text, + } +} + +func assertCategories(t *testing.T, segment model.Segment, want []string) { + t.Helper() + if !reflect.DeepEqual(segment.Categories, want) { + t.Fatalf("categories = %v, want %v", segment.Categories, want) + } +}