From 01fc6c3a26cff6ec7ba10d623a4d7f80b379b978 Mon Sep 17 00:00:00 2001 From: Pawel Sarkowicz Date: Fri, 2 Oct 2026 08:23:26 -0400 Subject: [PATCH] docs: add local pipx installation instructions --- README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 102 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 7a87dac..6946e9d 100644 --- a/README.md +++ b/README.md @@ -17,28 +17,106 @@ saiki --help - Python 3.12+ - [Anki](https://apps.ankiweb.net/) with [AnkiConnect](https://github.com/amikey/anki-connect) - `ffmpeg` -- spaCy models for word mining: +- spaCy models for word mining (install after Saiki, as shown below) -```shell -python -m spacy download es_core_news_sm -python -m spacy download ja_core_news_lg -``` +## Installation -Setup example: +Choose either a virtual environment or a local command-line installation with +pipx. Run the installation commands from the root of this checkout (the directory +containing `pyproject.toml`). + +### Virtual environment ```shell python3.12 -m venv ~/.venv/saiki source ~/.venv/saiki/bin/activate pip install -U pip pip install -e . -sudo dnf install ffmpeg +saiki --help ``` +Activate it with `source ~/.venv/saiki/bin/activate` in each new terminal before +running Saiki. Install `ffmpeg` with your OS package manager (examples below). + +For word mining, install the models for the languages you need inside the +activated environment: + +```shell +python -m spacy download es_core_news_sm +python -m spacy download ja_core_news_lg +``` + +### Install locally (no virtual environment activation) + +Use [pipx](https://github.com/pypa/pipx) to install Saiki as a command-line app. +It manages an isolated Python environment and puts the commands on your `PATH`, +so you can run `saiki` from any directory without sourcing a `.venv`. + +Install pipx and ffmpeg with your OS package manager, for example: + +```shell +# Fedora +sudo dnf install pipx ffmpeg + +# Ubuntu / Debian +sudo apt install pipx ffmpeg + +# macOS (Homebrew) +brew install pipx ffmpeg +``` + +Run the block for your OS, then: + +```shell +pipx ensurepath +``` + +Open a new terminal so the `PATH` change takes effect. From the root of this +checkout (the directory containing `pyproject.toml`), install Saiki: + +```shell +pipx install --python python3.12 --include-deps --editable . +saiki --help +``` + +Python 3.12 must be installed; you can replace `python3.12` with another installed +Python 3.12+ interpreter. Keep this checkout in place: `--editable` makes the +installed command use its source files directly. Omit `--editable` if you prefer +an independent installation that does not depend on keeping the checkout. + +`--include-deps` also exposes dependency commands such as `edge-tts`, `gtts-cli`, +and `spacy`. Saiki invokes the TTS commands as subprocesses, so they must be on +`PATH` too. + +For word mining, install the models using the `spacy` command supplied by this +installation (choose the languages you need): + +```shell +spacy download es_core_news_sm +spacy download ja_core_news_lg +``` + +These install into Saiki's pipx environment. Model downloads are not required for +`saiki import`. If you previously activated a virtual environment, deactivate it +or open a fresh terminal before using this installation. + ### Updating -If you installed with `pip install -e .` (editable mode), changes to the source -are live immediately — no reinstall needed. Only re-run `pip install -e .` if -you pull changes that add new dependencies or scripts. +For the editable pipx installation, source changes take effect immediately. +Pull updates from the checkout root; if dependencies or entry points in +`pyproject.toml` changed, refresh the installation: + +```shell +git pull +pipx install --force --include-deps --editable . +``` + +For a non-editable pipx installation, reinstall after every update, omitting +`--editable`. To remove either installation, run `pipx uninstall saiki`. + +For a development environment installed with `pip install -e .`, source changes +are also live immediately. Activate that environment before running the update +commands; only reinstall if dependencies or scripts changed. ```shell git pull @@ -48,12 +126,19 @@ pip install -e . # only needed if pyproject.toml changed ### Optional TTS Backends The default `edge-tts` backend is included. To install the optional Python-backed -engines (piper, kokoro): +engines (piper, kokoro), run this from the checkout root: ```shell -pip install ".[tts]" +pipx install --force --include-deps --editable ".[tts]" +``` -# System package for espeak-ng. +Keep `".[tts]"` in subsequent reinstall commands to retain these extras. Omit +`--editable` for an independent installation. If using a manually activated +virtual environment instead, run `pip install ".[tts]"` inside it. + +For espeak-ng, install the system package: + +```shell sudo dnf install espeak-ng ``` @@ -66,14 +151,14 @@ sudo pacman -S espeak-ng Backend notes: -- `edge-tts`: installed by `pip install edge-tts`; no API key, but it uses +- `edge-tts`: included in the base installation; no API key, but it uses Microsoft Edge's online TTS service. -- `gtts`: installed by `requirements.txt`; no API key, but it uses Google's +- `gtts`: included in the base installation; no API key, but it uses Google's online TTS service through `gtts-cli`. -- `piper`: installed by `pip install piper-tts`; you still need a compatible +- `piper`: included in the `tts` extra; you still need a compatible `.onnx` voice model, usually with its matching `.onnx.json` config file. - `espeak-ng`: installed through your OS package manager, not pip. -- `kokoro`: installed by `pip install kokoro-onnx soundfile`; you still need +- `kokoro`: included in the `tts` extra; you still need `kokoro-v1.0.onnx` and `voices-v1.0.bin`, plus any language-specific G2P setup required by your Kokoro release.