echoact 0.1.0__tar.gz

echoact-0.1.0/.gitignore

@@ -0,0 +1,225 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Spike render output
+spikes/_out/
+
+# Fetched by scripts/fetch_fonts.py, not committed: a checkout should not
+# acquire a third-party licence obligation as a side effect of cloning.
+echoact/assets/fonts/

echoact-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

echoact-0.1.0/CLAUDE.md

@@ -0,0 +1,95 @@
+# EchoAct — working notes for contributors
+
+EchoAct generates Korean and English speech from text, entirely on the user's
+PC. `docs/design.md` is the requirements baseline and the only authority: every
+behaviour traces to an `F-`, `N-`, or `A-` identifier there. Appendix A is a
+non-normative planning note; A.2 records the chosen stack and build order, A.3
+records decisions that must not be reopened, A.5 records what was measured.
+
+## Where things live
+
+```
+echoact/
+  errors.py      Code enum + EchoActError. The ONLY exception crossing a module boundary.
+  policy.py      Every number Section 4 fixes. Never hard-code a limit elsewhere.
+  domain.py      Job/Segment/Result/Document, states, VoiceSettings, Budget, TextRange.
+  paths.py       Every on-disk location, plus redact() for logs.
+  config/        Persisted settings (F-24), resource budget resolution (F-20/21/23, N-04).
+  models/        F-84 manifest, download/verify/repair (F-63..F-65).
+  text/          F-81 segmentation, F-27 normalisation-with-alignment, file sniffing (F-32..F-35).
+  engine/        F-87 runtime pinning, worker child process, OS resource container (N-03).
+  jobs/          Single-slot job engine (F-47), dedup keys (F-49), estimates (F-88).
+  audio/         F-82 WAV, PortAudio player with a frame clock (N-12), devices (F-67).
+  db/            SQLite WAL store, backup/restore (F-44, N-27).
+  security/      Credentials (F-71), scopes (F-61), rate limits (4.1).
+  service/       FastAPI, the 12 endpoints in Section 2.10.
+  mcp/           FastMCP stdio server — a REST client, nothing more (F-58).
+  ui/            PySide6 widgets.
+tests/           pytest. Mirror the package layout: tests/text/test_segment.py etc.
+```
+
+## Rules that are not negotiable
+
+1. **No number without a home.** Limits, timeouts, defaults, and sizes come
+   from `echoact.policy`. If a value is missing there, add it there.
+2. **Text offsets are Unicode code points**, half-open, into the job's *source*
+   text — never into normalised text, never UTF-16. Qt counts UTF-16; convert
+   at the widget boundary and nowhere else (4.2, F-27).
+3. **One exception type.** Raise `EchoActError(Code.X, ...)` outward. Do not
+   let `sqlite3.Error`, `OSError`, or an engine exception escape a module.
+4. **The engine never sees a path or a URL from a client** (N-18). Text a user
+   or client supplies is data; it can never reach a style, a voice, or a
+   provider selection.
+5. **Local CPU only, by allow-list** (F-87, N-01). The installed ONNX Runtime
+   offers `AzureExecutionProvider` — this is measured, not hypothetical. Assert
+   the session's providers after construction and refuse otherwise.
+6. **No body text, audio, or credential in a log** (N-20). Log a job id, a
+   stage, a code, and a redacted path.
+7. **Never block the Qt main thread.** The engine, the database, and the
+   service run off it; the GUI touches widgets only from the main thread.
+8. **A retryable error carries a retry-after hint; a permanent one must not**
+   (F-57, N-23).
+
+## Style
+
+- Python 3.12, `from __future__ import annotations`, full type hints, `ruff`
+  clean at line-length 100.
+- Prefer `dataclass(frozen=True, slots=True)` for values, plain classes for
+  things with a lifecycle.
+- Docstrings say *which requirement* the code answers and *why the obvious
+  alternative is wrong*, when that is not evident. Do not restate the code.
+- Comments are sparse and load-bearing. No section banners in short files, no
+  "# increment counter".
+- Tests are named for the behaviour, not the function:
+  `test_first_segment_is_capped_so_playback_starts_sooner`.
+
+## Running things
+
+```
+uv run python -m echoact          # the app
+uv run pytest -q                  # tests
+uv run ruff check echoact tests   # lint
+```
+
+The Supertonic 3 weights are already cached at `~/.cache/supertonic3`
+(revision `724fb5abbf5502583fb520898d45929e62f02c0b`, 385 MB). Tests that need
+the real engine must be marked `@pytest.mark.engine` and skipped when the
+weights are absent; everything else runs without them.
+
+## Engine facts worth knowing before you touch `engine/`
+
+Measured in `spikes/`, recorded in A.5:
+
+- Supertonic 3: 44,100 Hz mono, ten voices `M1`–`M5` / `F1`–`F5`, warm load
+  0.8 s, real-time factor 0.18–0.21 at two threads.
+- **More threads is slower.** Twenty threads ran ~2× slower than two.
+- `synthesize(silence_duration=...)` does nothing once we chunk text ourselves.
+  Inter-segment silence is the app's own to insert (F-82). Pass a large
+  `max_chunk_length` so one of our segments is exactly one engine call —
+  otherwise the engine re-chunks Korean at 120 characters and our segment time
+  ranges stop being exactly known.
+- Identical settings do **not** reproduce identical audio (max sample delta
+  0.47 on a ±1.0 signal). Nothing may assume a regenerated result matches a
+  stored one (F-41).
+- The engine vocalises emoji (three emoji → 1.32 s of audio). A.3 decided they
+  are not sent for synthesis; their source ranges attach to a neighbour.

echoact-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

echoact-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.5
+Name: echoact
+Version: 0.1.0
+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.

echoact-0.1.0/README.md

@@ -0,0 +1,111 @@
+# 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.