vv-synth 0.1.0__tar.gz

vv_synth-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Local environment / secret files
+.env
+.env.*
+
+# macOS metadata
+.DS_Store
+
+# Tool caches
+.ruff_cache/
+
+# VOICEVOX CORE (run ./download in project root)
+download
+voicevox_core/
+
+# VOICEVOX Engine official binaries / extracted distributions
+voicevox_engine*/
+*.7z
+*.7z.*
+*.vvpp
+
+# Artifacts such as synthesized audio (track only .gitkeep)
+output/*
+!output/.gitkeep
+
+# Synthesized audio written anywhere outside output/
+*.wav
+
+# Local agent / editor project metadata
+.serena/
+
+# Claude Code per-user local settings
+.claude/settings.local.json
+
+# Local Claude Code skill copies (canonical skills live in skills/)
+.claude/skills/

vv_synth-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

vv_synth-0.1.0/AGENTS.md

@@ -0,0 +1,53 @@
+# vv-synth — Agent Guide
+
+`vv-synth` is a thin Typer CLI for VOICEVOX Engine: it sends text to a separately prepared
+Engine over HTTP (default `http://127.0.0.1:50021`) and writes a WAV file. Package: `vv-synth`;
+library: `vv_synth/`; entry point: `main:main`. Keep changes small and the CLI thin.
+
+This repository is open source (MIT). Do **not** vendor VOICEVOX Engine, voice libraries,
+model files, binaries, Docker images, or generated WAV files (see
+[`.claude/rules/terms.md`](.claude/rules/terms.md)).
+
+User-facing docs: [`README.md`](README.md) (English; source of truth for the Mermaid diagrams
+and maintenance) and [`README.ja.md`](README.ja.md) (Japanese).
+
+## Recommended agents
+
+Development is set up for **Codex CLI** and **Claude Code**. This `AGENTS.md` is the shared
+entry both read: Codex auto-loads it, and Claude Code reads it via [`CLAUDE.md`](CLAUDE.md).
+Claude Code additionally auto-loads `.claude/rules/*.md` natively — the always-on rules
+(`commit`, `security`, `terms`) every session, and the path-scoped rules when you edit matching
+files; Codex and other agents read them on demand from the index below.
+
+## Rules index
+
+Detailed rules live in [`.claude/rules/`](.claude/rules/). Read the one that matches your change:
+
+| File | Contents |
+|------|----------|
+| [`commit.md`](.claude/rules/commit.md) | Commit message format and prefixes |
+| [`coding.md`](.claude/rules/coding.md) | Python 3.14, ruff/ty, English `--help`, one-line errors |
+| [`architecture.md`](.claude/rules/architecture.md) | Module responsibilities and synthesis flow |
+| [`workflow.md`](.claude/rules/workflow.md) | uv, quality checks, Engine setup, smoke test |
+| [`docs.md`](.claude/rules/docs.md) | README/Mermaid/skills sync, MD placement |
+| [`terms.md`](.claude/rules/terms.md) | VOICEVOX terms, no-vendoring, credit |
+| [`security.md`](.claude/rules/security.md) | Secret files and hardcoding |
+
+## Quick reference
+
+```shell
+uv sync --group dev
+uv run ruff check . && uv run ruff format . && uv run ty check && uv run pytest
+uv run vv-synth "Test"   # Engine must be running on :50021
+```
+
+Global CLI: `uv tool install --editable .`. Engine setup (Docker / Windows GPU / binary) is in
+[README.md](README.md#prepare-voicevox-engine).
+
+## Skills
+
+- [`skills/vv-synth/`](skills/vv-synth/) — portable TTS for other projects
+- [`skills/vv-synth-dev/`](skills/vv-synth-dev/) — developing this repository
+- [`skills/README.md`](skills/README.md) — install and publish
+
+Commit only when the user explicitly asks ([`.claude/rules/commit.md`](.claude/rules/commit.md)).

vv_synth-0.1.0/CLAUDE.md

@@ -0,0 +1,14 @@
+# vv-synth — Claude Code
+
+Claude Code reads this file. The shared agent guide is imported from [`AGENTS.md`](AGENTS.md)
+below; Claude-specific notes follow.
+
+@AGENTS.md
+
+## Claude Code notes
+
+- Claude Code auto-loads [`.claude/rules/`](.claude/rules/) natively: `commit.md`, `security.md`,
+  and `terms.md` every session, and the path-scoped `coding.md` / `architecture.md` /
+  `workflow.md` / `docs.md` when you edit files they target (`paths:` frontmatter).
+- `README.md` is the source of truth for implementation detail and the two Mermaid diagrams.
+- Commit only when the user explicitly asks ([`.claude/rules/commit.md`](.claude/rules/commit.md)).

vv_synth-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to vv-synth
+
+Thanks for your interest in `vv-synth`. It is a thin Typer CLI that sends text to a
+separately prepared VOICEVOX Engine over HTTP and writes a local WAV file. Please keep
+changes small and focused.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](.github/CODE_OF_CONDUCT.md). By participating, you are expected to uphold it.
+
+## Scope and philosophy
+
+- `vv-synth` only talks to the Engine HTTP API (`http://127.0.0.1:50021` by default).
+- Do **not** vendor VOICEVOX Engine, voice libraries, model files, official binaries,
+  Docker images, or generated WAV files. They must never be committed.
+- Prefer editing existing modules over adding new abstractions. Avoid out-of-scope
+  refactors and large test additions unless they are requested.
+
+The runtime logic lives in three files:
+
+| Path | Responsibility |
+|------|----------------|
+| `main.py` | Typer CLI and the `vv-synth` entry point |
+| `vv_synth/engine_client.py` | Engine HTTP calls, speech rate, WAV saving |
+| `vv_synth/output_paths.py` | Output path resolution (`output/`, `-o`, timestamps) |
+
+## Development setup
+
+Requires Python 3.14+ and [uv](https://docs.astral.sh/uv/).
+
+```shell
+uv sync --group dev
+uv run vv-synth --help
+```
+
+Start the VOICEVOX Engine with Docker or an official binary, then confirm it responds:
+
+```shell
+docker run --rm -it -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest
+curl -sSf http://127.0.0.1:50021/version
+```
+
+See [README.md](README.md#prepare-voicevox-engine) for full Engine setup (CPU, Windows GPU,
+official binaries) and troubleshooting.
+
+## Quality checks
+
+Run these before opening a pull request:
+
+```shell
+uv run ruff check .
+uv run ruff format .
+uv run ty check
+uv run pytest
+```
+
+`pytest` runs the suite in `tests/` and does not require a running VOICEVOX Engine
+(network calls are mocked).
+
+Manual smoke test with the Engine running:
+
+```shell
+uv run vv-synth "contribution smoke test"
+ls -la output/
+```
+
+## Coding conventions
+
+- Strict `ruff` (`select = ["ALL"]`) and `ty` settings are defined in `pyproject.toml`.
+- Relative imports are banned; use absolute imports.
+- Keep `vv-synth --help` text in **English**. Japanese user-facing prose belongs in
+  `README.ja.md`.
+- Synthesis errors must be a **single English line** on stderr (exit code 1). Do not expose
+  tracebacks to users.
+- Print `INFO: wrote <absolute-path>` to stdout on success. Argument and option parsing
+  errors use Typer's usage error on stderr (exit code 2).
+- CLI speech rates must be finite numbers from `0.01` to `10.0`.
+- Keep business logic in `vv_synth/`; `main.py` stays CLI-only.
+
+## Documentation sync
+
+When module boundaries, Engine APIs, or the CLI flow change, update the two Mermaid diagrams
+in `README.md` and keep these in sync as needed:
+
+- `README.ja.md` (Japanese user docs)
+- `AGENTS.md` and `CLAUDE.md` (agent guidance)
+- Agent Skills: `skills/vv-synth/SKILL.md`, `skills/vv-synth-dev/SKILL.md`
+
+The full checklist lives in [README.md](README.md#documentation-sync-checklist).
+
+## Commit and pull request style
+
+- Use a single-line English message: `prefix: message`.
+- Prefixes: `feat`, `fix`, `docs`, `chore`, `update`, `refactor`, `test`, `style`.
+- Examples: `feat: add --pitch option`, `docs: update engine setup`.
+- Keep each pull request scoped to one logical change.
+- Never commit `output/*.wav`, `voicevox_core/`, `download`, Engine binaries, models, voice
+  libraries, or virtual environments.
+
+## VOICEVOX terms
+
+Generated audio is subject to the latest official VOICEVOX terms and each voice library /
+speaker's own terms, including credit requirements. Before sharing or redistributing any
+generated audio, confirm the applicable terms. See
+[OSS Publication And VOICEVOX Terms](README.md#oss-publication-and-voicevox-terms).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+[MIT License](LICENSE).

vv_synth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ru-461
+
+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.