MsEdgeTTS: Azure Speech Synthesis Through the Edge Read Aloud Endpoint

What MsEdgeTTS Is Actually Talking To

MsEdgeTTS does not call the Azure Speech Service with your subscription key. It calls the same Read Aloud endpoint that the Microsoft Edge browser uses when a user asks it to read a page aloud. The package.json describes it as "An Azure Speech Service module that uses the Microsoft Edge Read Aloud API", and the README calls it "A simple Azure Speech Service module". The distinction matters: there is no key, no region, no resource to provision, and no invoice. The voice catalogue is whatever the Edge endpoint exposes, which is why the README links to the Edge voice list rather than to an Azure pricing page.

That is the whole value proposition, and it is also the whole risk. You are depending on an endpoint that Microsoft runs for its own browser, not one it documents as a public API for third parties. In December 2025 the README recorded exactly that kind of change: the Read Aloud API began requiring a user agent matching the Microsoft Edge browser, which means it no longer works from browsers other than Edge. Server-side runtimes were unaffected. A library that depends on an undocumented endpoint will keep absorbing changes like that one, and this release is the evidence.

The MsEdgeTTS Architecture: HTTP Metadata, WebSocket Audio

The package is written in TypeScript and ships from a src/ directory compiled with tsc. Its dependencies tell you the shape of the data flow: axios for HTTP, ws and isomorphic-ws for the socket, buffer and stream-browserify for binary handling. The object model is small. You construct an MsEdgeTTS instance, call setMetadata with a voice name and an output format, then call toStream or toFile with the text.

setMetadata is where the voice and format are resolved, and it is asynchronous, which is why every example awaits it. The README states the library "only supports promises", so there is no callback API to fall back on. Audio arrives as a Node stream from toStream, or is written into a directory by toFile, which returns an audioFilePath. When word or sentence boundaries are enabled, a second stream carries JSON metadata: the README's sample shows a Metadata array whose entries have a Type of SentenceBoundary and a Data object containing Offset, Duration and a text object with Text, Length and BoundaryType. That is the mechanism you would use to highlight words as they are spoken.

One structural constraint is visible in package.json: a preinstall script runs npx only-allow pnpm. If you install the repository itself with npm or yarn, that script will stop you. The published package on npm is a normal dependency and is not affected by this, but anyone cloning the source to build it should expect pnpm.

Installing msedge-tts and Synthesizing Your First File

The README points to the npm package msedge-tts, and package.json sets engines.node to >=16.0.0, so the runtime floor is Node 16. Install it as a normal dependency:

npm install msedge-tts

The README's file example is the shortest path to a real artifact. It creates an MsEdgeTTS instance, awaits setMetadata with a voice and a format, then awaits toFile with a folder and the text. Note that the README's own snippet destructures audioFilePath but never uses it, so the useful thing to log is that path:

import {MsEdgeTTS, OUTPUT_FORMAT} from "msedge-tts";

(async () => {
    const tts = new MsEdgeTTS();
    await tts.setMetadata("en-US-AriaNeural", OUTPUT_FORMAT.WEBM_24KHZ_16BIT_MONO_OPUS);
    const {audioFilePath} = await tts.toFile("./tmpfolder", "Hi, how are you?");
    console.log(audioFilePath);
})();

After the promise resolves, the folder you passed contains the synthesized audio and audioFilePath points at it. The format constant WEBM_24KHZ_16BIT_MONO_OPUS comes from the package's Output module, and the README says all supported formats are listed in src/Output.ts. If you want to adjust delivery, the third argument to toStream takes rate and pitch:

const {audioStream} = await tts.toStream("Hi, how are you?", {rate: 0.5, pitch: "+200Hz"});

The README also gives a proxy example using SocksProxyAgent passed into the constructor, which is the escape hatch when the endpoint is not reachable directly. One warning is stated in the README in bold: escape or sanitize user input, and it suggests a library like xml-escape. That is not optional advice. The text you pass is interpolated into an SSML template, and the template is shown in the README with the input dropped straight into a prosody element.

SSML Support in MsEdgeTTS Stops at Three Elements

