# VOICEVOX Editor: Building the Desktop App Behind the Japanese Text-to-Speech Tool

> The repository is the Electron editor for VOICEVOX, not the synthesis engine. It is aimed at contributors and at developers who want to run the editor against a separately installed engine, and its setup depends on pointing VITE_DEFAULT_ENGINE_INFOS at a real vv-engine binary.

**VOICEVOX/voicevox** — 無料で使える中品質なテキスト読み上げソフトウェア、VOICEVOXのエディター

- Repository: https://github.com/VOICEVOX/voicevox
- Website: https://voicevox.hiroshiba.jp/
- Stars: 3,255 · Forks: 375
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/voicevox-voicevox

## What the VOICEVOX editor repository actually contains

This is not the synthesis software. The README opens by saying so: VOICEVOX's editor, with the engine in VOICEVOX ENGINE and the core in VOICEVOX CORE, and the overall structure described in docs/全体構成.md. That split matters more than any feature list. The repository you are looking at is a TypeScript and Electron front end, built with Vue and Vuex, whose job is to present text, speakers and audio controls and then hand work to an engine process.

The README addresses two audiences and is explicit that ordinary users are not one of them. There is a section for users that redirects to the official site for usage instructions, and a section for people who want to contribute. So the practical audience here is narrow: contributors, and developers who want the editor running against an engine they installed themselves. If you arrived looking for a download link, the repository is the wrong page.

One consequence of that split is that the editor alone cannot speak. Everything about voice quality, speaker selection and synthesis lives on the engine side, and this repository only decides how those capabilities are exposed. Judging the editor on how the voices sound would be judging a different project.

## How the editor talks to a local engine over HTTP

The mechanism is visible in .env.example. A single environment variable, VITE_DEFAULT_ENGINE_INFOS, holds a JSON array of engine entries. Each entry carries a uuid, a name, executionEnabled, executionFilePath, executionArgs and host. In the example, host is http://127.0.0.1:50021, which is the engine API endpoint the editor will call.

The execution fields describe process management rather than networking. When executionEnabled is true, the editor is expected to launch the binary named in executionFilePath itself, passing executionArgs. When you already run the engine API separately, the README says you do not need executionFilePath, but you must set executionEnabled to false instead. The same rule applies when the packaged VOICEVOX application is already running.

That gives two operating modes with different failure characteristics. In managed mode the editor owns the engine lifecycle, so a wrong path produces a launch failure. In external mode the editor only knows a host, so a wrong port or a stopped server produces connection failures instead. The README does not document what the interface shows in either case, and it does not describe rollback or recovery behavior when an engine dies mid-session.

## Installing the toolchain and starting the editor for the first time

The README's environment section starts with Node.js: install the version recorded in .node-version, and it suggests a version manager such as nvs or nvm so switching is automatic. package.json narrows this further with an engines field of >=24.11.1 <25, and declares pnpm@10.28.2 as the package manager. Then fork the repository and clone it.

Dependencies come from pnpm. The README gives the global install as a one-time step and then the workspace install:

```bash
npm i -g pnpm # 初回のみ
pnpm i
```

Before the editor can synthesize anything, the engine has to exist. Copy .env.example to .env and edit the executionFilePath inside VITE_DEFAULT_ENGINE_INFOS. On Windows with the default install location the README names %LOCALAPPDATA%/Programs/VOICEVOX/vv-engine/run.exe and warns that path separators must be forward slashes, not backslashes. On macOS with VOICEVOX.app the value is /path/to/VOICEVOX.app/Contents/Resources/vv-engine/run. On Linux, take vv-engine/run from the tar.gz release, or mount the AppImage filesystem with $ /path/to/VOICEVOX.AppImage --appimage-mount.

With the engine path in place, the development run is one command:

```bash
pnpm run electron:serve
```

The README also lists pnpm run electron:serve --mode production for a run closer to a build, and pnpm run electron:serve -- ... when you need to pass arguments through. The same section points at the engine repository, VOICEVOX/voicevox_engine, if you need to build the engine yourself. There is also an optional one-liner, pnpm run setup-agents, which the README says sets up files for AI agents such as Codex CLI and Claude Code.

## Where the setup breaks and when this repository is the wrong choice

The most common failure is a missing or wrong engine path. The README's instructions are platform-specific and unforgiving about the separator on Windows, which is the kind of detail people skim. If you point executionFilePath at something that is not a runnable engine and leave executionEnabled true, the editor has no backend.

The second failure mode is a mismatch between mode and reality. Running the packaged VOICEVOX application while the editor is also configured to launch its own engine is exactly the case the README calls out: set executionEnabled to false. Forgetting this leaves two processes competing for the same endpoint.

Beyond setup, the browser build is explicitly unfinished. The README labels it 開発中, in development, and notes that you still have to start the synthesis engine separately on your local machine. The main-branch build is deployed to VOICEVOX/preview-pages, but that is a preview, not a hosted product. If your goal is a browser-based speech tool with no local process, this repository does not give you one today.

