github-starred/open-webui
2
0
Fork 0
mirror of https://github.com/open-webui/open-webui.git synced 2026-07-15 21:19:39 -05:00
Code Issues 2.4k Packages Projects Releases 129 Wiki Activity

[PR #16036] [CLOSED] feat: KokoroTTS text-to-speech-engine option (decoupled from OpenAI TTS) #127668

New Issue
Closed
opened 2026-05-21 09:42:32 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-05-21 09:42:32 -05:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/open-webui/open-webui/pull/16036
Author: @silentoplayz
Created: 7/26/2025
Status: ❌ Closed

Base: dev ← Head: KokoroTTS-text-to-speech-engine

📝 Commits (9)

  • 3a25512 feat: KokoroTTS text-to-speech-engine option (decoupled from OpenAI TTS option)
  • 60f83f3 remove comments
  • f170ea3 fix: add required for TTS fields to save settings
  • d007819 refac: forward slash (/) support for KokoroTTS Base URL
  • 4bb995c feat: display voice distribution percentages for KokoroTTS voice combinations input
  • 4c88936 refac: validate KokoroTTS custom voice combination input against the actual available voice names fetched from the KokoroTTS API
  • 0536da1 .
  • f09e15b Merge branch 'dev' into KokoroTTS-text-to-speech-engine
  • c96fb20 fix: add back required

📊 Changes

5 files changed (+502 additions, -44 deletions)

View changed files

📝 backend/open_webui/config.py (+8 -0)
📝 backend/open_webui/main.py (+2 -0)
📝 backend/open_webui/routers/audio.py (+122 -8)
📝 src/lib/components/admin/Settings/Audio.svelte (+360 -31)
📝 src/lib/components/chat/Messages/ResponseMessage.svelte (+10 -5)

📄 Description

Pull Request Checklist

Before submitting, make sure you've checked the following:

  • Target branch: Please verify that the pull request targets the dev branch.
  • Description: Provide a concise description of the changes made in this pull request.
  • Changelog: Ensure a changelog entry following the format of Keep a Changelog is added at the bottom of the PR description.
  • Documentation: Have you updated relevant documentation Open WebUI Docs, or other documentation sources?
  • Dependencies: Are there any new dependencies? Have you updated the dependency versions in the documentation?
  • Testing: Have you written and run sufficient tests to validate the changes?
  • Code review: Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards?
  • Prefix: To clearly categorize this pull request, prefix the pull request title using one of the following:
    • BREAKING CHANGE: Significant changes that may affect compatibility
    • build: Changes that affect the build system or external dependencies
    • ci: Changes to our continuous integration processes or workflows
    • chore: Refactor, cleanup, or other non-functional code changes
    • docs: Documentation update or addition
    • feat: Introduces a new feature or enhancement to the codebase
    • fix: Bug fix or error correction
    • i18n: Internationalization or localization changes
    • perf: Performance improvement
    • refactor: Code restructuring for better maintainability, readability, or scalability
    • style: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc.)
    • test: Adding missing tests or correcting existing tests
    • WIP: Work in progress, a temporary label for incomplete or ongoing work

Changelog Entry

Description

  • Adds a new, decoupled KokoroTTS text-to-speech engine option to Open-WebUI, enabling users to use a KokoroTTS endpoint for Open WebUI's text-to-speech engine independently of OpenAI TTS engine. Configuration is driven by the new AUDIO_TTS_KOKORO_API_BASE_URL environment variable (or UI setting) and integrates KokoroTTS model/voice discovery and speech generation throughout the audio pipeline.

Added

  • New KokoroTTS TTS engine (kokoro) selectable in the UI alongside openai, azure, and elevenlabs.
  • Support for fetching KokoroTTS models and voices via /v1/models and /v1/audio/voices endpoints, respectively.
  • Dedicated KokoroTTS speech generation path that POSTs to TTS_KOKORO_API_BASE_URL/v1/audio/speech.
  • Environment variable AUDIO_TTS_KOKORO_API_BASE_URL and corresponding persistent config entry.
  • Cache keys now include TTS_KOKORO_API_BASE_URL to prevent cache collisions when switching engines.
  • UI fields for TTS_KOKORO_API_BASE_URL and an optional TTS_API_KEY for KokoroTTS.
  • Option in the UI to input custom KokoroTTS voice combinations (e.g., af_bella+af_sky or af_bella(2)+af_sky(1)).
  • UI toggle to enable/disable text normalization for KokoroTTS, driven by KOKORO_NORMALIZATION_OPTIONS.normalize in the config.

Changed

  • Updated backend/open_webui/config.py to register AUDIO_TTS_KOKORO_API_BASE_URL.
  • Updated backend/open_webui/main.py to expose TTS_KOKORO_API_BASE_URL to the application state.
  • Extended backend/open_webui/routers/audio.py:
    • Added Kokoro-related fields to TTSConfigForm, get_audio_config, and update_audio_config, including KOKORO_NORMALIZATION_OPTIONS.
    • Added Kokoro branch in /speech endpoint for KokoroTTS requests.
    • Added Kokoro branches in get_available_models and get_voices for dynamic discovery.
  • Audio.svelte (frontend UI):
    • Implemented dynamic fetching and display of KokoroTTS models and voices based on the TTS_ENGINE selection.
    • Introduced a "Custom Combination..." option for KokoroTTS voices, allowing users to input complex voice strings, with client-side validation for empty custom inputs.
    • Added a toggle for "Enable Text Normalization" for KokoroTTS, reflecting the KOKORO_NORMALIZATION_OPTIONS.normalize setting.
    • Modified the voice and model selection logic to clear previously selected values when switching TTS engines, and to set default OpenAI values when selecting the OpenAI engine.
    • Updated voice and model type definitions for better clarity and consistency across different TTS engines.

Fixed

  • Made the API Key for KokoroTTS actually optional. It wasn't before with the OpenAI TTS engine.
  • Ensured that the "TTS Model" and "TTS Voice" fields are now marked as required for all TTS engines that utilize them, including KokoroTTS, to prevent users from leaving these essential settings blank.

Hopefully there aren't any breaking changes. All existing TTS engines remain unchanged and KokoroTTS is an optional text-to-speech engine.

Before vs After — KokoroTTS in Open WebUI

BEFORE AFTER
Manual Setup – Users had to know and either type out or copy-paste the exact KokoroTTS model name and voice(s) string into the “TTS Voice” and “TTS Model” fields. Automatic Discovery – Open WebUI queries your KokoroTTS server (/v1/models and /v1/audio/voices) endpoints and lists every available model and voice in drop-down menus—no typing required!
Hidden Support – KokoroTTS only worked if you tricked the “OpenAI” engine into pointing at a KokoroTTS endpoint; the UI never mentioned KokoroTTS, so many users assumed it simply wasn’t supported or couldn't figure out setup for it. First-class Option – “KokoroTTS” now appears as its own TTS engine in Settings > Audio > Text-to-Speech Engine. Selecting it instantly tells the UI to use the correct endpoints and parameters (as long as a valid URL is entered in the TTS engine base URL input field), removing all guesswork.
Confusion – Users often asked, “Does Open WebUI support Kokoro?” and struggled to configure voices manually. Clarity – The dedicated Kokoro toggle and auto-populated lists make the answer obvious: Yes, and it’s one click away.
Text-to-Speech Engine: Requires users to configure KokoroTTS by pointing the OpenAI engine at a KokoroTTS endpoint. Text-to-Speech Engine: "KokoroTTS" is now a dedicated option in the dropdown, making its support explicit and direct.
TTS Voice: Requires manual entry of voice combinations (e.g., af_alloy+af_heart+af_sky+af_bella) into a single text field. TTS Voice: Offers a "Custom Combination..." option with a dropdown, suggesting predefined choices are now available or expected to be. When "Custom Combination..." is selected, a text input field appears below for manual entry of combinations, along with guidance on how to format them (e.g., af_bella(2)+af_sky(1)).
TTS Model: Requires manual entry of the model name (e.g., kokoro) into a text field. TTS Model: Provides a dropdown menu to select the model, implying automatic discovery of available models from the KokoroTTS server.
Missing Feature: "Enable Text Normalization" toggle is not present. New Feature: "Enable Text Normalization" toggle is introduced, with a description: "Disable text normalization if words are missing or timestamps are incorrect in the generated audio." This suggests enhanced control over audio generation.

Additional Information

  • Weighted voice combinations using ratios (e.g., "af_bella(2)+af_heart(1)" for 67%/33% mix)
  • Ratios are automatically normalized to sum to 100%
  • Available through any endpoint by adding weights in parentheses"

"The api will automaticly do text normalization on input text which may incorrectly remove or change some phrases. This can be disabled by adding "normalization_options":{"normalize": false} to your request json"

  • I'm unsure if the API key (Optional) logic is working properly for KokoroTTS - UNTESTED!
  • The toggle for the added Enable Text Normalization option is colored gray and still needs styling to be green.
  • AUDIO_TTS_KOKORO_API_KEY likely should be an environment variable added to this PR. Thoughts?

Testing is definitely desired with this PR and any feedback is certainly appreciated. This PR was made entirely possible with the companionship of Gemini 2.5 Flash model! DO NOT JUST BLINDLY MERGE THIS!

BEFORE THIS PR

image

AFTER MODIFICATIONS MADE IN THIS PR

image image image image image

Contributor License Agreement

By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/open-webui/open-webui/pull/16036 **Author:** [@silentoplayz](https://github.com/silentoplayz) **Created:** 7/26/2025 **Status:** ❌ Closed **Base:** `dev` ← **Head:** `KokoroTTS-text-to-speech-engine` --- ### 📝 Commits (9) - [`3a25512`](https://github.com/open-webui/open-webui/commit/3a255121d925d78bf6d2f3411a3f87aea7d0f3ca) feat: KokoroTTS text-to-speech-engine option (decoupled from OpenAI TTS option) - [`60f83f3`](https://github.com/open-webui/open-webui/commit/60f83f3eeaf230b222ec56c4f286717de6bf33f0) remove comments - [`f170ea3`](https://github.com/open-webui/open-webui/commit/f170ea39883bfba4aed73866b0c94511e0a1de02) fix: add required for TTS fields to save settings - [`d007819`](https://github.com/open-webui/open-webui/commit/d0078195ee5217ee7c9882268048c5e5066a0303) refac: forward slash (/) support for KokoroTTS Base URL - [`4bb995c`](https://github.com/open-webui/open-webui/commit/4bb995caff2ff06069dec06cbb2e44896006bec4) feat: display voice distribution percentages for KokoroTTS voice combinations input - [`4c88936`](https://github.com/open-webui/open-webui/commit/4c88936c791ad592c05cfe5fd2bf8f1495e383e7) refac: validate KokoroTTS custom voice combination input against the actual available voice names fetched from the KokoroTTS API - [`0536da1`](https://github.com/open-webui/open-webui/commit/0536da1173835008dae9c957c826dbdc6282fc9c) . - [`f09e15b`](https://github.com/open-webui/open-webui/commit/f09e15b5a66743cb6431897260bf44397c88c5f4) Merge branch 'dev' into KokoroTTS-text-to-speech-engine - [`c96fb20`](https://github.com/open-webui/open-webui/commit/c96fb20dce3017a5bee940bdfe155fae0ac79f84) fix: add back required ### 📊 Changes **5 files changed** (+502 additions, -44 deletions) <details> <summary>View changed files</summary> 📝 `backend/open_webui/config.py` (+8 -0) 📝 `backend/open_webui/main.py` (+2 -0) 📝 `backend/open_webui/routers/audio.py` (+122 -8) 📝 `src/lib/components/admin/Settings/Audio.svelte` (+360 -31) 📝 `src/lib/components/chat/Messages/ResponseMessage.svelte` (+10 -5) </details> ### 📄 Description # Pull Request Checklist **Before submitting, make sure you've checked the following:** - [X] **Target branch:** Please verify that the pull request targets the `dev` branch. - [X] **Description:** Provide a concise description of the changes made in this pull request. - [X] **Changelog:** Ensure a changelog entry following the format of [Keep a Changelog](https://keepachangelog.com/) is added at the bottom of the PR description. - [X] **Documentation:** Have you updated relevant documentation [Open WebUI Docs](https://github.com/open-webui/docs), or other documentation sources? - [X] **Dependencies:** Are there any new dependencies? Have you updated the dependency versions in the documentation? - [X] **Testing:** Have you written and run sufficient tests to validate the changes? - [X] **Code review:** Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards? - [X] **Prefix:** To clearly categorize this pull request, prefix the pull request title using one of the following: - **BREAKING CHANGE**: Significant changes that may affect compatibility - **build**: Changes that affect the build system or external dependencies - **ci**: Changes to our continuous integration processes or workflows - **chore**: Refactor, cleanup, or other non-functional code changes - **docs**: Documentation update or addition - **feat**: Introduces a new feature or enhancement to the codebase - **fix**: Bug fix or error correction - **i18n**: Internationalization or localization changes - **perf**: Performance improvement - **refactor**: Code restructuring for better maintainability, readability, or scalability - **style**: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc.) - **test**: Adding missing tests or correcting existing tests - **WIP**: Work in progress, a temporary label for incomplete or ongoing work # Changelog Entry ### Description - Adds a new, decoupled KokoroTTS text-to-speech engine option to Open-WebUI, enabling users to use a KokoroTTS endpoint for Open WebUI's text-to-speech engine independently of OpenAI TTS engine. Configuration is driven by the new `AUDIO_TTS_KOKORO_API_BASE_URL` environment variable (or UI setting) and integrates KokoroTTS model/voice discovery and speech generation throughout the audio pipeline. ### Added - New KokoroTTS TTS engine (`kokoro`) selectable in the UI alongside `openai`, `azure`, and `elevenlabs`. - Support for fetching KokoroTTS models and voices via `/v1/models` and `/v1/audio/voices` endpoints, respectively. - Dedicated KokoroTTS speech generation path that POSTs to `TTS_KOKORO_API_BASE_URL/v1/audio/speech`. - Environment variable `AUDIO_TTS_KOKORO_API_BASE_URL` and corresponding persistent config entry. - Cache keys now include `TTS_KOKORO_API_BASE_URL` to prevent cache collisions when switching engines. - UI fields for `TTS_KOKORO_API_BASE_URL` and an optional `TTS_API_KEY` for KokoroTTS. - Option in the UI to input custom KokoroTTS voice combinations (e.g., `af_bella+af_sky` or `af_bella(2)+af_sky(1)`). - UI toggle to enable/disable text normalization for KokoroTTS, driven by `KOKORO_NORMALIZATION_OPTIONS.normalize` in the config. ### Changed - Updated `backend/open_webui/config.py` to register `AUDIO_TTS_KOKORO_API_BASE_URL`. - Updated `backend/open_webui/main.py` to expose `TTS_KOKORO_API_BASE_URL` to the application state. - Extended `backend/open_webui/routers/audio.py`: - Added Kokoro-related fields to `TTSConfigForm`, `get_audio_config`, and `update_audio_config`, including `KOKORO_NORMALIZATION_OPTIONS`. - Added Kokoro branch in `/speech` endpoint for KokoroTTS requests. - Added Kokoro branches in `get_available_models` and `get_voices` for dynamic discovery. - `Audio.svelte` (frontend UI): - Implemented dynamic fetching and display of KokoroTTS models and voices based on the `TTS_ENGINE` selection. - Introduced a "Custom Combination..." option for KokoroTTS voices, allowing users to input complex voice strings, with client-side validation for empty custom inputs. - Added a toggle for "Enable Text Normalization" for KokoroTTS, reflecting the `KOKORO_NORMALIZATION_OPTIONS.normalize` setting. - Modified the voice and model selection logic to clear previously selected values when switching TTS engines, and to set default OpenAI values when selecting the OpenAI engine. - Updated voice and model type definitions for better clarity and consistency across different TTS engines. ### Fixed - Made the API Key for KokoroTTS *actually* optional. It wasn't before with the OpenAI TTS engine. - Ensured that the "TTS Model" and "TTS Voice" fields are now marked as required for all TTS engines that utilize them, including KokoroTTS, to prevent users from leaving these essential settings blank. Hopefully there aren't any breaking changes. All existing TTS engines remain unchanged and KokoroTTS is an optional text-to-speech engine. ### Before vs After — KokoroTTS in Open WebUI | BEFORE | AFTER | |---|---| | **Manual Setup** – Users had to know and either type out or copy-paste the exact KokoroTTS model name and voice(s) string into the “TTS Voice” and “TTS Model” fields. | **Automatic Discovery** – Open WebUI queries your KokoroTTS server (`/v1/models` and `/v1/audio/voices`) endpoints and lists every available model and voice in drop-down menus—no typing required! | | **Hidden Support** – KokoroTTS only worked if you tricked the “OpenAI” engine into pointing at a KokoroTTS endpoint; the UI never mentioned KokoroTTS, so many users assumed it simply wasn’t supported or couldn't figure out setup for it. | **First-class Option** – “KokoroTTS” now appears as its own TTS engine in `Settings` > `Audio` > `Text-to-Speech Engine`. Selecting it instantly tells the UI to use the correct endpoints and parameters (as long as a valid URL is entered in the TTS engine base URL input field), removing all guesswork. | | **Confusion** – Users often asked, “Does Open WebUI support Kokoro?” and struggled to configure voices manually. | **Clarity** – The dedicated Kokoro toggle and auto-populated lists make the answer obvious: Yes, and it’s one click away. | | **Text-to-Speech Engine:** Requires users to configure KokoroTTS by pointing the OpenAI engine at a KokoroTTS endpoint. | **Text-to-Speech Engine:** "KokoroTTS" is now a dedicated option in the dropdown, making its support explicit and direct. | | **TTS Voice:** Requires manual entry of voice combinations (e.g., `af_alloy+af_heart+af_sky+af_bella`) into a single text field. | **TTS Voice:** Offers a "Custom Combination..." option with a dropdown, suggesting predefined choices are now available or expected to be. When "Custom Combination..." is selected, a text input field appears below for manual entry of combinations, along with guidance on how to format them (e.g., `af_bella(2)+af_sky(1)`). | | **TTS Model:** Requires manual entry of the model name (e.g., `kokoro`) into a text field. | **TTS Model:** Provides a dropdown menu to select the model, implying automatic discovery of available models from the KokoroTTS server. | | **Missing Feature:** "Enable Text Normalization" toggle is not present. | **New Feature:** "Enable Text Normalization" toggle is introduced, with a description: "Disable text normalization if words are missing or timestamps are incorrect in the generated audio." This suggests enhanced control over audio generation. | --- ### Additional Information - 'Voice Combination/Weighted Combinations' of KokoroTTS voices is birthed from the `Voice Combination` section of https://github.com/remsky/Kokoro-FastAPI?tab=readme-ov-file#features. > - Weighted voice combinations using ratios (e.g., "af_bella(2)+af_heart(1)" for 67%/33% mix) > - Ratios are automatically normalized to sum to 100% > - Available through any endpoint by adding weights in parentheses" - The 'Enable Text Normalization' toggle is birthed from the `Missing words & Missing some timestamps` section of https://github.com/remsky/Kokoro-FastAPI?tab=readme-ov-file#known-issues--troubleshooting. I am not 100% sure if this is working or not. It gets toggled off when I toggle it on, save the settings, swap off the audio settings page, and swap back to it. **PLEASE TEST/FIX THIS FOR ME!** > "The api will automaticly do text normalization on input text which may incorrectly remove or change some phrases. This can be disabled by adding "normalization_options":{"normalize": false} to your request json" - **I'm unsure if the API key (`Optional`) logic is working properly for KokoroTTS - UNTESTED!** - **The toggle for the added `Enable Text Normalization` option is colored gray and still needs styling to be green.** - **`AUDIO_TTS_KOKORO_API_KEY` likely should be an environment variable added to this PR. Thoughts?** ### Testing is definitely desired with this PR and any feedback is certainly appreciated. This PR was made entirely possible with the companionship of Gemini 2.5 Flash model! DO NOT JUST BLINDLY MERGE THIS! ### BEFORE THIS PR <img width="1872" height="403" alt="image" src="https://github.com/user-attachments/assets/3c3eeb2d-d278-4906-ba8c-db5f45222ac8" /> ### AFTER MODIFICATIONS MADE IN THIS PR <img width="1898" height="647" alt="image" src="https://github.com/user-attachments/assets/6283777e-f7c1-4a07-9803-1cd3b47ac8c4" /> <img width="1082" height="458" alt="image" src="https://github.com/user-attachments/assets/12297dc5-7017-4722-b2e1-c39acebb19ce" /> <img width="1078" height="420" alt="image" src="https://github.com/user-attachments/assets/6ec4b7aa-6c44-4a4e-8bf8-1cd57ce1a5f1" /> <img width="1061" height="1006" alt="image" src="https://github.com/user-attachments/assets/b7a5b3a9-0aa1-4d95-9d1f-fd2dfa34a9f5" /> <img width="1068" height="254" alt="image" src="https://github.com/user-attachments/assets/8b1c3d91-636a-4c0e-a646-dfcf0eaea7d7" /> ### Contributor License Agreement By submitting this pull request, I confirm that I have read and fully agree to the [Contributor License Agreement (CLA)](/CONTRIBUTOR_LICENSE_AGREEMENT), and I am providing my contributions under its terms. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-05-21 09:42:32 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
confirmed
confirmed issue
core
documentation
enhancement
good first issue
help wanted
non-core
pull-request
Mirrored from GitHub Pull Request
 python
question
testing wanted
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/open-webui#127668
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?