feat(go bindings): add state abstraction

Author: ciricc

bindings/go/pkg/whisper/consts.go

@@ -16,6 +16,7 @@ var (
 	ErrProcessingFailed     = errors.New("processing failed")
 	ErrUnsupportedLanguage  = errors.New("unsupported language")
 	ErrModelNotMultilingual = errors.New("model is not multilingual")
+	ErrUnableToCreateState  = errors.New("unable to create state")
 )
 
 ///////////////////////////////////////////////////////////////////////////////

bindings/go/pkg/whisper/context.go

@@ -20,9 +20,6 @@ type context struct {
 	params whisper.Params
 }
 
-// Make sure context adheres to the interface
-var _ Context = (*context)(nil)
-
 ///////////////////////////////////////////////////////////////////////////////
 // LIFECYCLE
 
@@ -241,26 +238,49 @@ func (context *context) Process(
 	return nil
 }
 
-// Return the next segment of tokens
+// NextSegment returns the next segment from the context buffer
 func (context *context) NextSegment() (Segment, error) {
 	if context.model.ctx == nil {
 		return Segment{}, ErrInternalAppError
 	}
 	if context.n >= context.model.ctx.Whisper_full_n_segments() {
 		return Segment{}, io.EOF
 	}
-
-	// Populate result
 	result := toSegment(context.model.ctx, context.n)
-
-	// Increment the cursor
 	context.n++
-
-	// Return success
 	return result, nil
 }
 
