playht

package module
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Jul 10, 2024 License: Apache-2.0 Imports: 19 Imported by: 0

README

go-playht

Build Status go.dev reference

Unofficial Go module for play.ht API client.

The official play.ht API documentation, upon which this Go module has been built, can be found here.

In order to use this Go module you must create an account with play.ht and generate API secret and retrieve your User ID. See the official docs here.

Get started

Get the module

go get ./...

Run tests:

go test -v ./...

There are a few code samples available in the examples directory so please do have a look. They could give you some idea about how to use this Go module.

[!IMPORTANT] Before you attempt to run the samples you must set a couple of environment variables These are automatically read by the client when it gets created; you can override them in your own code.

  • PLAYHT_SECRET_KEY: API secret key
  • PLAYHT_USER_ID: Play.HT User ID

Nix

There is a Nix flake file vailable which lets you work on the Go module using nix.

Just run the following command and you are in the business:

nix develop

Basics

There are two ways to create audio/speech from the text using the API:

  • Job: audio generation is done in async; when you create a job you can monitor its progress via SSE
  • Stream: a real-time audio stream available immediately as soon as the stream has been created via the API

The API also allows you to clone a voice using a small sample of limited size. See the docs.

[!NOTE] the proto code was generated by running protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=paths=source_relative proto/api.proto

TODO

  • Lease refresh for gRPC streaming

Documentation

Index

Constants

View Source 
const (
	// BaseURL is OpenAI HTTP API base URL.
	BaseURL = "https://api.play.ht/api"
	// GrpcAddr is the default gRPC endpoint.
	GrpcAddr = "prod.turbo.play.ht:443"
	// APIV2 V2 version.
	APIV2 = "v2"
	// APIV2 V1 version.
	APIV1 = "v1"
	// UserIDHeader
	UserIDHeader = "X-USER-ID"
)
View Source 
const (
	// HTEpoch is the HT Lease epoch.
	// I've no idea why but whatever.
	HTEpoch int64 = 1519257480 // 2018-02-21 23:58:00 UTC
)

Variables

View Source 
var (
	// ErrUnknown is returned when an unknown error occurrs.
	ErrUnknown = errors.New("unknown error")
)

Functions

func Float32Ptr added in v0.0.2 

func Float32Ptr(f float32) *float32

Float32Ptr returns pointer to f.

func Int32Ptr added in v0.0.2 

func Int32Ptr(i int32) *int32

Int32Ptr returns pointer to i.

func MakeGrpcStreamRequest added in v0.0.2 

func MakeGrpcStreamRequest(lease []byte, req *CreateTTSStreamReq) *pb.TtsRequest

MakeGrpcStreamRequest creates a new gRPC stream request from lease and req. NOTE: gRPC doesn't provide VoiceEngine and Emotion configuration at the moment.

func ToPbFormat added in v0.0.2 

func ToPbFormat(f OutputFormat) *pb.Format

ToPbFormat converts OutputFormat to its proto representation.

func ToPbQuality added in v0.0.2 

func ToPbQuality(q Quality) *pb.Quality

ToPbQuality converts Quality to its proto representation.

Types

type APIError 

type APIError struct {
	Generic        *ErrGeneric
	Internal       *ErrInternal
	RateLimit      *ErrRateLimit
	UnexpecedError json.RawMessage
}

APIError is a pseudo-sum type API error type.

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) UnmarshalJSON added in v0.1.2 

func (e *APIError) UnmarshalJSON(data []byte) error

type Client 

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

Client is an OpenAI HTTP API client.

func NewClient 

func NewClient(opts ...Option) *Client

NewClient creates a new HTTP API client and returns it. By default it reads the secret key from PLAYHT_SECRET_KEY env var and user ID from PLAYHT_USER_ID env var and uses the default http client for making the HTTP api requests.

func (*Client) CreateInstantVoiceCloneFromFile 

func (c *Client) CreateInstantVoiceCloneFromFile(ctx context.Context, cloneReq *CloneVoiceFileRequest) (*ClonedVoice, error)

