docs: update README with VAD, new threshold option, and silence handling

Update README to clarify VAD mode behavior: provisional caption only after Silero detects speech, Parakeet idle during silence. Document new --vad-threshold option to control Silero speech confidence. Add troubleshooting tip for music/noise false detections.

src/captions/processor.go

@@ -3,22 +3,30 @@ package captions
 
 import (
 	"strings"
+	"time"
 
 	"tea.chunkbyte.com/kato/captioneer/src/audio"
 	"tea.chunkbyte.com/kato/captioneer/src/config"
 )
 
+// Provisional recognition uses only a recent window. Re-decoding an entire
+// long utterance every refresh grows increasingly expensive, while the UI only
+// presents the latest provisional lines. The final event still decodes the
+// complete VAD segment.
+const maxPreviewDuration = 10 * time.Second
+
 type Processor struct {
 	settings    config.Settings
 	transcriber Transcriber
 	emit        func(Event) error
 
-	fixedSamples   []float32
-	previewSamples []float32
-	previewActive  bool
-	previewStart   int
-	nextPreviewAt  int
-	totalSamples   int
+	fixedSamples    []float32
+	previewSamples  []float32
+	previewActive   bool
+	previewStart    int
+	nextPreviewAt   int
+	previewReceived int
+	totalSamples    int
 }
 
 func New(settings config.Settings, transcriber Transcriber, emit func(Event) error) *Processor {
@@ -43,19 +51,26 @@ func (p *Processor) Accept(samples []float32) error {
 func (p *Processor) Flush() error {
 	if p.settings.Mode == config.ModeFixed {
 		if len(p.fixedSamples) > 0 {
-			return p.emitFinal(p.totalSamples, p.totalSamples+len(p.fixedSamples), p.fixedSamples)
+			return p.emitFixedFinal(p.totalSamples, p.totalSamples+len(p.fixedSamples), p.fixedSamples)
 		}
 		return nil
 	}
 	p.transcriber.FlushVAD()
-	return p.drainVAD()
+	if err := p.drainVAD(); err != nil {
+		return err
+	}
+	if p.previewActive {
+		p.resetPreview()
+		return p.emit(Event{Kind: Hide})
+	}
+	return nil
 }
 
 func (p *Processor) acceptFixed(samples []float32) error {
 	p.fixedSamples = append(p.fixedSamples, samples...)
 	chunkSize := audio.DurationSamples(p.settings.ChunkDuration)
 	for len(p.fixedSamples) >= chunkSize {
-		if err := p.emitFinal(p.totalSamples, p.totalSamples+chunkSize, p.fixedSamples[:chunkSize]); err != nil {
+		if err := p.emitFixedFinal(p.totalSamples, p.totalSamples+chunkSize, p.fixedSamples[:chunkSize]); err != nil {
 			return err
 		}
 		p.fixedSamples = p.fixedSamples[chunkSize:]
@@ -68,20 +83,33 @@ func (p *Processor) acceptVAD(samples []float32) error {
 	p.totalSamples += len(samples)
 	p.transcriber.AcceptVAD(samples)
 
-	if p.previewActive || audio.RMSDBFS(samples) >= p.settings.PreviewThresholdDB {
+	speechActive := p.transcriber.SpeechActive()
+	if speechActive && (p.previewActive || audio.RMSDBFS(samples) >= p.settings.PreviewThresholdDB) {
 		if !p.previewActive {
 			p.previewActive = true
 			p.previewStart = p.totalSamples - len(samples)
 		}
 		p.previewSamples = append(p.previewSamples, samples...)
-		if len(p.previewSamples) >= p.nextPreviewAt {
+		p.previewReceived += len(samples)
+		p.trimPreviewWindow()
+		if p.previewReceived >= p.nextPreviewAt {
 			if err := p.emitProvisional(); err != nil {
 				return err
 			}
 			p.nextPreviewAt += audio.DurationSamples(p.settings.ChunkDuration)
 		}
 	}
-	return p.drainVAD()
+	if err := p.drainVAD(); err != nil {
+		return err
+	}
+	// A short VAD false-positive can become active without meeting the minimum
+	// speech duration, so no final segment is produced. Clear its provisional
+	// text instead of leaving a stale caption on screen.
+	if !speechActive && p.previewActive {
+		p.resetPreview()
+		return p.emit(Event{Kind: Hide})
+	}
+	return nil
 }
 
 func (p *Processor) drainVAD() error {
@@ -93,13 +121,28 @@ func (p *Processor) drainVAD() error {
 		if err := p.emitFinal(start, start+len(samples), samples); err != nil {
 			return err
 		}
-		p.previewSamples = nil
-		p.previewActive = false
-		p.previewStart = 0
-		p.nextPreviewAt = audio.DurationSamples(p.settings.ChunkDuration)
+		p.resetPreview()
 	}
 }
 
+func (p *Processor) trimPreviewWindow() {
+	maxSamples := audio.DurationSamples(maxPreviewDuration)
+	if len(p.previewSamples) <= maxSamples {
+		return
+	}
+	dropped := len(p.previewSamples) - maxSamples
+	p.previewSamples = p.previewSamples[dropped:]
+	p.previewStart += dropped
+}
+
+func (p *Processor) resetPreview() {
+	p.previewSamples = nil
+	p.previewActive = false
+	p.previewStart = 0
+	p.previewReceived = 0
+	p.nextPreviewAt = audio.DurationSamples(p.settings.ChunkDuration)
+}
+
 func (p *Processor) emitProvisional() error {
 	text := strings.TrimSpace(p.transcriber.Decode(p.previewSamples))
 	if text == "" {
@@ -125,3 +168,10 @@ func (p *Processor) emitFinal(start, end int, samples []float32) error {
 		EndedAt:   audio.SamplesDuration(end),
 	})
 }
+
+func (p *Processor) emitFixedFinal(start, end int, samples []float32) error {
+	if audio.RMSDBFS(samples) < p.settings.PreviewThresholdDB {
+		return p.emit(Event{Kind: Hide})
+	}
+	return p.emitFinal(start, end, samples)
+}