-// Test for text tokens
+///////////////////////////////////////////////////////////////////////////////
+// PRIVATE METHODS
+
+func toSegment(ctx *whisper.Context, n int) Segment {
+	return Segment{
+		Num:    n,
+		Text:   strings.TrimSpace(ctx.Whisper_full_get_segment_text(n)),
+		Start:  time.Duration(ctx.Whisper_full_get_segment_t0(n)) * time.Millisecond * 10,
+		End:    time.Duration(ctx.Whisper_full_get_segment_t1(n)) * time.Millisecond * 10,
+		Tokens: toTokens(ctx, n),
+	}
+}
+
+func toTokens(ctx *whisper.Context, n int) []Token {
+	result := make([]Token, ctx.Whisper_full_n_tokens(n))
+	for i := 0; i < len(result); i++ {
+		data := ctx.Whisper_full_get_token_data(n, i)
+
+		result[i] = Token{
+			Id:    int(ctx.Whisper_full_get_token_id(n, i)),
+			Text:  ctx.Whisper_full_get_token_text(n, i),
+			P:     ctx.Whisper_full_get_token_p(n, i),
+			Start: time.Duration(data.T0()) * time.Millisecond * 10,
+			End:   time.Duration(data.T1()) * time.Millisecond * 10,
+		}
+	}
+	return result
+}
+
+// Token helpers
 func (context *context) IsText(t Token) bool {
 	switch {
 	case context.IsBEG(t):
@@ -280,70 +300,34 @@ func (context *context) IsText(t Token) bool {
 	}
 }
 
-// Test for "begin" token
 func (context *context) IsBEG(t Token) bool {
 	return whisper.Token(t.Id) == context.model.ctx.Whisper_token_beg()
 }
 
-// Test for "start of transcription" token
 func (context *context) IsSOT(t Token) bool {
 	return whisper.Token(t.Id) == context.model.ctx.Whisper_token_sot()
 }
 
-// Test for "end of transcription" token
 func (context *context) IsEOT(t Token) bool {
 	return whisper.Token(t.Id) == context.model.ctx.Whisper_token_eot()
 }
 
-// Test for "start of prev" token
 func (context *context) IsPREV(t Token) bool {
 	return whisper.Token(t.Id) == context.model.ctx.Whisper_token_prev()
 }
 
-// Test for "start of lm" token
 func (context *context) IsSOLM(t Token) bool {
 	return whisper.Token(t.Id) == context.model.ctx.Whisper_token_solm()
 }
 
-// Test for "No timestamps" token
 func (context *context) IsNOT(t Token) bool {
 	return whisper.Token(t.Id) == context.model.ctx.Whisper_token_not()
 }
 
-// Test for token associated with a specific language
 func (context *context) IsLANG(t Token, lang string) bool {
 	if id := context.model.ctx.Whisper_lang_id(lang); id >= 0 {
 		return whisper.Token(t.Id) == context.model.ctx.Whisper_token_lang(id)
 	} else {
 		return false
 	}
 }
-
-///////////////////////////////////////////////////////////////////////////////
-// PRIVATE METHODS
-
-func toSegment(ctx *whisper.Context, n int) Segment {
-	return Segment{
-		Num:    n,
-		Text:   strings.TrimSpace(ctx.Whisper_full_get_segment_text(n)),
-		Start:  time.Duration(ctx.Whisper_full_get_segment_t0(n)) * time.Millisecond * 10,
-		End:    time.Duration(ctx.Whisper_full_get_segment_t1(n)) * time.Millisecond * 10,
-		Tokens: toTokens(ctx, n),
-	}
-}
-
-func toTokens(ctx *whisper.Context, n int) []Token {
-	result := make([]Token, ctx.Whisper_full_n_tokens(n))
-	for i := 0; i < len(result); i++ {
-		data := ctx.Whisper_full_get_token_data(n, i)
-
-		result[i] = Token{
-			Id:    int(ctx.Whisper_full_get_token_id(n, i)),
-			Text:  ctx.Whisper_full_get_token_text(n, i),
-			P:     ctx.Whisper_full_get_token_p(n, i),
-			Start: time.Duration(data.T0()) * time.Millisecond * 10,
-			End:   time.Duration(data.T1()) * time.Millisecond * 10,
-		}
-	}
-	return result
-}

bindings/go/pkg/whisper/interface.go

@@ -85,6 +85,15 @@ type Context interface {
 	SystemInfo() string
 }
 
+// State is a per-request speech recognition state which shares the loaded model
+// but isolates recognition results. It embeds Context, so any state-specific
+// methods can be added later without breaking existing API.
+type State interface {
+	io.Closer
+
+	Context
+}
+
 // Segment is the text result of a speech recognition.
 type Segment struct {
 	// Segment Number

bindings/go/pkg/whisper/model.go

@@ -99,3 +99,19 @@ func (model *model) NewContext() (Context, error) {
 	// Return new context
 	return newContext(model, params)
 }
+
+// NewState returns a new per-request state sharing the loaded model
+func (model *model) NewState() (State, error) {
+	if model.ctx == nil {
+		return nil, ErrInternalAppError
+	}
+	params := model.ctx.Whisper_full_default_params(whisper.SAMPLING_GREEDY)
+	params.SetTranslate(false)
+	params.SetPrintSpecial(false)
+	params.SetPrintProgress(false)
+	params.SetPrintRealtime(false)
+	params.SetPrintTimestamps(false)
+	params.SetThreads(runtime.NumCPU())
+	params.SetNoContext(true)
+	return newState(model, params)
+}

bindings/go/pkg/whisper/state.go

@@ -0,0 +1,125 @@
+package whisper
+
+import (
+	"io"
+	"strings"
+	"time"
+
+	// Bindings
+	whisper "github.com/ggerganov/whisper.cpp/bindings/go"
+)
+
+// state embeds context behavior and carries a low-level state pointer
+// for isolated processing results.
+type state struct {
+	*context
+	st *whisper.State
+}
+
+// NewState creates a new per-request State from a Model without changing the Model interface.
+func NewState(m Model) (State, error) {
+	impl, ok := m.(*model)
+	if !ok {
+		return nil, ErrInternalAppError
+	}
+	params := impl.ctx.Whisper_full_default_params(whisper.SAMPLING_GREEDY)
+	params.SetTranslate(false)
+	params.SetPrintSpecial(false)
+	params.SetPrintProgress(false)
+	params.SetPrintRealtime(false)
+	params.SetPrintTimestamps(false)
+	return newState(impl, params)
+}
+
+// internal constructor used by model.NewState
+func newState(model *model, params whisper.Params) (State, error) {
+	ctx := &context{model: model, params: params}
+	st := model.ctx.Whisper_init_state()
+	if st == nil {
+		return nil, ErrUnableToCreateState
+	}
+	return &state{context: ctx, st: st}, nil
+}
+
+// Process using an isolated state for concurrency
+func (s *state) Process(
+	data []float32,
+	callEncoderBegin EncoderBeginCallback,
+	callNewSegment SegmentCallback,
+	callProgress ProgressCallback,
+) error {
+	if s.model.ctx == nil || s.st == nil {
+		return ErrInternalAppError
+	}
+	if callNewSegment != nil {
+		s.params.SetSingleSegment(true)
+	}
+	if err := s.model.ctx.Whisper_full_with_state(s.st, s.params, data, callEncoderBegin,
+		func(new int) {
+			if callNewSegment != nil {
+				num_segments := s.model.ctx.Whisper_full_n_segments_from_state(s.st)
+				s0 := num_segments - new
+				for i := s0; i < num_segments; i++ {
+					callNewSegment(toSegmentFromState(s.model.ctx, s.st, i))
+				}
+			}
+		}, func(progress int) {
+			if callProgress != nil {
+				callProgress(progress)
+			}
+		}); err != nil {
+		return err
+	}
+	return nil
+}
+
+// Return the next segment of tokens for state
+func (s *state) NextSegment() (Segment, error) {
+	if s.model.ctx == nil {
+		return Segment{}, ErrInternalAppError
+	}
+	if s.n >= s.model.ctx.Whisper_full_n_segments_from_state(s.st) {
+		return Segment{}, io.EOF
+	}
+	result := toSegmentFromState(s.model.ctx, s.st, s.n)
+	s.n++
+	return result, nil
+}
+
+func (s *state) Close() error {
+	if s.st != nil {
+		s.st.Whisper_free_state()
+		s.st = nil
+	}
+	return nil
+}
+
+// Helpers specific to state-based results
+func toSegmentFromState(ctx *whisper.Context, st *whisper.State, n int) Segment {
+	return Segment{
+		Num:    n,
+		Text:   stringsTrim(ctx.Whisper_full_get_segment_text_from_state(st, n)),
+		Start:  duration10x(ctx.Whisper_full_get_segment_t0_from_state(st, n)),
+		End:    duration10x(ctx.Whisper_full_get_segment_t1_from_state(st, n)),
+		Tokens: toTokensFromState(ctx, st, n),
+	}
+}
+
+func toTokensFromState(ctx *whisper.Context, st *whisper.State, n int) []Token {
+	result := make([]Token, ctx.Whisper_full_n_tokens_from_state(st, n))
+	for i := 0; i < len(result); i++ {
+		data := ctx.Whisper_full_get_token_data_from_state(st, n, i)
+		result[i] = Token{
+			Id:    int(ctx.Whisper_full_get_token_id_from_state(st, n, i)),
+			Text:  ctx.Whisper_full_get_token_text_from_state(st, n, i),
+			P:     ctx.Whisper_full_get_token_p_from_state(st, n, i),
+			Start: duration10x(data.T0()),
+			End:   duration10x(data.T1()),
+		}
+	}
+	return result
+}
+
+// small shared helpers to avoid importing time/strings here unnecessarily
+func stringsTrim(s string) string          { return strings.TrimSpace(s) }
+func duration10x(ms10 int64) time.Duration { return time.Duration(ms10) * time.Millisecond * 10 }