Help us shape the future of Go! Take the 2026 Go Developer Survey

polly

package
v1.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 36 Imported by: 0

README

Polly

Parity grade: A · SDK aws-sdk-go-v2/service/polly@v1.65.4 · last audited 2026-10-07 (c9523cebb)

Coverage

Metric Value
PARITY entries audited 10 (5 ok, 5 partial)
Feature families 4 (4 ok)
Known gaps none
Deferred items 0
Resource leaks clean

More

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrLexiconNotFound is returned when a requested lexicon is absent.
	ErrLexiconNotFound = errors.New("LexiconNotFoundException")
	// ErrTaskNotFound is returned when a requested synthesis task is absent.
	ErrTaskNotFound = errors.New("SynthesisTaskNotFoundException")
	// ErrValidation maps to the generic frontend "ValidationException" code;
	// ops that do not model it surface it as a smithy.GenericAPIError.
	ErrValidation = errors.New("ValidationException")
	// ErrTextLengthExceeded is returned when Text exceeds the format-specific length limit.
	ErrTextLengthExceeded = errors.New("TextLengthExceededException")
	// ErrInvalidSampleRate is returned when SampleRate is not valid for the requested OutputFormat.
	ErrInvalidSampleRate = errors.New("InvalidSampleRateException")
	// ErrEngineNotSupported is returned when the requested voice does not support the requested engine.
	ErrEngineNotSupported = errors.New("EngineNotSupportedException")
	// ErrLanguageNotSupported is returned when the requested voice does not support the requested language.
	ErrLanguageNotSupported = errors.New("LanguageNotSupportedException")
	// ErrMarksNotSupportedForFormat is returned when SpeechMarkTypes is requested with a non-json OutputFormat.
	ErrMarksNotSupportedForFormat = errors.New("MarksNotSupportedForFormatException")
	// ErrSsmlMarksNotSupportedForTextType is returned when the "ssml" speech mark type is
	// requested with a plain-text TextType.
	ErrSsmlMarksNotSupportedForTextType = errors.New("SsmlMarksNotSupportedForTextTypeException")
	// ErrInvalidNextToken is returned when a pagination token cannot be decoded.
	ErrInvalidNextToken = errors.New("InvalidNextTokenException")
	// ErrInvalidLexicon is returned when lexicon Content is not well-formed PLS lexicon XML.
	ErrInvalidLexicon = errors.New("InvalidLexiconException")
	// ErrLexiconSizeExceeded is returned when lexicon Content exceeds the maximum lexicon size.
	ErrLexiconSizeExceeded = errors.New("LexiconSizeExceededException")
	// ErrMaxLexemeLengthExceeded is returned when a <phoneme>/<alias> replacement in
	// lexicon Content exceeds the maximum lexeme replacement length.
	ErrMaxLexemeLengthExceeded = errors.New("MaxLexemeLengthExceededException")
	// ErrMaxLexiconsNumberExceeded is returned when PutLexicon would create a new
	// lexicon beyond the per-account lexicon count quota.
	ErrMaxLexiconsNumberExceeded = errors.New("MaxLexiconsNumberExceededException")
	// ErrUnsupportedPlsAlphabet is returned when lexicon Content specifies an
	// alphabet other than "ipa" or "x-sampa".
	ErrUnsupportedPlsAlphabet = errors.New("UnsupportedPlsAlphabetException")
	// ErrUnsupportedPlsLanguage is returned when lexicon Content specifies an
	// xml:lang value outside Polly's supported LanguageCode set.
	ErrUnsupportedPlsLanguage = errors.New("UnsupportedPlsLanguageException")
	// ErrInvalidS3Bucket is returned when OutputS3BucketName is not a valid S3 bucket name.
	ErrInvalidS3Bucket = errors.New("InvalidS3BucketException")
	// ErrInvalidS3Key is returned when OutputS3KeyPrefix is not a valid S3 object key.
	ErrInvalidS3Key = errors.New("InvalidS3KeyException")
	// ErrInvalidSnsTopicArn is returned when SnsTopicArn is not a well-formed SNS topic ARN.
	ErrInvalidSnsTopicArn = errors.New("InvalidSnsTopicArnException")
	// ErrInvalidSsml is returned when TextType is "ssml" but Text is not
	// well-formed SSML wrapped in a <speak> root element.
	ErrInvalidSsml = errors.New("InvalidSsmlException")
	// ErrInvalidTaskID is returned when a TaskId path parameter is not a
	// syntactically valid task identifier (as opposed to a well-formed one that
	// simply does not exist, which is ErrTaskNotFound).
	ErrInvalidTaskID = errors.New("InvalidTaskIdException")
	// ErrStreamValidation is returned for StartSpeechSynthesisStream input
	// validation failures. AWS models this operation's client errors as the
	// generic smithy ValidationException, not the op-specific exceptions
	// (EngineNotSupportedException, InvalidSampleRateException, ...) used by
	// SynthesizeSpeech/StartSpeechSynthesisTask -- see
	// aws-sdk-go-v2/service/polly's StartSpeechSynthesisStream deserializer
	// error switch, which only lists ServiceFailureException,
	// ServiceQuotaExceededException, ThrottlingException, and ValidationException.
	ErrStreamValidation = errors.New("ValidationException")
	// ErrThrottling is returned when a request exceeds Polly's real per-second
	// transaction-rate quota. Confirmed via
	// aws-sdk-go-v2/service/polly@v1.60.4/deserializers.go: of all 10 ops,
	// only StartSpeechSynthesisStream's awsRestjson1_deserializeOpError switch
	// declares ThrottlingException -- see limits.go.
	ErrThrottling = errors.New("ThrottlingException")
	// ErrServiceQuotaExceeded is returned when a request exceeds a real Polly
	// service quota that is not one of the more specific Max*/*SizeExceeded
	// sentinels above. Confirmed via the same deserializer scan as
	// ErrThrottling: only StartSpeechSynthesisStream declares
	// ServiceQuotaExceededException -- see limits.go.
	ErrServiceQuotaExceeded = errors.New("ServiceQuotaExceededException")
)

