Changelog
All notable changes to this project are documented in this file.
The format is based on Keep a Changelog, and the project adheres to Semantic Versioning.
2.1.1 - 2026-10-20
A Dockerfile to copy and documentation that covers all six engines; nothing in the 2.1.0 API changes.
Added
examples/docker: a two-stage Dockerfile to copy for a program of your own. The build stage compiles thesaveandspeakprograms without cgo; the run stage isdebian:bookworm-slimwith the CA certificates for the engines and the player that thePLAYERbuild argument asks for (none,mplayer, ornativefor the ALSA library), and it runs the programs as an unprivileged user with their audio in the/audiovolume. Its README has the commands for saving and for playing with the host’s sound device, a root.dockerignorekeeps.gitand theaudiofolders out of the build context, and CI builds the image with everyPLAYERvalue and starts the programs. The Docker section of the README points to this file instead of a snippet that built a program the repository does not have (#33, #27).
Changed
- README and the doc comments of
htgotts,player/nativeand thenativeandcustom-engineexamples: the overview, the requirements, the native player’s row of the player table, the limitations and the package documentation describe all six engines instead of the two of 2.0.0: which ones need an API key and charge for the audio, which one works offline, which produce the 24 kHz MP3 that the native player expects and that ElevenLabs does not by default, and how much text each one speaks per request.
2.1.0 - 2026-10-20
Four more engines, each a few lines of configuration away from the existing ones; nothing in the 2.0.0 API changes.
Added
engine/azure: an engine for the Azure Speech text to speech REST endpoint, with a choice of voice, language, speaking style, rate, pitch and output format. The resource key and the region come fromWithKeyandWithRegionor fromAZURE_SPEECH_KEYandAZURE_SPEECH_REGION, andWithEndpointreaches custom voices and sovereign clouds. It needs no SDK and no cgo (#21).examples/azure, a program that speaks or saves a sentence through the Azure Speech engine.engine/googlecloud: an engine for the Google Cloud Text-to-Speech REST endpoint, the official, paid counterpart of the Translate endpoint, with a choice of voice, language, gender, speaking rate, pitch, volume, sample rate and output format. The API key comes fromWithKeyor fromGOOGLE_CLOUD_API_KEYand travels in a header, never in the URL, andWithEndpointreaches the regional endpoints. It needs no SDK and no cgo.examples/googlecloud, a program that speaks or saves a sentence through the Google Cloud Text-to-Speech engine.engine/command: an engine that runs a speech program installed on the machine, such as thesaycommand of macOS, espeak-ng or piper, with the text on its standard input or in an argument and the audio from its standard output or from a file it writes.Say,ESpeakNGandPiperare ready-made,Newtakes any other program, andWithDir,WithEnvandWithTimeoutset the working directory, the environment and a time limit. It needs no API key and no network, so speech works offline (#14).examples/command, a program that speaks or saves a sentence through a speech program on the machine.engine/elevenlabs: an engine for the ElevenLabs text to speech API, with a choice of voice, model, language, stability, similarity, style, speaker boost, speed and output format. The API key comes fromWithKeyor fromELEVENLABS_API_KEY,WithBaseURLreaches the data residency endpoints, and long text is requested piece by piece withprevious_textandnext_textfor continuity. It needs no SDK and no cgo.examples/elevenlabs, a program that speaks or saves a sentence through the ElevenLabs engine.
2.0.0 - 2026-10-20
A rewrite with the new import path github.com/hegedustibor/htgo-tts/v2. The v1 API stays available as github.com/hegedustibor/htgo-tts@v1.6.0 and from the v1 branch; MIGRATION.md maps it to v2.
Added
- The
engine.Engineinterface. The engine that does the synthesis is the first argument ofhtgotts.New, and any type with its three methods,Synthesize,FormatandFingerprint, can be used in place of the engines of the module, for example one that calls Azure Speech (#21). The README says which service the module speaks through (#20). engine/openai: an engine for the OpenAI speech API and any OpenAI-compatible endpoint, with a choice of model, voice, speed and output format and, with gpt-4o-mini-tts, instructions on how to speak. The API key comes fromWithAPIKeyorOPENAI_API_KEY, andWithBaseURLreaches Azure OpenAI and local servers. It brings the choice of voice that the Google Translate endpoint cannot offer (#5).Speech.SynthesizeandSpeech.SynthesizeToreturn the audio in memory or write it to anio.Writer, andSpeech.Openstreams it, all without writing a file (#23).Speech.Savewrites the audio to a path of the caller’s choice, creating the folder and adding the engine’s extension when the path has none (#30).- A
context.Contexton every network and playback call:Speak,Open,Synthesize,SynthesizeTo,Save,PlayandPlayFilestop when the context is done, and so can a player of your own (#26). - The
playerpackage:player.Playerreceives the audio as anio.Reader;player.Commandruns any program that plays from its standard input, withplayer.MPlayer()andplayer.FFplay()ready-made;player.Discardplays nothing. player/native: the in-process MP3 player, now in a package of its own, built on oto v3 and go-mp3 and free of cgo on every platform.google.WithSlow,google.WithTimeout,google.WithHTTPClientandgoogle.WithEndpoint;engine.HTTPErrorandengine.ErrEmptyText; typed errors for a nil engine, a nil player, an empty folder and an empty path.voices.Language, a typed language code, andvoices.Bengali, which was unexported.- Tests that run without network, sound card or API key, and a GitHub Actions CI on Linux and macOS with gofmt, go vet, staticcheck, a cgo-free build and
go test -race. - Six runnable programs under
examples/(#28),MIGRATION.mdand this changelog.
Changed
- The module path is
github.com/hegedustibor/htgo-tts/v2, and the minimum Go version is 1.25 (v1 asked for Go 1.17). htgotts.Speechis created withhtgotts.New(engine, options...)instead of a struct literal, and its fields are unexported. The language belongs to the Google engine,google.New(voices.English); the player is set withhtgotts.WithPlayerand the folder withhtgotts.WithFolder.- The cache folder is optional: without
WithFolder, no file is written at all (#18). With it, the file names are the ones v1 wrote for the Google engine,<language>_<md5>.mp3, so an existing folder keeps serving. - Players receive a stream instead of a file name:
Play(ctx context.Context, audio io.Reader) error. mplayer and ffplay read it from standard input. - The proxy of the Google engine is set with
google.WithProxyand keeps TLS verification on; v1 turned it off. A client of your own, throughgoogle.WithHTTPClient, can turn it off. voices.EnglishUKisen-GB, the code the endpoint expects, instead ofen-UK; its cache files are therefore named differently.- The Google engine requests over HTTPS with one HTTP client, a timeout of 30 seconds per request and a check of the status and the content type of every answer.
- Errors are wrapped and typed, so
errors.Isanderrors.Astell a missing player, an empty text, an unexpected answer of the speech service and a done context apart (#14). - The native player opens the sound card once per process, at the sample rate of the first MP3, and reuses it.
Removed
- The
handlerspackage:handlers.PlayerInterface,handlers.MPlayerandhandlers.Native.player.Player,player.MPlayer()andnative.New()take their place. Speech.CreateSpeechFile,Speech.CreateSpeechBuffandSpeech.PlaySpeechFile.Save,Synthesize,OpenandPlayFiletake their place.- The
Folder,Language,ProxyandHandlerfields ofSpeech. - The dependency of the root package on the audio library: a program that only saves or synthesizes speech links no audio library, and the whole module builds with
CGO_ENABLED=0, so building in Docker and on machines without ALSA headers works (#15, #27, #33). - The
V1.0tag, a duplicate ofv1.0that brokego geton case-insensitive file systems (#35), is removed with this release.
Fixed
- Text longer than about a hundred characters: the Google engine splits it at sentence and clause boundaries and fetches the pieces one after the other, so long text no longer comes back as an HTML error page saved as
.mp3(#10). The OpenAI engine splits at 4096 characters. - The native player crashed on the second playback in a process (#31).
CreateSpeechBuffreturned a drained reader; its replacementsSynthesizeandOpenreturn the audio.- The last character of a text was dropped when its length was one more than a multiple of 32.
- A failed download left a half-written file in the cache; files are now written atomically and appear only once complete.
- The HTTP status and content type of the endpoint’s answer were not checked, so error pages were saved as audio (#14).
- The Google engine’s proxy requests went out without TLS verification.
- Cache paths are built with
filepath.Join, so a folder with a trailing separator and Windows paths work. - mplayer was run with
-cache 8092 - <file>, where-meant an unused standard input; it now reads the audio from standard input.
1.6 - 2024-09-12
The last release of the v1 API, which added chunked CreateSpeechBuff output for longer text (#32). v1 stays available from this release, tagged v1.6.0 for go get because the v1.6 tag is not a semantic version that Go resolves, and from the v1 branch, which is for critical fixes only.