4.0.0-beta.1 UI and Engine Overhaul

.env.example

@@ -0,0 +1,10 @@
+# Copy this file to .env and fill in the values you need. .env itself is
+# gitignored - never commit it.
+
+# Folder of an unzipped Vosk speech-recognition model (download one from
+# https://alphacephei.com/vosk/models, e.g. vosk-model-small-en-us-0.15),
+# used by the Voice Reference dock's "Vosk" auto-transcription engine
+# (kokoro_gui/engine/asr.py). Leave unset if you're only using the default
+# Audio8-ASR-0.1B engine. You can also set/edit this from the dock itself
+# (Browse/Save/Reload next to the Vosk model field) instead of by hand.
+VOSK_MODEL_PATH=

.gitattributes

@@ -0,0 +1,16 @@
+# Normalize line endings: LF in the repo and on checkout, on every OS.
+* text=auto eol=lf
+
+# Windows launcher needs CRLF for cmd.exe.
+*.bat text eol=crlf
+
+# Binary assets, never touched by the text filters.
+*.png binary
+*.jpg binary
+*.gif binary
+*.wav binary
+*.flac binary
+*.mp3 binary
+*.ogg binary
+*.pt binary
+*.tbaw binary

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,80 @@
+name: Bug report
+description: Something crashed, sounded wrong, or didn't do what the docs say.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Installation questions and "how do I" belong in Discussions. This form is for things that are broken.
+  - type: input
+    id: version
+    attributes:
+      label: KokoroGUI version
+      description: The "New in" heading at the top of the README, or `kokoro_gui/__init__.py`'s `APP_VERSION`.
+      placeholder: "4.0.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Windows
+        - Linux
+        - macOS
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.11.9 (python --version)"
+    validations:
+      required: true
+  - type: dropdown
+    id: engine
+    attributes:
+      label: Engine (Options > Engine)
+      options:
+        - Kokoro
+        - Audio8
+        - Dummy
+        - Not engine-related
+    validations:
+      required: true
+  - type: input
+    id: device
+    attributes:
+      label: Device
+      description: Options > Device, plus the GPU if any.
+      placeholder: "cuda, RTX 3060 / cpu"
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: What you clicked or typed, in order. If a specific text triggers it, paste the text (or the smallest part that still does).
+      placeholder: |
+        1. New project, paste "[Narrator]: Hello."
+        2. Generate
+        3. ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected, and what happened instead
+    validations:
+      required: true
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Traceback or log
+      description: The terminal output from `python main.py`, if any. Pasted as text, not a screenshot.
+      render: text
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I ran `pip install -r requirements.txt` on this version before reporting.
+        - label: The `.tbaw` or text that triggers this is something I can share if asked.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions and help
+    url: https://github.com/CoffeeMethod/KokoroGUI/discussions
+    about: Install trouble, "how do I", model and hardware questions.
+  - name: Security issue
+    url: https://github.com/CoffeeMethod/KokoroGUI/security/advisories/new
+    about: Report privately. See SECURITY.md.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,29 @@
+name: Feature request
+description: Something the app should do that it doesn't.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What are you trying to do?
+      description: The task, not the button. "Make a two-voice audiobook from an EPUB with chapter breaks" tells us more than "add a chapter button".
+    validations:
+      required: true
+  - type: textarea
+    id: today
+    attributes:
+      label: How do you do it today?
+      description: The workaround, or "can't".
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like instead?
+      description: Optional. If you have a specific design in mind, describe it; if not, the first two answers are enough.
+  - type: dropdown
+    id: engine
+    attributes:
+      label: Engine, if it matters
+      options:
+        - Any
+        - Kokoro
+        - Audio8

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## What
+
+<!-- One or two sentences. What changes for a user, or for a developer if it's internal. -->
+
+## Why
+
+<!-- The bug or gap. Link the issue if there is one. -->
+
+## How to check it
+
+<!-- What you ran or clicked. `pytest` output counts; a screenshot for anything visual. -->
+
+## Checklist
+
+- [ ] `pytest` passes locally (the fast suite; CI runs it on Windows and Linux)
+- [ ] New settings are threaded through `_assemble_config` and `tests/gui_qt/test_qt_config_assembly.py`
+- [ ] README's Features list and "New in" section updated if a user can see the change

.github/workflows/tests.yml

@@ -5,14 +5,24 @@ on:
     branches: [main]
   pull_request:
 
+# The token only ever reads the checkout; nothing here pushes or comments.
+permissions:
+  contents: read
+
+# A new push to the same branch/PR cancels the run it supersedes.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
-    # Playback goes through playback.py (sounddevice/PortAudio) instead of
-    # the Windows-only `winsound` module, so kokoro_engine.py/gui.py no
-    # longer force Windows-only. ubuntu-latest additionally needs:
-    #   - libportaudio2 (system PortAudio lib `sounddevice` dlopens)
-    #   - Xvfb (the GUI suite builds real Tk windows - tests/conftest.py's
-    #     `tts_app` fixture - which needs a display on headless Linux)
+    # CI runs the engine, DAW model and audio suites only. tests/gui_qt/
+    # (real QtTTSApp widgets, docks, screenshots) is skipped here and run
+    # locally with a plain `pytest`; it was the flaky half of every failed
+    # run. Nothing collected below imports PySide6.QtGui or QtWidgets
+    # (tests/test_mixer_transport.py needs QtCore only), so the Linux leg
+    # needs no Qt runtime libraries and no QT_QPA_PLATFORM. It still needs
+    # libportaudio2, the system PortAudio library `sounddevice` dlopens.
     # macos-latest is left out for now (unverified) - see ROADMAP.md's
     # "CI expansion" item.
     strategy:
@@ -26,26 +36,34 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+          # torch alone is several hundred MB; keyed on both requirements files.
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            requirements-test.txt
 
-      - name: Install PortAudio + Xvfb (Linux)
+      - name: Install PortAudio (Linux)
         if: runner.os == 'Linux'
-        run: sudo apt-get update && sudo apt-get install -y libportaudio2 xvfb
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libportaudio2
 
       - name: Install dependencies
         run: |
           pip install -r requirements.txt
           pip install -r requirements-test.txt
 
-      - name: Run fast test suite (Linux)
-        if: runner.os == 'Linux'
-        run: xvfb-run -a pytest
-        # Runs the mocked-pipeline suite only (pytest.ini already sets
-        # `-m "not integration"` by default). No eSpeak NG or model
-        # download needed. The real-synthesis integration suite
+      - name: Run non-GUI test suite
+        # -X faulthandler from interpreter start: pytest's own faulthandler
+        # only switches on at pytest_configure, after tests/conftest.py
+        # (and torch, pedalboard with it) has already been imported, so a
+        # native crash during those imports printed nothing.
+        # --ignore=tests/gui_qt leaves the Qt suite out (its conftest builds
+        # the whole app). -p no:pytest-qt keeps the pytest-qt plugin from
+        # importing QtGui/QtWidgets at configure time, which it does even
+        # when no test uses qtbot.
+        run: python -X faulthandler -m pytest --ignore=tests/gui_qt -p no:pytest-qt
+        # pytest.ini already deselects `integration` and `slow`. No eSpeak
+        # NG or model download needed. The real-synthesis integration suite
         # (`pytest -m integration tests/integration`) is intentionally
-        # left out of CI - it's slow and pulls model weights. Wrapped in
-        # xvfb-run so the Tk-based GUI tests have a display to attach to.
-
-      - name: Run fast test suite (Windows)
-        if: runner.os != 'Linux'
-        run: pytest
+        # left out of CI - it's slow and pulls model weights.

.gitignore

@@ -173,3 +173,14 @@ cython_debug/
 /ROADMAP.md
 /CLAUDE.md
 /tests/output/
+/custom_voices/
+/cache/
+/presets/
+/Claude/PLAN_qt_and_engine_abstraction.md
+/generation_stats.json
+/SECURITY_AUDIT.md
+/Claude/
+/.claude/
+document.json
+document.tbaw
+config_qt.json

CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing
+
+Bug reports and pull requests are welcome. Questions go in Discussions, security reports through
+the Security tab (see [SECURITY.md](SECURITY.md)).
+
+## Setup
+
+```bash
+git clone https://github.com/CoffeeMethod/KokoroGUI.git
+cd KokoroGUI
+python -m venv .venv && . .venv/Scripts/activate   # or .venv/bin/activate
+pip install -r requirements.txt -r requirements-test.txt
+python main.py
+```
+
+Python 3.11 or newer. eSpeak NG is only needed to actually synthesize with Kokoro; the fast test
+suite runs without it.
+
+## Tests
+
+```bash
+pytest
+```
+
+That's the fast suite: the Kokoro pipeline is mocked, playback is mocked, no model download, runs
+in well under a minute. The Qt tests run headless (`tests/gui_qt/conftest.py` sets
+`QT_QPA_PLATFORM=offscreen`), so no display is needed. CI runs the suite on `windows-latest` and
+`ubuntu-latest` without `tests/gui_qt/` (`pytest --ignore=tests/gui_qt -p no:pytest-qt`), so the
+GUI tests only run on your machine. Run plain `pytest` before you push.
+
+Two conventions the suite enforces, both from `tests/conftest.py`:
+
+- Test configs come from the `make_config` fixture and have `caching: False`. Only
+  `tests/test_caching.py` turns caching on; `tests/test_meta_caching_policy.py` fails the run if
+  another file does.
+- Tests never touch the real `custom_voices/` or `cache/` directories or a real audio device. Use
+  the `isolated_dirs`, `engine` and `fake_pipeline` fixtures rather than patching around them.
+
+GUI tests build a real `QtTTSApp` through the `qt_app` fixture in `tests/gui_qt/conftest.py`,
+with the engine replaced by `StubEngine`. Save and Open run on a thread; call
+`qt_app.wait_for_project_io()` before asserting on the result.
+
+The integration suite (`pytest -m integration tests/integration -s`) does real synthesis and is
+opt-in. It isn't run in CI.
+
+## Pull requests
+
+- Branch from `main`, one change per PR.
+- `pytest` green locally before you push (that includes `tests/gui_qt/`, which CI skips). CI has
+  to pass on both OSes to merge.
+- A new setting is threaded through `QtTTSApp._assemble_config` and covered in
+  `tests/gui_qt/test_qt_config_assembly.py`.
+- If a user can see the change, update the README: the Features list, and a bullet under the
+  current "New in" heading.
+- No formatter or linter is configured. Match the style of the file you're in.
+
+## Layout
+
+- `kokoro_engine.py` and `kokoro_gui/engine/` are the synthesis core (mixins per feature area).
+- `kokoro_gui/engines/` is the backend interface and the three registered backends (Kokoro,
+  Audio8, Dummy). Nothing there imports the document model.
+- `kokoro_gui/daw/` is the document model: text, clips, tracks, characters, arrangement, dirty
+  tracking, undo.
+- `kokoro_gui/audio/` is the transport, mixer and read-time FX stage.
+- `kokoro_gui/qt/` is the PySide6 shell; every panel is a dock under `kokoro_gui/qt/docks/`.
+- `docs/` is the GitHub Pages site.