CreateInstantVoiceCloneFromFile creates an instant voice clone by providing a sample audio file via file upload.

func (*Client) CreateInstantVoiceCloneFromURL 

func (c *Client) CreateInstantVoiceCloneFromURL(ctx context.Context, cloneReq *CloneVoiceURLRequest) (*ClonedVoice, error)

CreateInstantVoiceCloneFromURL create an instant voice clone by providing an URL for a sample audio file.

func (*Client) CreateLease added in v0.0.2 

func (c *Client) CreateLease(ctx context.Context, _ *CreateLeaseReq) (*Lease, error)

CreateLease creates a new lease and returns it.

func (*Client) CreateTTSJob 

func (c *Client) CreateTTSJob(ctx context.Context, createReq *CreateTTSJobReq) (*TTSJob, error)

CreateTTSJob creates a new Text-to-Speech (TTS) job that converts input text into audio asynchronously

func (*Client) CreateTTSJobWithProgressStream 

func (c *Client) CreateTTSJobWithProgressStream(ctx context.Context, w io.Writer, createReq *CreateTTSJobReq) (string, error)

CreateTTSJobWithProgressStream creates a new Text-to-Speech (TTS) SSE stream that converts input text into audio asynchronously and returns the job progress SSE stream URL. If w is not nil, the events are streamed into it.

func (*Client) DeleteClonedVoice 

func (c *Client) DeleteClonedVoice(ctx context.Context, delReq *DeleteClonedVoiceRequest) (*DeleteClonedVoiceResp, error)

DeleteClonedVoice eletes a cloned voice created by the user using the provided voice_id.

func (*Client) GetClonedVoices 

func (c *Client) GetClonedVoices(ctx context.Context) ([]ClonedVoice, error)

GetClonedVoices obtains a list of all cloned voices created by the user.

func (*Client) GetTTSJob 

func (c *Client) GetTTSJob(ctx context.Context, id string) (*TTSJob, error)

GetTTSJob retrieves information about an async text-to-speech job.

func (*Client) GetTTSJobAudioStream 

func (c *Client) GetTTSJobAudioStream(ctx context.Context, w io.Writer, id string) error

GetTTSJobAudioStream retrieves the TTS job audio stream from the job with the given id. It streams audio in the MP3 format or returns error if the file was not generated as MP3.

func (*Client) GetTTSJobProgressStream 

func (c *Client) GetTTSJobProgressStream(ctx context.Context, w io.Writer, id string) error

GetTTSJobProgressStream retrieves the TTS job progress SSE stream for the job with the given id and streams it into w.

func (*Client) GetVoices 

func (c *Client) GetVoices(ctx context.Context) ([]Voice, error)

GetVoices returns the full list of stock PlayHT GetVoices.

func (*Client) RefreshLease added in v0.0.2 

func (c *Client) RefreshLease(ctx context.Context, createReq *CreateLeaseReq) (*Lease, error)

RefreshLease refreshes the existing Lease and returns it.

func (*Client) TTSGrpcStream added in v0.0.2 

func (c *Client) TTSGrpcStream(ctx context.Context, w io.Writer, req *pb.TtsRequest) error

TTSGrpcStream creates a new TTS stream ovr gRCP and streams the audio bytes immediately.

func (*Client) TTSStream 

func (c *Client) TTSStream(ctx context.Context, w io.Writer, createReq *CreateTTSStreamReq) error

TTSStream creates a new TTS stream and streams the audio bytes immediately.

func (*Client) TTSStreamURL 

func (c *Client) TTSStreamURL(ctx context.Context, createReq *CreateTTSStreamReq) (*TTSStreamURL, error)

TTSStreamURL creates a new TTS stream and returns data containing an URL that is immediately streamable.

type CloneVoiceFileRequest 

type CloneVoiceFileRequest struct {
	SampleFile string `json:"sample_file"`
	VoiceName  string `json:"voice_name"`
	MimeType   string `json:"mime_type"`
}

CloneVoiceFileRequest is used to create a voice clone.

type CloneVoiceURLRequest 

