Metadata-Version: 2.5
Name: echoact
Version: 0.1.2
Summary: Local Korean/English speech generation for the desktop
Project-URL: Homepage, https://github.com/ZeroAct/echo-act
Project-URL: Issues, https://github.com/ZeroAct/echo-act/issues
Author-email: "Huijae Lee (ZeroAct)" <lhj56822@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Huijae Lee
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: english,korean,local,offline,speech,text-to-speech,tts
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: MacOS X
Classifier: Environment :: Win32 (MS Windows)
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: <3.13,>=3.12
Requires-Dist: fastapi>=0.115
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Requires-Dist: onnxruntime>=1.20
Requires-Dist: psutil>=6.0
Requires-Dist: pydantic>=2.9
Requires-Dist: pyside6>=6.8
Requires-Dist: python-multipart>=0.0.12
Requires-Dist: sounddevice>=0.5
Requires-Dist: soundfile>=0.12
Requires-Dist: supertonic==1.3.1
Requires-Dist: uvicorn>=0.32
Description-Content-Type: text/markdown

# EchoAct

EchoAct reads Korean and English text aloud on your own computer. Nothing you
type is sent anywhere: the model runs on your CPU, and once it is downloaded
the app works with no network connection at all.

- **Read a document, follow along.** The sentence being played is marked on
  screen. The mark is drawn as an outline around the letters rather than as a
  heavier weight, so the text never shifts under you while you read.
- **Playback starts before generation finishes.** The first sentence is spoken
  as soon as it is ready, and the rest follows.
- **It stays out of the way.** You choose how much processor and memory the app
  may use, and it stays inside that while you work on something else.
- **Automations can use it too.** A local HTTP service on the loopback address,
  and an MCP server for tools that speak that protocol. Both are the same
  engine, the same limits, and the same one job at a time.

Windows 11 and macOS 14 (Apple Silicon). No Python, Node, or database server
to install.

## Run it with one command

With [uv](https://docs.astral.sh/uv/) installed, no checkout or venv needed:

```
uvx echoact
```

uv fetches EchoAct into an isolated environment and starts the app. The MCP
server is the same package: `uvx --from echoact echoact-mcp`.

## Running it from a checkout

```
uv sync
uv run python -m echoact
```

The first launch offers to download the speech model (about 385 MB) and shows
its licence terms before it does. Generation works offline afterwards.

## Local service

The service is on by default and listens only on `127.0.0.1:8765`. It always
requires a credential; one is created for you on first launch and is shown in
the app under Settings. It cannot be reached from another machine, and there
is no way to configure it to be.

Turn it off in Settings if you do not want it. The app, generation, playback
and the library all work exactly the same with it off.

| | |
| --- | --- |
| Base | `http://127.0.0.1:8765/api/v1` |
| Auth | `Authorization: Bearer <credential>` |
| Discovery | `GET /status`, `GET /models` |
| Before committing | `POST /estimate` — validates, counts segments, estimates length, says whether the slot is free |
| Generate | `POST /jobs` — needs a duplicate-prevention key; may ask to wait up to 10 s |
| Follow | `GET /jobs/{id}`, `GET /jobs/{id}/segments`, `POST /jobs/{id}/cancel` |
| Collect | `GET /jobs/{id}/audio`, `GET /jobs/{id}/result` |

One generation runs at a time across the app and every client, so a second
request is refused with a retry-after hint rather than queued.

## MCP

Off by default; enable it in Settings. The MCP server is a small process your
MCP client starts, which talks to the local service over loopback with a
credential you issue for it. It adds nothing the HTTP service does not already
do, and its permissions are exactly that credential's.

**Connect an app** in the header writes the configuration for you: a tab each
for Claude Desktop, Claude Code, Codex CLI, VS Code and Cursor, with the right
key name and file path for each, the command this particular installation
actually uses, and a Copy button. Issue a credential from that screen and it
goes straight into the snippet — the only moment it can, since the app keeps
only a verifier.

Tools: `list_models`, `estimate_speech`, `create_speech`, `get_speech_job`,
`cancel_speech_job`, `list_speech_segments`, `get_speech_result`,
`list_speech_history`.

## Your data

Documents and generation history are saved only when you ask. Results from a
one-off job are cleaned up when they are replaced or when the app exits, and a
result produced for an integration stays retrievable for an hour. Logs contain
no text and no audio. Nothing is uploaded, and there is no telemetry.

## Repository

```
docs/design.md    The requirements baseline. Every behaviour traces to an
                  identifier in it; Appendix A records what was measured.
echoact/          The application.
spikes/           Standalone measurements that settled open questions.
tests/            pytest. `-m engine` needs the model; the rest does not.
```

`CLAUDE.md` is the contributor's short version.

## Author

Huijae Lee (ZeroAct) — lhj56822@gmail.com — [github.com/ZeroAct](https://github.com/ZeroAct)

## Licence

The application code is MIT (see `LICENSE`). The speech model is downloaded
separately and carries its own licence with use restrictions, which the app
presents for acceptance before it prepares the model for the first time. Being
able to run it locally is not a right to redistribute it.
