htgo-tts

Text to speech package for Golang.

View on GitHub

Migrating from v1 to v2

htgo-tts v2 is a rewrite with a new import path, github.com/hegedustibor/htgo-tts/v2, and a new API: you choose the engine that does the synthesis, players read the audio from a stream instead of a file, every call takes a context.Context, and nothing is written to disk unless you ask for a cache folder. This guide maps the v1 API to v2 and lists what behaves differently.

v1 is not going away. go get github.com/hegedustibor/htgo-tts@v1.6.0 keeps serving the v1 API as it is: the v1.6.0 tag marks the same commit as the older v1.6 tag, which Go cannot resolve because it is not a semantic version. The v1 branch is where a critical fix for v1 would land; v1 gets no new features.

Import path

go get github.com/hegedustibor/htgo-tts/v2
import (
	htgotts "github.com/hegedustibor/htgo-tts/v2"
	"github.com/hegedustibor/htgo-tts/v2/engine/google"
	"github.com/hegedustibor/htgo-tts/v2/player"
	"github.com/hegedustibor/htgo-tts/v2/player/native"
	"github.com/hegedustibor/htgo-tts/v2/voices"
)

The handlers package is gone; player and player/native take its place. Both versions can live in one program during a transition, because their import paths differ.

Before and after

v1:

speech := htgotts.Speech{Folder: "audio", Language: voices.English, Handler: &handlers.MPlayer{}}
if err := speech.Speak("Hello, world!"); err != nil {
	log.Fatal(err)
}

v2:

tts, err := htgotts.New(google.New(voices.English), htgotts.WithFolder("audio"))
if err != nil {
	log.Fatal(err)
}
if err := tts.Speak(context.Background(), "Hello, world!"); err != nil {
	log.Fatal(err)
}

API

v1 v2
htgotts.Speech{Folder: "audio", Language: voices.English, Handler: &handlers.MPlayer{}} htgotts.New(google.New(voices.English), htgotts.WithFolder("audio"), htgotts.WithPlayer(player.MPlayer())); New returns an error for a nil engine or an invalid option
Language: voices.English, a string field of Speech google.New(voices.English): the language is a setting of the Google engine, and the constants have the type voices.Language
Folder: "audio", required htgotts.WithFolder("audio"), optional; without it no file is written
Handler: &handlers.MPlayer{}, or no handler htgotts.WithPlayer(player.MPlayer()), the default when no player is given
Handler: &handlers.Native{} htgotts.WithPlayer(native.New()), from the player/native package
Proxy: "http://…" google.WithProxy("http://…"), with TLS verification on
speech.Speak(text) tts.Speak(ctx, text)
speech.CreateSpeechFile(text, name), which wrote <Folder>/<name>.mp3 and returned the path tts.Save(ctx, text, "audio/name.mp3"): the path is yours to choose, the .mp3 extension is added when the path has none, the folder is created, and the path is returned
speech.CreateSpeechBuff(text, name), an io.Reader tts.Synthesize(ctx, text) for the bytes, or tts.Open(ctx, text) for a stream; neither writes a file unless there is a cache folder
speech.PlaySpeechFile(path) tts.PlayFile(ctx, path)
handlers.PlayerInterface, Play(fileName string) error player.Player, Play(ctx context.Context, audio io.Reader) error: the player reads the audio from the stream and stops when ctx is done
a handler of your own that runs a program on the file &player.Command{Name: "play", Args: []string{"-q", "-t", "mp3", "-"}}: any program that plays from its standard input
no equivalent htgotts.New(openai.New(openai.WithVoice(openai.VoiceNova))): the OpenAI engine, with model, voice, speed, format and instructions
no equivalent an engine of your own: any type with the three methods of engine.Engine
no equivalent tts.SynthesizeTo(ctx, text, w) and tts.Play(ctx, audio)

Behaviour