Finally, if you have no intention of touching the code, cloning is wasted effort. The README states plainly that usage instructions live on the official site. The editor is a means to contribute or to integrate, not a distribution channel.

## Testing and build workflow, and what it costs to keep up

The repository is heavier on verification than a typical Electron app. Unit tests run through Vitest with pnpm run test:unit, plus watch and UI variants. The README notes that the environment for files under ./tests/unit is chosen by filename: .node.spec.ts runs in Node.js, .browser.spec.ts in Chromium, and .spec.ts in a browser environment emulated by happy-dom.

End-to-end coverage is split by whether Electron features are needed. Browser E2E uses Playwright via pnpm run test:browser-e2e, and the README confirms Playwright is the basis for the generator command pnpm exec playwright codegen http://localhost:5173/ --viewport-size=1024,630, which requires the browser version already running. Electron E2E covers engine start and stop through pnpm run test:electron-e2e.

Visual regression is the awkward part. Storybook VRT compares component screenshots, and the README states this test can only run on Windows. Snapshot updates can go through a GitHub Actions workflow dispatch with update_snapshots=true, or locally with pnpm run test:browser-e2e --update-snapshots, which the README says updates only the snapshots matching your local operating system. That Windows-only constraint is a real cost for anyone on macOS or Linux who touches shared UI components.

Builds are pnpm run electron:build locally, or the build.yml workflow run by workflow_dispatch on a fork with Actions enabled, which uploads artifacts to a Release. The repository also carries tooling for dependency licence reporting: pnpm run license:generate -o voicevox_licenses.json and pnpm run license:merge. The licence of the repository itself is reported as NOASSERTION by the host, so read LICENSE and LGPL_LICENSE in the tree rather than assuming terms. This is a description of what the files say, not legal advice.

## How the editor relates to other singing and speech tools

The comparison worth making is with UTAU. UTAU is a voice-synthesis editor built around user-recorded voicebanks and a long-standing community format, and its workflow centres on importing and tuning those banks inside the editor itself. VOICEVOX separates the concerns: the editor here is a client, and the voices come from an engine reached over HTTP at a host such as http://127.0.0.1:50021. If you want to swap voices, you change what the engine offers, not what the editor contains.

That architecture is also why questions about using VOICEVOX inside other editors are really questions about the engine, not this repository. The README points to VOICEVOX ENGINE as the synthesis repository, and that is the component other software would integrate with. This repository's contribution is the desktop interface: the Electron shell, the Vue component tree, the Storybook catalogue and the Playwright suites that keep the UI honest.

So the honest framing is that the editor is the visible half of a two-part system, and the interesting engineering decisions about audio are made in the other half. Judging this repository means judging process management, configuration and UI testing, which is exactly what its README spends its length on.

## Conclusion

Adopt this repository if you are contributing to the VOICEVOX editor or need to run its Electron shell against an engine you control; skip it if you only want a working speech tool, since the README sends users to the official site instead. Before cloning, check the Node.js range in package.json (>=24.11.1 <25) and confirm you have a vv-engine binary, because without executionFilePath or a separately running engine the editor has nothing to talk to.

## FAQ

### What is VOICEVOX?

VOICEVOX is a text-to-speech system whose editor is this repository. The README separates it into three parts: the editor here, the engine in VOICEVOX ENGINE, and the core in VOICEVOX CORE.

### How do I install VOICEVOX from this repository?

Install the Node.js version recorded in .node-version, run npm i -g pnpm once and then pnpm i, copy .env.example to .env, and point executionFilePath in VITE_DEFAULT_ENGINE_INFOS at a vv-engine binary. Then start the editor with pnpm run electron:serve.

### Is VOICEVOX free?

The repository's licence is reported by the host as NOASSERTION, and the tree contains LICENSE and LGPL_LICENSE files, so the terms are not something to infer from the README. The README itself does not state a price for the software.

### Does VOICEVOX support English?

The README of this repository does not describe language support; it documents the editor's setup, run, build and test commands. Language behaviour belongs to the engine, which the README links as VOICEVOX ENGINE.

### Does VOICEVOX use AI?

The README of this repository does not describe how synthesis works internally; it documents the editor's setup, run, build and test commands. The synthesis component is the engine, linked in the README as VOICEVOX ENGINE.

## Sources

- [Issues](https://github.com/VOICEVOX/voicevox/issues)
- [Project website](https://voicevox.hiroshiba.jp/)
- [README](https://github.com/VOICEVOX/voicevox/blob/main/README.md)
- [Releases](https://github.com/VOICEVOX/voicevox/releases)
- [VOICEVOX/voicevox on GitHub](https://github.com/VOICEVOX/voicevox)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/voicevox-voicevox