Functions

This section is empty.

Types

type DescribeVoicesFilter

type DescribeVoicesFilter struct {
	Engine                         string
	LanguageCode                   string
	Gender                         string
	NextToken                      string
	IncludeAdditionalLanguageCodes bool
}

DescribeVoicesFilter limits voice responses.

type Handler

type Handler struct {
	Backend *InMemoryBackend
	// contains filtered or unexported fields
}

Handler implements Amazon Polly REST JSON operations.

func NewHandler

func NewHandler(backend *InMemoryBackend) *Handler

NewHandler creates handler for backend.

func (*Handler) BackendFor

func (h *Handler) BackendFor(region string) *InMemoryBackend

BackendFor returns the backend serving region: the home backend, or the sibling built on first use.

func (*Handler) ChaosOperations

func (h *Handler) ChaosOperations() []string

ChaosOperations returns injectable operation list.

func (*Handler) ChaosRegions

func (h *Handler) ChaosRegions() []string

ChaosRegions returns backend region.

func (*Handler) ChaosServiceName

func (h *Handler) ChaosServiceName() string

ChaosServiceName returns service key.

func (*Handler) EnableRegions

func (h *Handler) EnableRegions()

EnableRegions makes h serve every other region through lazily built per-region siblings.

func (*Handler) ExtractOperation

func (h *Handler) ExtractOperation(c *echo.Context) string

ExtractOperation derives operation from request method and path.

func (*Handler) ExtractResource

func (h *Handler) ExtractResource(c *echo.Context) string

ExtractResource derives task ID, lexicon name, or ARN from request path.

func (*Handler) GetSupportedOperations

func (h *Handler) GetSupportedOperations() []string

GetSupportedOperations returns implemented SDK operations.

func (*Handler) Handler

func (h *Handler) Handler() echo.HandlerFunc

Handler serves each request from the handler of its region.

func (*Handler) MatchPriority

func (h *Handler) MatchPriority() int

MatchPriority returns REST service routing priority.

func (*Handler) Name

func (h *Handler) Name() string

Name returns service name.

func (*Handler) RegionBackends

func (h *Handler) RegionBackends() []*InMemoryBackend

RegionBackends returns the home backend followed by every sibling built so far.

func (*Handler) RegionHandler

func (h *Handler) RegionHandler(region string) *Handler