type CloneVoiceURLRequest struct {
	SampleFileURL string `json:"sample_file_url"`
	VoiceName     string `json:"voice_name"`
}

CloneVoiceURLRequest is used to create a voice clone via file URL.

type ClonedVoice 

type ClonedVoice struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Type string `json:"type"`
}

ClonedVoice data.

type CreateLeaseReq added in v0.0.2 

type CreateLeaseReq struct{}

CreateLeaseReq is used to create a nw Lease.

type CreateTTSJobReq 

type CreateTTSJobReq struct {
	Text          string       `json:"text"`
	Voice         string       `json:"voice"`
	Quality       Quality      `json:"quality"`
	OutputFormat  OutputFormat `json:"output_format"`
	VoiceEngine   VoiceEngine  `json:"voice_engine,omitempty"`
	Emotion       Emotion      `json:"emotion,omitempty"`
	Speed         float32      `json:"speed"`
	Temperature   float32      `json:"temperature,omitempty"`
	SampleRate    int32        `json:"sample_rate"`
	Seed          uint8        `json:"seed,omitempty"`
	VoiceGuidance float32      `json:"voice_guidance,omitempty"`
	StyleGuidance float32      `json:"style_guidance,omitempty"`
}

CreateTTSJobReq is used to create a new TTS.

type CreateTTSStreamReq 

type CreateTTSStreamReq struct {
	Text          string       `json:"text"`
	Voice         string       `json:"voice"`
	Quality       Quality      `json:"quality"`
	OutputFormat  OutputFormat `json:"output_format,omitempty"`
	VoiceEngine   VoiceEngine  `json:"voice_engine,omitempty"`
	Emotion       Emotion      `json:"emotion,omitempty"`
	SampleRate    int32        `json:"sample_rate"`
	Seed          int32        `json:"seed,omitempty"`
	VoiceGuidance float32      `json:"voice_guidance,omitempty"`
	StyleGuidance float32      `json:"style_guidance,omitempty"`
	TextGuidance  float32      `json:"text_guidance,omitempty"`
	Temperature   float32      `json:"temperature,omitempty"`
	Speed         float32      `json:"speed"`
}

CreateTTSStreamReq is used to create TTS stream.

type DeleteClonedVoiceRequest 

type DeleteClonedVoiceRequest struct {
	VoiceID string `json:"voice_id"`
}

DeleteVoiceRequest is used to deleted cloned voice.

type DeleteClonedVoiceResp 

type DeleteClonedVoiceResp struct {
	Message string      `json:"message"`
	Deleted ClonedVoice `json:"deleted"`
}

DeleteClonedVoiceResp is returned when the cloned voice has been deleted.

type Emotion 

type Emotion string
const (
	FemaleHappy     Emotion = "female_happy"
	FemaleSad       Emotion = "female_sad"
	FemaleAngry     Emotion = "female_angry"
	FemaleFearful   Emotion = "female_fearful"
	FemaleDisgust   Emotion = "female_disgust"
	FemaleSurprised Emotion = "female_surprised"
	MaleHappy       Emotion = "male_happy"
	MaleSad         Emotion = "male_sad"
	MaleAngry       Emotion = "male_angry"
	MaleFearful     Emotion = "male_fearful"
	MaleDisgust     Emotion = "male_disgust"
	MaleSurprised   Emotion = "male_surprised"
)

func (Emotion) String 

func (e Emotion) String() string

type ErrGeneric added in v0.1.2 

type ErrGeneric struct {
	ID      string `json:"error_id"`
	Message string `json:"error_message"`
}

ErrGeneric is a generic API error.

func (ErrGeneric) Error added in v0.1.2 

func (e ErrGeneric) Error() string

Error implements error interface.

type ErrInternal added in v0.1.2 

type ErrInternal struct {
	Message string `json:"message"`
	Err     string `json:"error"`
}

ErrInternal is an error returned when the API responds with 50x status code.

func (ErrInternal) Error added in v0.1.2 

func (e ErrInternal) Error() string

Error implements error interface.

type ErrRateLimit added in v0.1.2 

type ErrRateLimit struct {
	Message string
}