The README crosses out its own claim about full SSML support. What remains is speak, voice and prosody. The default template is fixed: a speak root with the Microsoft speech namespace, a voice element named from your metadata call, a prosody element carrying rate, pitch and volume, and your text inside it. You cannot inject break, say-as, phoneme, lexicon or mstts:express-as through the public surface described here, because the library builds the wrapper itself.

For plain narration this is enough. For anything that needs pronunciation control, custom lexicons, or expressive styles, it is a hard ceiling, and it is the clearest reason to pick a different tool. The README does not document a way to supply your own SSML document, so treat the template as the contract. The same section of the README also links to Microsoft's speech-synthesis-markup documentation for the format, but linking to the specification is not the same as implementing it, and the strikethrough is the honest signal.

Where MsEdgeTTS Breaks: Browsers, Input, and Upstream Changes

Three failure modes are worth naming before you commit. The first is the browser restriction from December 2025: the Read Aloud API now requires an Edge user agent, so synthesis from any other browser will not work. The README is explicit that server-side runtimes are unaffected, which means this library is effectively a backend tool now. If your plan was client-side speech in a Chrome tab, the plan is dead.

The second is input injection. Because your string is placed inside XML, unescaped angle brackets or ampersands from user content can break the request or alter the markup. The README's instruction to escape or sanitize is the only mitigation it offers, and it points at xml-escape rather than shipping a helper. That is a design choice with a cost: every caller must remember it.

The third is upstream drift. Nothing in this repository controls the Edge endpoint. When Microsoft changes authentication, headers or voice availability, the fix lands here only after someone notices. The last push to the repository was on 2026-07-09, so the project is not abandoned, but the dependency it wraps is not governed by any agreement between you and Microsoft. Budget for the possibility that a deploy fails for reasons outside your codebase.

edge-tts and Python Clients Compared to MsEdgeTTS

The same Edge Read Aloud endpoint is reached by other clients, and the related searches around this project include edge-tts and edge-tts-universal. The difference is ecosystem, not protocol. edge-tts is a Python command line tool and library; MsEdgeTTS is a TypeScript module published to npm, meant to be imported into a Node process. If your pipeline is a Python script or a shell job, a Python client is a shorter path than standing up a Node runtime just for speech. If your service is already Node and you want to call toStream inside an existing request handler, MsEdgeTTS fits without a subprocess.

The second difference is the API surface. MsEdgeTTS exposes a promise-based object with setMetadata, toStream and toFile, plus boundary metadata when you enable it. A command line tool exposes flags and writes a file. Boundary metadata is the feature that is awkward to replicate from a shell: the README's JSON output gives Offset, Duration and the matched text per sentence, which is what a read-along UI needs. If you only need a wav file from a string, the shell tool is simpler. If you need timings inside a running application, the library is the better fit.

Licence, Maintenance, and What an Upgrade Costs You

The repository is MIT licensed, and package.json repeats "license": "MIT". For most teams that means you can use, modify and redistribute the code, including in closed products, provided the copyright notice and permission notice travel with it. That is a general description of the MIT terms, not legal advice; check the LICENSE file at the repository root for the exact text and have counsel review it if your organisation requires that.

The maintenance picture is narrow. There are no releases retrieved for this repository, so version history is read from package.json, which currently declares 2.0.7. The last push was on 2026-07-09. The repository is not archived. The upgrade cost is low in dependency terms: axios, ws, isomorphic-ws, buffer and stream-browserify are ordinary packages, and Node 16 or newer is the only runtime requirement. The real upgrade cost is behavioural. A new version can change the accepted voice names, the output format constants, or the handling of the Edge user agent, and none of that is under your control. Pin the version in package.json and test synthesis after every bump rather than trusting a semver range.

Editorial conclusion

Adopt MsEdgeTTS if you need a no-key, server-side text-to-speech path in a Node 16+ project and can accept that the upstream Read Aloud endpoint is undocumented and has already changed once, in December 2025, when it began requiring an Edge user agent. Do not adopt it if you need SSML beyond speak, voice and prosody, if you need a contractual SLA, or if you intend to run synthesis in a browser other than Edge. Before committing, verify three things: that your chosen voice name is accepted by setMetadata, that the OUTPUT_FORMAT you pick is one of the formats listed in src/Output.ts, and that your runtime can reach the endpoint from wherever the process is hosted.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Migushthe2nd/MsEdgeTTS on GitHub
4. Project website
5. README