ps/Saiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add local pipx installation instructions

Browse Source
This commit is contained in:
ps
2026-10-02 08:23:26 -04:00
parent 43a6b7d93d
commit 01fc6c3a26
1 changed files with 102 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+102 -17
View File
@@ -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.