Documentation
¶
Overview ¶
Package transcription defines the serializable audio-to-text protocol and its single-method Model capability.
NewRequest accepts validated media audio. Options carries the shared language hint and provider extensions written through Options.SetExtension so they are JSON-safe. Request has no arbitrary parameter bag. Implementations and defaults live outside Core.
Example ¶
package main
import (
"fmt"
"github.com/Tangerg/scope/core/media"
"github.com/Tangerg/scope/core/transcription"
)
func main() {
audio, err := media.NewBytes("audio/wav", []byte("audio"))
if err != nil {
panic(err)
}
request, err := transcription.NewRequest(audio)
if err != nil {
panic(err)
}
options := transcription.Options{Model: "transcription-model"}
err = options.Validate()
if err != nil {
panic(err)
}
options.Language = "en"
request.Options = options
fmt.Println(request.Audio.MIME, request.Options.Language)
}
Output: audio/wav en
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
Functions ¶
This section is empty.
Types ¶
type Model ¶
type Model interface {
// Call transcribes one validated media request without retaining or mutating
// it. The returned provider-neutral response belongs to the caller, and
// context cancellation remains identifiable through errors.Is.
Call(ctx context.Context, request *Request) (*Response, error)
}
Model is the complete provider-neutral transcription SPI. Call implementations validate requests before I/O, reject explicit options they cannot represent, preserve context error identity, and return responses that pass Validate. Provider defaults and identity belong to provider construction and observability.
type Options ¶
type Options struct {
// Model is the provider model identifier (e.g. "whisper-1").
Model string `json:"model"`
// Language is an ISO-639-1 language code (e.g. "en", "zh") hinting
// the spoken language. Empty leaves detection to the provider.
Language string `json:"language"`
// Extensions carries JSON-safe provider-specific options unknown to this
// struct.
Extensions metadata.Extensions `json:"extensions,omitzero"`
}
Options holds provider-neutral transcription configuration. Provider-specific controls belong in Extensions. Resolve overlays only explicitly supplied values and snapshots extension data, leaving both inputs unchanged.
func (Options) MarshalJSON ¶
func (*Options) UnmarshalJSON ¶
type Output ¶
type Output struct {
// Text is the transcribed text. Empty is allowed for partial /
// silence segments.
Text string `json:"text"`
// Metadata carries per-segment extras.
Metadata metadata.Map `json:"metadata,omitzero"`
}
Output is one transcription segment.
func (Output) MarshalJSON ¶
func (*Output) UnmarshalJSON ¶
type Request ¶
type Request struct {
// Audio carries the audio bytes (or URL) to transcribe.
Audio *media.Media `json:"audio,omitempty"`
Options Options `json:"options,omitzero"`
}
Request is one transcription call: the audio payload and explicit options.
func (Request) MarshalJSON ¶
func (*Request) UnmarshalJSON ¶
type Response ¶
type Response struct {
// Output holds the transcribed text. Non-nil after [NewResponse].
Output *Output `json:"output,omitempty"`
Metadata *ResponseMetadata `json:"metadata,omitempty"`
}
Response is one transcription call's output plus shared metadata. Providers that emit per-segment timing (Whisper verbose_json) should stash the segment array under Output.Metadata.Extra; the top-level Output holds the merged transcript text.
func NewResponse ¶
func NewResponse(output *Output, responseMetadata *ResponseMetadata) (*Response, error)
func (Response) MarshalJSON ¶
func (*Response) UnmarshalJSON ¶
type ResponseMetadata ¶
type ResponseMetadata struct {
// Model is the model name actually served.
Model string `json:"model"`
// CreatedAt is the provider-reported creation timestamp.
CreatedAt time.Time `json:"created_at,omitzero"`
// Extra carries JSON-safe provider-specific metadata.
Extra metadata.Map `json:"extra,omitzero"`
}
ResponseMetadata holds response-level metadata for a transcription call.
func (ResponseMetadata) MarshalJSON ¶
func (r ResponseMetadata) MarshalJSON() ([]byte, error)
func (*ResponseMetadata) UnmarshalJSON ¶
func (r *ResponseMetadata) UnmarshalJSON(data []byte) error
Source Files