ErrRateLimit is an error returned when the API rate limit is exceeded

func (ErrRateLimit) Error added in v0.1.2 

func (e ErrRateLimit) Error() string

Error implements error interface.

type Lease added in v0.0.2 

type Lease struct {
	Data     []byte
	Created  time.Time
	Duration time.Duration
	Metadata map[string]any
}

Lease for gRPC stream.

func (*Lease) Expires added in v0.0.2 

func (l *Lease) Expires() time.Time

Expires returns a timestamp when the Lease expires 

type Link struct {
	ContentType string `json:"content_type,omitempty"`
	Description string `json:"description,omitempty"`
	Href        string `json:"href,omitempty"`
	Method      string `json:"method,omitempty"`
	Rel         string `json:"rel,omitempty"`
}

type Option 

type Option func(*Options)

Option is functional graph option.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL sets the API base URL.

func WithGRPCClient added in v0.0.2 

func WithGRPCClient(c *grpc.ClientConn) Option

WithGRPCClient sets the gRPC client.

func WithHTTPClient 

func WithHTTPClient(httpClient *client.HTTP) Option

WithHTTPClient sets the HTTP client.

func WithSecretKey 

func WithSecretKey(apiKey string) Option

WithSecretKey sets the secret key.

func WithUserID 

func WithUserID(userID string) Option

WithUserID sets the user ID.

func WithVersion 

func WithVersion(version string) Option

WithVersion sets the API version.

type Options 

type Options struct {
	SecretKey  string
	UserID     string
	BaseURL    string
	Version    string
	HTTPClient *client.HTTP
	GRPC       *grpc.ClientConn
}

type OutputFormat 

type OutputFormat string
const (
	Mp3   OutputFormat = "mp3"
	Wav   OutputFormat = "wav"
	Ogg   OutputFormat = "ogg"
	Flac  OutputFormat = "flac"
	Mulaw OutputFormat = "mulaw"
)

func (OutputFormat) String 

func (o OutputFormat) String() string

type Quality 

type Quality string
const (
	Draft   Quality = "draft"
	Low     Quality = "low"
	Medium  Quality = "medium"
	High    Quality = "high"
	Premium Quality = "premium"
)

func (Quality) String 

func (q Quality) String() string

type TTSJob 

type TTSJob struct {
	ID      string           `json:"id"`
	Created time.Time        `json:"created"`
	Input   *CreateTTSJobReq `json:"input"`
	Output  struct {
		Size     int     `json:"size"`
		URL      string  `json:"url"`
		Duration float64 `json:"duration"`
	} `json:"output"`
	Status string `json:"status,omitempty"`
	Links  []Link `json:"_links,omitempty"`
}

TTSJob is returned when a new TTS async job has been created.

type TTSStreamURL 

type TTSStreamURL struct {
	HRef   string `json:"href"`
	Method string `json:"method"`
	CType  string `json:"contentType"`
	Rel    string `json:"rel"`
	Desc   string `json:"description"`
}

TTSStreamURL is returned when the stream URL is requested.

type Voice 

type Voice struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Sample   string `json:"sample"`
	Accent   string `json:"accent"`
	Age      string `json:"age"`
	Gender   string `json:"gender"`
	Language string `json:"language"`
	LangCode string `json:"language_code"`
	Loudness string `json:"loudness"`
	Style    string `json:"style"`
	Tempo    string `json:"tempo"`
	Texture  string `json:"texture"`
}

Voice is the stock PlayHT voice.

type VoiceEngine 

type VoiceEngine string
const (
	PlayHTv1      VoiceEngine = "PlayHT1.0"
	PlayHTv2      VoiceEngine = "PlayHT2.0"
	PlayHTv2Turbo VoiceEngine = "PlayHT2.0-turbo"
)

func (VoiceEngine) String 

func (v VoiceEngine) String() string

Source Files

View all Source files

Directories

Path Synopsis
examples
tts-grpc-stream
tts-job
tts-job-audio-stream
tts-job-progress-stream
tts-stream
tts-stream-url
voices

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.