RegionHandler returns the handler serving region: h itself for the home region, else its sibling.

func (*Handler) Reset

func (h *Handler) Reset()

Reset clears every region.

func (*Handler) Restore

func (h *Handler) Restore(ctx context.Context, data []byte) error

Restore implements persistence.Persistable.

func (*Handler) RouteMatcher

func (h *Handler) RouteMatcher() service.Matcher

RouteMatcher matches versioned Polly routes.

func (*Handler) Snapshot

func (h *Handler) Snapshot(ctx context.Context) []byte

Snapshot implements persistence.Persistable; other regions ride in an additive "regions" key.

type InMemoryBackend

type InMemoryBackend struct {
	// contains filtered or unexported fields
}

InMemoryBackend stores Polly resources safely for concurrent requests.

lexicons and tasks are *store.Table[T]-backed (see store_setup.go and pkgs/store's package doc). voices is the static built-in voice catalogue, not a mutable resource collection.

streamRequests/streamsInFlight are transient StartSpeechSynthesisStream rate-limiter state (see throttle.go/limits.go) -- deliberately plain backend fields, not a store.Table or backendSnapshot member, so they are never persisted (pkgs/persistence's TestSnapshotVersionGuard only inventories *Snapshot-suffixed structs and store.Register'd types; neither applies here) and never survive a restart, matching real AWS throttle state.

func NewInMemoryBackend

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates a Polly backend configured for default AWS identity.

func NewInMemoryBackendWithConfig

func NewInMemoryBackendWithConfig(accountID, region string) *InMemoryBackend

NewInMemoryBackendWithConfig creates a Polly backend configured for account and region.

func (*InMemoryBackend) BeginSpeechSynthesisStream

func (b *InMemoryBackend) BeginSpeechSynthesisStream(engine string) (func(), error)

BeginSpeechSynthesisStream enforces StartSpeechSynthesisStream's real AWS quotas (limits.go) before a request proceeds. The concurrent-request cap is checked first: an unreleased slot only ever comes from a request that is still in flight, a stronger overload signal than one more tick in the rate window. On success the caller MUST invoke the returned release func exactly once when the request finishes (defer works); on error the returned func is nil.

func (*InMemoryBackend) DeleteLexicon

func (b *InMemoryBackend) DeleteLexicon(name string) error

DeleteLexicon removes named lexicon.

func (*InMemoryBackend) DescribeVoices

func (b *InMemoryBackend) DescribeVoices(filter DescribeVoicesFilter) ([]Voice, error)

DescribeVoices lists built-in voices matching filters.

func (*InMemoryBackend) GetLexicon

func (b *InMemoryBackend) GetLexicon(name string) (*Lexicon, error)

GetLexicon returns named lexicon.

func (*InMemoryBackend) GetSpeechSynthesisTask

func (b *InMemoryBackend) GetSpeechSynthesisTask(taskID string) (*SpeechSynthesisTask, error)

GetSpeechSynthesisTask retrieves task and advances simulated lifecycle.

func (*InMemoryBackend) ListLexicons

func (b *InMemoryBackend) ListLexicons() []*Lexicon

ListLexicons lists lexicons ordered by name.

func (*InMemoryBackend) ListSpeechSynthesisTasks

func (b *InMemoryBackend) ListSpeechSynthesisTasks(
	status, token string,
	maxResults int,
) ([]*SpeechSynthesisTask, string, error)

ListSpeechSynthesisTasks lists tasks and advances lifecycle consistently with AWS polling.

func (*InMemoryBackend) PutLexicon

func (b *InMemoryBackend) PutLexicon(name, content string) error

PutLexicon creates or replaces lexicon content.

func (*InMemoryBackend) Region

func (b *InMemoryBackend) Region() string

Region returns configured AWS region.

func (*InMemoryBackend) Reset

func (b *InMemoryBackend) Reset()

Reset clears stored resources.

func (*InMemoryBackend) Restore

func (b *InMemoryBackend) Restore(ctx context.Context, data []byte) error

Restore deserializes backend state from a snapshot. It implements persistence.Persistable.

func (*InMemoryBackend) SetAppConfig

func (b *InMemoryBackend) SetAppConfig(cfg any)

SetAppConfig records the service.AppContext.Config for lazy S3 lookup.

func (*InMemoryBackend) SetLifecycleDelay

func (b *InMemoryBackend) SetLifecycleDelay(d time.Duration)

SetLifecycleDelay sets the dwell per stage for synthesis tasks (scheduled, then inProgress, then terminal). Zero (the default) advances one stage per poll.

func (*InMemoryBackend) SetS3Writer

func (b *InMemoryBackend) SetS3Writer(w S3Writer)

SetS3Writer overrides the S3 destination for synthesis task output.

func (*InMemoryBackend) Snapshot

func (b *InMemoryBackend) Snapshot(ctx context.Context) []byte

Snapshot serializes the backend state to JSON. It implements persistence.Persistable.

func (*InMemoryBackend) StartSpeechSynthesisTask

func (b *InMemoryBackend) StartSpeechSynthesisTask(
	options SynthesisOptions,
	outputBucket, outputKeyPrefix, topicArn string,
) (*SpeechSynthesisTask, error)

StartSpeechSynthesisTask creates scheduled asynchronous task.

func (*InMemoryBackend) SynthesizeSpeech

func (b *InMemoryBackend) SynthesizeSpeech(options SynthesisOptions) (*SynthesizedSpeech, error)

SynthesizeSpeech validates options and returns deterministic audio or speech-mark output.

func (*InMemoryBackend) WithClock

func (b *InMemoryBackend) WithClock(now func() time.Time) *InMemoryBackend

WithClock overrides the backend's time source, used by tests to drive StartSpeechSynthesisStream's sliding throttle window (checkStreamThrottleLocked) deterministically -- no time.Sleep, no real wall-clock waits.

func (*InMemoryBackend) WithStreamLimits

func (b *InMemoryBackend) WithStreamLimits(tps, concurrency int) *InMemoryBackend

WithStreamLimits overrides StartSpeechSynthesisStream's throttle/concurrency caps (see limits.go). A zero argument keeps its real-AWS default -- lets tests trip the cap without issuing defaultStreamTPS/defaultStreamConcurrency real requests.

type Lexicon

type Lexicon struct {
	LastModified time.Time
	Name         string
	ARN          string
	Content      string
	Alphabet     string
	LanguageCode string
	LexemesCount int
	Size         int
}

Lexicon stores pronunciation content and computed lexicon attributes.

type Provider

type Provider struct{}

Provider implements service.Provider for Amazon Polly.

func (*Provider) Init

Init initializes Polly backend and REST handler.

func (*Provider) Name

func (p *Provider) Name() string

Name returns provider name.

type S3Writer

type S3Writer interface {
	PutObject(ctx context.Context, bucket, key string, data []byte) error
}

S3Writer stores a finished task's output object.

type SpeechSynthesisTask

type SpeechSynthesisTask struct {
	CreationTime       time.Time
	TaskID             string
	TaskStatus         string
	TaskStatusReason   string
	OutputURI          string
	OutputS3BucketName string
	OutputS3KeyPrefix  string
	SNSTopicArn        string
	Options            SynthesisOptions
	// contains filtered or unexported fields
}

SpeechSynthesisTask represents an asynchronous synthesis task.

type SynthesisOptions

type SynthesisOptions struct {
	Engine          string
	LanguageCode    string
	OutputFormat    string
	SampleRate      string
	Text            string
	TextType        string
	VoiceID         string
	LexiconNames    []string
	SpeechMarkTypes []string
}

SynthesisOptions contains common synchronous and asynchronous synthesis parameters.

type SynthesizedSpeech

type SynthesizedSpeech struct {
	ContentType       string
	Data              []byte
	RequestCharacters int
}

SynthesizedSpeech is deterministic output from SynthesizeSpeech.

type Voice

type Voice struct {
	AdditionalLanguageCodes []string `json:"AdditionalLanguageCodes,omitempty"`
	LanguageCode            string   `json:"LanguageCode"`
	LanguageName            string   `json:"LanguageName"`
	Gender                  string   `json:"Gender"`
	ID                      string   `json:"Id"`
	Name                    string   `json:"Name"`
	SupportedEngines        []string `json:"SupportedEngines"`
}

Voice describes a voice that can be selected for synthesis.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL