indextts25-inference 0.1.1__tar.gz

indextts25_inference-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - run: uv run --only-group dev ruff check
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - run: uv run --group test pytest --cov=indextts25 --cov-report=xml
+
+      - uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

indextts25_inference-0.1.1/.github/workflows/openwiki-update.yml

@@ -0,0 +1,90 @@
+name: OpenWiki Update
+
+# Paused: there is no LLM API key yet. To turn on the daily update, add the
+# OPENAI_API_KEY secret and uncomment the schedule; until then it only runs by hand.
+on:
+  workflow_dispatch:
+  # schedule:
+  #   - cron: "0 8 * * *"
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          # Full history so `openwiki code --update` can diff HEAD against the
+          # commit it last documented; a shallow clone hides that commit and the
+          # update runs against an empty change summary.
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "22"
+
+      - name: Install OpenWiki
+        # mermaid + jsdom are optional; they add high-fidelity validation of Mermaid diagrams. Remove if your wiki has none.
+        run: npm install --global openwiki@0.7.2 mermaid@11.16.0 jsdom@29.1.1
+
+      - name: Run OpenWiki
+        id: openwiki
+        continue-on-error: true
+        run: openwiki code --update --print
+        env:
+          OPENWIKI_PROVIDER: openai
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENWIKI_MODEL_ID: "gpt-5.6-terra"
+          # Required for the LangSmith connector's code-mode pull to authenticate.
+          # For extra workspaces, add OPENWIKI_LANGSMITH_API_KEY_2, _3, ... as repo
+          # secrets and env entries here.
+          OPENWIKI_LANGSMITH_API_KEY: ${{ secrets.OPENWIKI_LANGSMITH_API_KEY }}
+          # Optional: also trace this workflow's own OpenWiki run to LangSmith.
+          LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
+          LANGCHAIN_PROJECT: openwiki
+          LANGCHAIN_TRACING_V2: "true"
+
+      - name: Remove transient OpenWiki run state
+        if: ${{ !cancelled() }}
+        run: rm -f -- openwiki/.run.json
+
+      - name: List OpenWiki update paths
+        id: paths
+        if: ${{ !cancelled() }}
+        # CLAUDE.md is listed only when present: git add fails on a missing path
+        # and then stages nothing.
+        run: |
+          paths=openwiki,AGENTS.md,.github/workflows/openwiki-update.yml
+          if [ -e CLAUDE.md ]; then paths="$paths,CLAUDE.md"; fi
+          echo "list=$paths" >> "$GITHUB_OUTPUT"
+
+      - name: Create OpenWiki update pull request
+        id: create-pr
+        if: ${{ !cancelled() }}
+        uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7
+        with:
+          add-paths: ${{ steps.paths.outputs.list }}
+          branch: openwiki/update
+          commit-message: "docs: update OpenWiki"
+          title: "docs: update OpenWiki"
+          body: |
+            Automated OpenWiki documentation update.
+
+            OpenWiki result: ${{ steps.openwiki.outcome }}
+
+            When the result is `failure`, this PR intentionally preserves only the
+            pages completed before the failure. Merge it to make that progress the
+            baseline for the next scheduled run.
+
+      - name: Annotate OpenWiki update pull request
+        if: ${{ !cancelled() && steps.create-pr.outputs.pull-request-url != '' }}
+        run: echo "::notice title=OpenWiki update pull request::${{ steps.create-pr.outputs.pull-request-url }}"
+
+      - name: Propagate OpenWiki failure
+        if: ${{ steps.openwiki.outcome == 'failure' }}
+        run: exit 1

indextts25_inference-0.1.1/.github/workflows/release-please.yml

@@ -0,0 +1,17 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}

indextts25_inference-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,20 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - run: uv build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

indextts25_inference-0.1.1/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+checkpoints/
+*.wav
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml

indextts25_inference-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

indextts25_inference-0.1.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.1"
+}

indextts25_inference-0.1.1/AGENTS.md

@@ -0,0 +1,16 @@
+<!-- OPENWIKI:START -->
+
+## OpenWiki
+
+This repository has a generated `openwiki/` evidence index. It is optional just-in-time context, not required startup reading.
+
+- Do not enumerate, preload, or search wikis at task start. Use retrieval when the user asks for it, when unfamiliar architecture or dependency behavior materially affects the task, or when source inspection leaves an important uncertainty. Stop once the question is grounded.
+- When those conditions apply and OpenWiki retrieval tools are available, use `openwiki_search` for just-in-time context and `openwiki_read` for the relevant complete sections. If search returns `workspace_required`, ask which listed workspace to use and retry with its ID.
+- Use `openwiki_list_workspaces` or `openwiki_list_wikis` when workspace membership itself needs to be discovered.
+- If the retrieval tools are unavailable, read `openwiki/quickstart.md` and follow its links to the relevant pages.
+- Treat source code and tests as authoritative. A brief's unknowns and review items are verification gaps, not automatic requirements.
+- Prefer the narrowest quiet validation that proves the changed behavior. Preserve complete failure output.
+
+The scheduled OpenWiki GitHub Actions workflow refreshes the repository wiki. Do not hand-edit generated OpenWiki pages unless explicitly asked; prefer updating source code/docs and letting OpenWiki regenerate.
+
+<!-- OPENWIKI:END -->

indextts25_inference-0.1.1/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.1.1](https://github.com/nicokim/indextts25-inference/compare/v0.1.0...v0.1.1) (2026-10-16)
+
+
+### Documentation
+
+* inicializar OpenWiki ([5a774df](https://github.com/nicokim/indextts25-inference/commit/5a774dfcd4237b2c476270c734d530c367d86f7d))
+* OpenWiki al día con los comentarios en inglés ([94d59e1](https://github.com/nicokim/indextts25-inference/commit/94d59e1e8306e881209d156f038c2081be15c3f1))
+* README en inglés con medidas, stacks recomendados y compatibilidad ([769f871](https://github.com/nicokim/indextts25-inference/commit/769f87198723a83babfb081a345471433b05c227))

indextts25_inference-0.1.1/DISCLAIMER

@@ -0,0 +1,43 @@
+TTS语音合成技术免责声明
+
+1. 总则
+本声明适用于 Index-TTS（以下简称"本项目"）的所有用户和使用者。使用本项目即表示您已阅读、理解并同意遵守本免责声明的全部内容。
+
+2. 使用限制
+2.1 本项目仅供用户进行技术研究、学习和合法的创意应用，不得用于任何违反法律法规的活动。
+
+2.2 用户不得使用本项目：
+   a) 合成政治人物、公众人物或任何未经授权的个人声音；
+   b) 创建诋毁、侮辱、歧视或损害他人名誉和权益的内容；
+   c) 进行欺诈、身份盗用或任何形式的违法活动；
+   d) 传播虚假信息或制造社会恐慌；
+   e) 侵犯他人知识产权、肖像权或隐私权；
+   f) 未经授权将合成声音用于商业目的；
+   g) 违反特定行业（如金融、医疗等）的法规要求；
+   h) 创建或使用涉及未成年人的不当声音内容；
+   i) 制作可能威胁国家安全的内容；
+   j) 违反任何地区关于深度伪造技术的法律法规。
+
+3. 知识产权与授权
+3.1 本项目以[开源许可证类型]许可证开源。
+3.2 用户在使用本项目过程中产生的所有内容及其法律责任由用户自行承担。
+
+4. 责任限制
+4.1 项目开发者不对用户使用本项目所产生的任何直接或间接后果承担责任。
+4.2 项目开发者不保证本项目的功能满足用户的所有需求，也不保证运行不会中断或出错。
+4.3 用户因使用本项目而产生的任何法律纠纷、损失或损害，项目开发者概不负责。
+
+5. 法律适用
+5.1 本免责声明受[国家/地区]法律管辖。
+5.2 如本声明的任何条款与适用法律相抵触，则以适用法律为准。
+
+6. 声明更新
+6.1 项目开发者保留随时更新本免责声明的权利，更新后的声明自发布之日起生效。
+6.2 用户应定期查阅本声明以了解任何变更。
+
+7. 其他条款
+7.1 用户在使用本项目前，应确保其使用行为符合所在地区的法律法规。
+7.2 如用户对本项目的使用引起任何法律纠纷，用户应积极配合相关调查并承担相应责任。
+
+最后更新日期：2025.3.17
+开发者：Bilibili Index Team

indextts25_inference-0.1.1/LICENSE

@@ -0,0 +1,57 @@
+bilibili Model Use License Agreement
+
+By clicking “I agree” to this bilibili Model Use License Agreement (“this Agreement”) , or by otherwise using any portion or element of the Model or any Derivative Work, you will be deemed to have recognized and accepted the content of this Agreement, which is effective immediately. If you do not agree to this Agreement, you must immediately cease all use and permanently delete the Model and any Derivative Works.
+
+1. Definitions
+1.1 “This Agreement”: means the bilibili Model Use License Agreement, including all of its terms and conditions.
+1.2 “We”, “us”, or “our”: means bilibili , the original right-holder of the Model.
+1.3 “You”: means any natural person or legal entity exercising rights granted by this Agreement and/or using the Model for any purpose and in any field of use.
+1.4 “Model”: means the artificial-intelligence model named “bilibili indextts2”, including but not limited to model weights and final code, in each case only to the extent that such components are published by us at https://github.com/index-tts/index-tts.
+1.5 “Derivative Work”: means any derivative of the Model, including without limitation:
+ (i) any modification of the Model, model outputs, or their derivatives;
+ (ii) any work based on the Model, model outputs, or their derivatives; 
+ (iii) any other machine learning model which is created by re-training, fine-tuning, quantizing, LoRA, parameter-efficient fine-tuning, or any other method involving incremental weights or merged checkpoints, in each case based on the Model, model outputs, or their derivatives.
+1.6 “Use”: means downloading, copying, training, modifying, creating Derivative Works, distributing, publishing, running, fine-tuning, publicly displaying, communicating to the public, or otherwise exploiting the Model or any Derivative Work.
+
+2. Scope of License and Restrictions
+2.1 Subject to the terms and conditions of this Agreement, we grant you a worldwide, non-exclusive, non-transferable, royalty-free limited license to Use the Model or any Derivative Work based on the intellectual properties or other rights owned by Us embodied in the Model or any Derivative Work.
+2.2 If You intend to Use, or have already Used, the Model or any Derivative Work, and either (i) your or any of your Affiliates’ products or services had more than 100 million monthly active users in the immediately preceding calendar month, or (ii) your or any of your Affiliates’ annual revenue in the immediately preceding calendar year exceeded RMB 1 billion, You must request a separated license from us, which We may grant to You in our sole discretion. You are not authorized to exercise any of the rights under this Agreement unless and until We have expressly granted You such rights in writing.
+2.3 This Agreement is an open-source license for the Model in which we possess intellectual properties and other rights. It governs your Use of the Model only and does not limit any rights that we have regarding the Model.
+
+3. Disclaimer and Risk Allocation
+3.1 The Model and any outputs generated thereby are provided “AS IS,” without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, non-infringement, absence of errors or omissions, continuity, accuracy, reliability, or stability. You are solely responsible for determining the appropriateness of using or redistributing the Model and assume all risks associated with exercising any rights granted under this Agreement.
+3.2 You shall bear sole responsibility for any infringement, illegality, breach of contract, damages, fines, regulatory investigations, or other liabilities (including, without limitation, infringement of third-party patents, copyrights, trademarks, trade secrets, personality rights, data-protection rights, or any other rights) arising out of or related to your Use of the Model or any outputs generated thereby. We assume no joint, several, supplementary, or advance payment liability.
+3.3 Under no circumstances shall we be liable to you or any third party for any direct, indirect, incidental, special, punitive, or consequential damages (including, without limitation, loss of data, business interruption, or loss of profits) arising out of or related to the Use of the Model, even if we have been advised of the possibility of such damages.
+3.4 Additional Obligations for You and Downstream Recipients
+a) You must ensure that any downstream recipient of the Model or any Derivative Work that you distribute complies with this Agreement, and you must impose appropriate contractual terms on such downstream recipients. If any downstream recipient breaches this Agreement, you shall be responsible for the consequences thereof.
+b) You must retain all original copyright notices and a copy of this Agreement in every copy of the Model or any Derivative Work that you Use.
+c) You may not Use the bilibili indextts2 or any Derivative Work to improve any AI model, except for the bilibili indextts2 itself, its Derivative Works，or non-commercial AI models.
+
+4. Compliance Obligations
+4.1 Usage Restrictions
+a) If you distribute a Derivative Work, you must clearly state in the distribution page or accompanying documentation: “Any modifications made to the original model in this Derivative Work are not endorsed, warranted, or guaranteed by the original right-holder of the original model, and the original right-holder disclaims all liability related to this Derivative Work.”
+b) If your Use of the Model or any Derivative Work incorporates any third-party data or weights, you must obtain all necessary authorizations on your own and bear full responsibility for compliance.
+c) You may not Use the Model or any Derivative Work for any purpose that violates the laws or regulatory requirements of the jurisdiction where the outputs and/or the Model are generated or used (including, without limitation, generating false information, discriminatory content, or content that infringes privacy).
+d) If the Model or any Derivative Work is capable of generating content, you must ensure that such content does not violate the laws or regulatory requirements of the applicable jurisdiction (including, without limitation, generating false information, discriminatory content, or content that infringes privacy).
+4.2 Prohibited High-Risk Use
+You must ensure that the Model and any Derivative Work are not deployed, directly or indirectly, in high-risk scenarios such as medical diagnosis, autonomous driving, military applications, critical-infrastructure control, large-scale biometric surveillance, or automated decision-making (e.g., credit or employment evaluations). If you insist on such deployment, you must independently complete all compliance obligations under applicable laws and regulations (including but not limited to GDPR, CCPA, HIPAA, export-control laws, and AI-specific regulations), and we shall bear no liability for any consequences arising therefrom.
+4.3 Infringement Liability
+Should any third party raise claims against you with respect to any Derivative Work you develop or your Use of the Model or any Derivative Work, you shall bear full and independent responsibility for defending against and resolving such claims. If your actions cause us to incur any third-party claims, administrative penalties, or other losses, you shall indemnify us for all losses we thereby suffer, including but not limited to attorney fees, litigation costs, damages, and fines, and shall take all necessary measures to eliminate any adverse impact on us.
+
+5. Reserved Rights
+5.1 We reserve the right to revoke the license granted to you under this Agreement in the event of your breach. Upon revocation, you must immediately cease all Use and permanently delete all copies of the Model and any Derivative Work. Sections 3 and 6 of this Agreement shall survive termination of this Agreement under this circumstance.
+5.2 Nothing in this Agreement grants you any right to use our trade names, trademarks, service marks, or product names, except as reasonably and customarily required to describe the origin of the Model or any Derivative Work—such as reproducing the content of a NOTICE file under Section 3.4 of this Agreement.
+5.3 If you or any of your Affiliates institutes or participates in any legal proceeding (including any cross-claim or counterclaim in a lawsuit) against us or any of our Affiliates, alleging that the Model or any output or any portion thereof infringes any intellectual property or other rights that you own or control, all licenses granted to you under this Agreement shall terminate automatically as of the date such proceeding is filed.
+
+6. Governing Law and Dispute Resolution
+6.1 This Agreement shall be governed by and construed in accordance with the laws of the People’s Republic of China.
+6.2 In the event of any dispute arising out of or in connection with this Agreement, the parties shall first attempt to resolve such dispute through friendly negotiation. If negotiation fails, the dispute shall be submitted to the Shanghai Arbitration Commission for arbitration in accordance with its then-effective arbitration rules. The arbitration award shall be final and binding on both parties. The prevailing party shall be entitled to recover reasonable costs, including notarization and investigation fees, arbitration costs, attorneys’ fees, and travel expenses.
+
+7. Severability
+If any provision of this Agreement is held to be invalid or unenforceable, the remaining provisions shall remain in full force and effect. The invalid or unenforceable provision shall be replaced with a valid and enforceable provision that, to the maximum extent permitted by law, most closely reflects the original intent of the invalid or unenforceable provision.
+
+8. Version Updates
+We may release new versions of the AI Model Use License Agreement. Any new version will apply only to Uses occurring after the date of its release. If you obtained the Model under an earlier version, the new version will not have retroactive effect; nevertheless, you are encouraged to adopt the new version voluntarily.
+
+9. Language Version
+In the event of any discrepancy or conflict between the English-language version set forth above and the Chinese-language version of this bilibili Model Use License Agreement, the Chinese-language version shall prevail for all purposes and shall govern the rights and obligations of the parties.

indextts25_inference-0.1.1/PKG-INFO

@@ -0,0 +1,320 @@
+Metadata-Version: 2.5
+Name: indextts25-inference
+Version: 0.1.1
+Summary: IndexTTS-2.5 inference library: zero-shot TTS with emotion, speed and streaming control
+Project-URL: Homepage, https://github.com/nicokim/indextts25-inference
+Project-URL: Upstream, https://github.com/index-tts/index-tts
+Author: Bilibili IndexTTS Team
+Maintainer: Kimox
+License-Expression: LicenseRef-Bilibili-IndexTTS
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: einops>=0.8
+Requires-Dist: huggingface-hub>=0.30
+Requires-Dist: librosa>=0.10
+Requires-Dist: nemo-text-processing>=1.1; sys_platform == 'linux' and platform_machine == 'x86_64' and python_version < '3.14'
+Requires-Dist: numpy>=1.26
+Requires-Dist: omegaconf>=2.3
+Requires-Dist: pyyaml>=5.1
+Requires-Dist: safetensors>=0.4.3
+Requires-Dist: tiktoken>=0.7
+Requires-Dist: torch>=2.8
+Requires-Dist: transformers>=4.52
+Provides-Extra: flash
+Requires-Dist: flash-attn>=2.8.3; extra == 'flash'
+Requires-Dist: triton>=3.0; extra == 'flash'
+Provides-Extra: ja
+Requires-Dist: fugashi>=1.2; extra == 'ja'
+Requires-Dist: unidic-lite>=1.0; extra == 'ja'
+Provides-Extra: zh
+Requires-Dist: wetext>=0.1; (sys_platform != 'linux') and extra == 'zh'
+Requires-Dist: wetextprocessing>=1.2; (sys_platform == 'linux') and extra == 'zh'
+Description-Content-Type: text/markdown
+
+# indextts25-inference
+
+[![CI](https://github.com/nicokim/indextts25-inference/actions/workflows/ci.yml/badge.svg)](https://github.com/nicokim/indextts25-inference/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/indextts25-inference)](https://pypi.org/project/indextts25-inference/)
+
+Inference library for **IndexTTS-2.5**: zero-shot text-to-speech (voice cloning from one
+reference clip) with emotion and speed control, and streaming that yields every audio chunk
+together with the text that produced it.
+
+It packages the inference code of [index-tts](https://github.com/index-tts/index-tts)
+(commit `ee40fa7`) behind a small API, fixes a number of upstream bugs (several of them
+changed what the model actually hears) and drops everything inference does not use, about
+80 % of the vendored code.
+
+## Installation
+
+```bash
+pip install indextts25-inference
+```
+
+Python 3.10–3.13 and a CUDA GPU with about 6 GB of free VRAM. The weights are downloaded
+separately; the `qwen0.6bemo4-merge/` text-emotion model in that repo is not used by this
+library and can be skipped:
+
+```bash
+hf download IndexTeam/IndexTTS-2.5 --local-dir=checkpoints --exclude "qwen0.6bemo4-merge/*"
+```
+
+One-time costs on a fresh machine:
+
+- **Auxiliary models.** w2v-bert-2.0, CAMPPlus and BigVGAN are read from
+  `checkpoints/hf_cache/` if they are there; otherwise only the files the library reads are
+  fetched into the standard Hugging Face cache. Set `HF_ENDPOINT` to use a mirror.
+- **Text-normalization grammar.** The first synthesis in a language compiles NeMo's grammar
+  for it (about 25 s). It is cached in `~/.cache/indextts25/nemo_tn/` (or under
+  `$XDG_CACHE_HOME`), and later processes load it in under a second.
+
+### Optional extras
+
+| extra | what it adds |
+|---|---|
+| `flash` | the accelerated GPT engine behind `attn_backend="flash"` (see [Backends](#backends) and [Recommended stack](#recommended-stack)) |
+| `zh` | WeTextProcessing normalization for Chinese and English; without it, both use NeMo |
+| `ja` | Japanese word segmentation (`fugashi` + `unidic-lite`), required for `lang="JA"` |
+
+`nemo-text-processing` pins a `pynini` that only ships wheels for Linux x86_64 up to
+CPython 3.13, so it is not installed elsewhere. Without it, text goes to the model
+unnormalized and digits are read poorly: write numbers out, or install `pynini` from
+conda-forge and then `nemo-text-processing`.
+
+## Usage
+
+```python
+from indextts25 import IndexTTS25
+
+tts = IndexTTS25(model_dir="checkpoints", attn_backend="flash")
+tts.warm("voice.wav")           # pay the one-time costs before the first real request
+
+tts.synthesize("Hola, ¿cómo va?", voice="voice.wav", out="out.wav", speed=0.85)
+```
+
+`lang` defaults to `"ES"`; the model also speaks `"EN"`, `"ZH"`, `"JA"` and `"AR"` (Arabic
+text is not normalized). `warm()` runs one short synthesis: it extracts the voice
+conditioning, loads the language's normalization grammar and, with `"flash"`, captures the
+CUDA graph. Pass it `lang=` if you will not be synthesizing Spanish.
+
+### Streaming with synchronized text
+
+Each chunk carries the text it was generated from, which is what subtitles or an on-screen
+transcript need:
+
+```python
+for chunk in tts.stream("A long text…", voice="voice.wav", lang="EN"):
+    play(chunk.audio)               # float32 mono at 22050 Hz
+    show(chunk.text)                # the segment that produced this audio
+    print(chunk.elapsed, chunk.duration)
+```
+
+`chunk.text` is the model input, not your original string: it is normalized (numbers and
+times spelled out) and, for Spanish, upper-cased. Text with nothing to pronounce (only
+punctuation or emoji) yields no chunks, and `synthesize()` raises `ValueError` for it.
+`include_silence=True` also yields the 200 ms pauses between segments.
+
+`segment_tokens` (60 by default for streaming) sets latency and text granularity at the same
+time: smaller segments return the first chunk sooner and give finer subtitles. Segments are
+cut at punctuation and, when a stretch has none, between words.
+
+### Fine-tuned models
+
+```python
+tts = IndexTTS25(model_dir="checkpoints", config="checkpoints/config_my_voice.yaml")
+```
+
+A YAML with `gpt_checkpoint:` pointing at your weights. It works for a merged LoRA: the
+resulting model has exactly the size and speed of the base one. Checkpoints are loaded
+strictly, so a missing key is an error instead of silently leaving random weights.
+
+### Emotion and speed
+
+```python
+tts.synthesize(text, voice="voice.wav", out="o.wav",
+               emotion="sad_reference.wav", emotion_strength=0.6,
+               speed=0.85)              # <1 is faster; below 0.78 it saturates
+
+# or an emotion vector instead of a reference clip, in the order
+# [happy, angry, sad, afraid, disgusted, melancholic, surprised, calm]
+tts.synthesize(text, voice="voice.wav", out="o.wav", emo_vector=[0, 0, 0.6, 0, 0, 0, 0, 0])
+```
+
+With `emo_vector`, the weight left over (`1 - sum`) goes to the voice's own emotion, so keep
+the sum at 0.8 or less; `emotion_strength` scales the vector. Voice and emotion conditioning
+are cached per file (path and modification time), so alternating between a few references
+costs nothing after the first use of each.
+
+### Generation knobs
+
+`synthesize()` and `stream()` forward extra keyword arguments to the generator:
+`temperature` (0.8), `top_p` (0.8), `top_k` (30), `num_beams` (3), `repetition_penalty` (10),
+`do_sample` (True), `max_mel_tokens` (1500) and, for the diffusion stage, `diffusion_steps`
+(25) and `inference_cfg_rate` (0.7). Fewer diffusion steps trade quality for latency.
+
+### Threads
+
+An instance is not thread-safe: call it from one thread at a time, for example from a single
+worker thread. Which thread does not matter, because the library leaves process-wide state
+alone: it does not redirect `stdout`/`stderr`, install warning filters or set environment
+variables, and it prints nothing unless you pass `verbose=True`.
+
+## Backends
+
+| | `"sdpa"` (default) | `"flash"` |
+|---|---|---|
+| GPT engine | transformers `generate()` | own decoder: paged KV cache, each step replayed as a CUDA graph |
+| decoding | beam sampling (3 beams by default) | sampling, a single beam |
+| sampling knobs | repetition penalty, temperature, top-k, top-p | the same, applied in the same order |
+| needs | nothing extra | a `flash-attn` wheel matching your torch and CUDA |
+
+`"flash"` ignores `num_beams`. Measured below, it is faster and scores the same as `"sdpa"`
+on intelligibility and speaker similarity.
+
+## Performance
+
+RTX 5090 (driver 595, CUDA 13.2), Ryzen 9 9900X, torch 2.9.1+cu130, transformers 4.57.6;
+medians of 5 runs of `scripts/benchmark.py` with a Spanish voice. The sentence has 49
+characters and the paragraph 425 (34 s of audio); TTFA is the time to the first `stream()`
+chunk.
+
+| backend | version | load | warm | TTFA sentence | TTFA paragraph | paragraph | peak VRAM |
+|---|---|---|---|---|---|---|---|
+| sdpa | 0.1.0 | 9.3 s | 25.6 s | 1.23 s | 2.36 s | 8.94 s | 22.8 GB |
+| sdpa | **0.2.0** | 3.0 s | 1.8 s | 0.85 s | 1.43 s | 6.17 s | 6.0 GB |
+| sdpa + fp16 | 0.2.0 | 3.0 s | 1.8 s | 0.94 s | 1.54 s | 6.27 s | 4.3 GB |
+| flash | 0.1.0 | 14.3 s | 25.7 s | 0.81 s | 1.64 s | 4.67 s | 25.3 GB |
+| flash | **0.2.0** | 3.0 s | 1.9 s | 0.73 s | 1.16 s | 4.54 s | 6.3 GB |
+| flash + fp16 | 0.2.0 | 3.2 s | 1.9 s | 0.72 s | 1.19 s | 4.56 s | 4.6 GB |
+
+- `warm` is the first synthesis in a new process: 0.1.0 compiled the text-normalization
+  grammar every time, 0.2.0 loads it from its cache.
+- The peak VRAM of 0.1.0 came mostly from autograd graphs kept alive in its voice cache.
+- `fp16=True` runs the GPT in bf16: 1.7 GB less VRAM, but no faster (with `sdpa`, about
+  0.1 s more to the first chunk).
+- On the recommended stacks below, `sdpa` with torch 2.14.1 measured 0.89 s / 6.39 s
+  (TTFA sentence / paragraph) and `flash` with torch 2.10, 0.71 s / 4.30 s.
+
+## Recommended stack
+
+**`"sdpa"`**: nothing to choose. A plain `pip install indextts25-inference` resolves to the
+newest releases (torch 2.14.1 and transformers 5.20 at the time of writing), which are
+tested.
+
+**`"flash"`**: flash-attn ships only a source distribution on PyPI and prebuilt wheels on
+GitHub for a few torch/CUDA/Python combinations. Install torch and the matching wheel
+*before* the extra; otherwise pip tries to compile flash-attn. With an NVIDIA driver ≥ 580
+(CUDA 13) and Python 3.12:
+
+```bash
+pip install torch==2.10.0 --index-url https://download.pytorch.org/whl/cu130
+pip install "https://github.com/Dao-AILab/flash-attention/releases/download/v2.8.3/flash_attn-2.8.3+cu13torch2.10cxx11abiTRUE-cp312-cp312-linux_x86_64.whl"
+pip install "indextts25-inference[flash]"
+```
+
+The newest CUDA 13 wheels are for torch 2.10; there are none for torch 2.11 or later. With
+an older driver, or another Python version, use torch 2.8 (CUDA 12.8) and the
+`cu12torch2.8` wheel for your Python from the
+[v2.8.3.post1 release](https://github.com/Dao-AILab/flash-attention/releases/tag/v2.8.3.post1);
+that is the minimum tested stack below.
+
+## Version compatibility
+
+Each stack ran the benchmark and six cases (Spanish sentence, paragraph and stream,
+English, Spanish with an emotion reference, Japanese) on the backends listed, and the audio
+was checked with Whisper. With a fixed seed the minimum stack produces bit-identical Spanish
+and Japanese audio to torch 2.9.1.
+
+| Python | torch | transformers | flash-attn | backends |
+|---|---|---|---|---|
+| 3.11 | 2.8.0+cu128 | 4.52.1 | 2.8.3.post1 (cu12) | sdpa, flash |
+| 3.12 | 2.9.1+cu130 | 4.57.6 | 2.8.3 (cu13) | sdpa, flash |
+| 3.12 | 2.10.0+cu130 | 4.57.6 and 5.20.0 | 2.8.3 (cu13) | flash |
+| 3.12 | 2.14.1+cu130 | 5.20.0 | — | sdpa |
+
+Python 3.10 and 3.13 install and pass the CPU tests (torch 2.14.1). CUDA 13 builds of torch
+need an NVIDIA driver ≥ 580.
+
+## Differences from upstream
+
+**Text**
+
+1. **`nemo-text-processing` is a real dependency.** Upstream does not declare it although it
+   needs it for Spanish; without it normalization fails silently and digits reach the
+   tokenizer raw.
+2. **Normalization order.** Upstream applies its punctuation map (which turns `":"` into
+   `","`) *before* normalizing, so `14:30` was read "catorce **coma** treinta". It now runs
+   after NeMo ("catorce **y media**"); for zh/en the colon is left to the normalizer, so
+   "8:00 AM" is no longer "eight, zero AM".
+3. **Exclamation marks reach the model.** In this tokenizer `"!"` has id 0, the same as the
+   start-of-text token, and upstream's padding filter deleted every one of them.
+4. English and Chinese without WeTextProcessing fall back to NeMo instead of being
+   normalized to an empty string (which synthesized about 2 s of noise). With `lang="EN"`,
+   text without letters is no longer routed to the Chinese normalizer.
+5. A stretch of text without punctuation is split between words, never inside one.
+
+**Generation**
+
+6. **Mel positions.** Generated code *k* now gets mel position *k*, as in training; upstream
+   was off by one, which costs about 0.5 nats per token of likelihood on real audio.
+7. **No stray stop token.** Upstream appended an extra stop token to every segment; it became
+   left padding, and the `flash` engine attended to it.
+8. **`flash` samples like transformers.** It applies repetition penalty, temperature, top-k and
+   top-p; upstream's engine sampled with temperature alone.
+
+   Together, 3 and 6–8 (plus the GELU kernel in 14) take `flash` from 3.2 % WER and 0.899
+   speaker similarity to 2.4 % and 0.908, on par with `sdpa` (2.4 %, 0.907 before and
+   after): 48 utterances (20 Spanish and 4 English sentences, two seeds), Whisper
+   large-v3-turbo for WER, CAMPPlus cosine for similarity.
+9. The `flash` engine works with transformers 5.x (it has its own block forward), and so
+   does `sdpa` on 5.x releases that stopped passing an attention mask.
+10. Fixed two `flash` crashes: a false prefix-cache hit with segments of 250+ tokens, and
+    sequences longer than 2048 tokens.
+
+**Memory and speed**
+
+11. **No autograd.** Upstream computes the CAMPPlus style and the prompt condition with
+    autograd on and keeps their graphs alive in its voice cache.
+12. Weights inference never uses are not loaded: w2v-bert layers 18–24, the GPT text head,
+    the codec encoder, and the second copy of the GPT that the `flash` engine used to make.
+13. Models are built directly on the GPU from memory-mapped checkpoints, with weight norm
+    folded at load time.
+14. The GPT uses the fused tanh-GELU kernel (`gelu_pytorch_tanh`, same formula as
+    `gelu_new`): 5–6 % faster.
+15. The emotion vector of a (voice, emotion, strength) triple is computed once and reused.
+
+**Library hygiene**
+
+16. **No global side effects.** Upstream sets `HF_HUB_CACHE` (relative to the working
+    directory) and silences every `FutureWarning` and `UserWarning` on import; its prints are
+    behind `verbose` here. The only global change left is lowering NeMo's and
+    WeTextProcessing's loggers, which both set to INFO with their own handler, to WARNING.
+17. `attn_backend` by name instead of a `use_accel` boolean; streaming yields `(audio, text)`.
+18. Packaged without IndexTTS-2.0, MaskGCT, training and web-UI code, and without
+    `openai-whisper`, `torchaudio`, `munch`, `matplotlib` or `modelscope`. The auxiliary
+    download fetches only the files it reads (2.5 GB less on a fresh install).
+
+## Development
+
+```bash
+pip install -e . pytest
+pytest                                   # fast checks: CPU, no weights
+INDEXTTS25_MODEL_DIR=checkpoints INDEXTTS25_VOICE=voice.wav pytest   # + end to end on GPU
+python scripts/benchmark.py --voice voice.wav --backend flash        # the numbers above
+```
+
+## License
+
+Bilibili Model Use License Agreement — see `LICENSE`. This library is a derivative work;
+its modifications are not endorsed or guaranteed by the original authors.