jaketts 1.0.0__tar.gz

jaketts-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jaketts-1.0.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: jaketts
+Version: 1.0.0
+Summary: Jake's Local CLI Text-to-Speech tool powered by Kokoro-82M
+Author: Jake
+Requires-Python: >=3.10,<3.13
+License-File: LICENSE
+Requires-Dist: kokoro>=0.7.0
+Requires-Dist: sounddevice>=0.4.0
+Requires-Dist: soundfile>=0.4.0
+Requires-Dist: numpy<2.0.0,>=1.20.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: tqdm>=4.65.0
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

jaketts-1.0.0/README.md

@@ -0,0 +1,98 @@
+# 🔊 jaketts
+
+`jaketts` (and its short alias `jtts`) is a lightning-fast, ultra-realistic command-line text-to-speech utility for macOS. Powered by the open-weight **Kokoro-82M** neural engine, it synthesizes highly natural, human-like narration directly in your terminal—completely locally, completely offline, and without requiring any API keys.
+
+By default, it features a rich, deep British voice (`bm_george`) optimized for storytelling and audiobook-style ingestion.
+
+---
+
+## ✨ Features
+* 🔊 **Live Playback:** Streams synthesized speech directly through your default Mac speakers using system memory.
+* 💾 **Audio Export:** Automatically stiches sentence fragments together to output crisp, high-fidelity `.wav` files via the `-o` or `--output` flags.
+* 📖 **Smart Input Handling:** Accepts raw text strings or directly parses `.txt` files seamlessly.
+* 🌍 **Global Execution:** Runs from any directory on your machine after running a single setup script.
+
+---
+
+## 🛠️ Prerequisites & Installation
+
+### 1. Install System Dependencies
+`jaketts` relies on `espeak-ng` for its phonetic mapping backend. Install it via Homebrew:
+```bash
+brew install espeak-ng
+```
+
+### 2. Clone the Repository & Configure Python
+Because underlying text processing tools require pre-compiled binaries, we **strongly recommend** running this tool using a stable **Python 3.11 or 3.12** environment (managed easily via `mise` or native virtual environments).
+
+```bash
+# Clone the workspace
+git clone https://github.com
+cd jaketts
+
+# (Optional) If using mise, lock this folder to Python 3.12
+mise use python@3.12
+
+# Initialize your local application sandbox
+python -m venv .venv
+source .venv/bin/activate
+
+# Install requirements
+pip install --upgrade pip setuptools wheel
+pip install -r requirements.txt
+```
+
+### 3. Make the Command Global
+Run the included installation script to register `jaketts` and `jtts` directly inside your machine's system execution paths:
+```bash
+chmod +x install.sh
+./install.sh
+```
+
+---
+
+## 🚀 Usage Examples
+
+*Note: The very first time you execute a command, the app will automatically download the ~340MB neural model weights. Subsequent runs will process completely offline and execute instantly.*
+
+### Basic Shorthand Execution (Live Playback)
+Pass any text string directly to your shorter alias:
+```bash
+jtts "Three Rings for the Elven-kings under the sky, Seven for the Dwarf-lords in their halls of stone."
+```
+
+### Reading from Text Files
+Pass a text file to read it straight out loud over your speakers:
+```bash
+jtts story.txt
+```
+
+### Saving Audio Files
+To bypass the speakers and save directly to an output file, use the `-o` or `--output` flag:
+```bash
+# Saves the track using the default name 'output.wav'
+jtts -o story.txt
+
+# Saves the track using a custom file name
+jtts -o fantasy_intro.wav "Deep in the land of Mordor where the Shadows lie."
+```
+
+### Overriding the Default Voice
+If you want to shift away from the deep British male voice (`bm_george`), you can explicitly pass an alternative voice ID using the `-v` flag:
+```bash
+# Switch to a conversational American Female profile
+jtts -v af_sarah "Hello from a clear American voice configuration."
+```
+
+---
+
+## 🎛️ Voice Directory Reference
+You can swap to any of Kokoro's built-in regional presets using the `-v` flag. Highly recommended profiles include:
+
+| Voice ID | Accent | Gender | Best Used For... |
+| :--- | :--- | :--- | :--- |
+| `bm_george` | British | Male | **[Default]** Deep, steady, and clear audiobook tone. |
+| `bm_lewis` | British | Male | Warm, documentary-ready cinematic narrator. |
+| `bf_emma` | British | Female | Crisp, highly professional narrative spacing. |
+| `af_heart` | American | Female | Highly melodic, emotional, and expressive. |
+| `am_adam` | American | Male | Deep, classic American broadcast tone. |

jaketts-1.0.0/jaketts.egg-info/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: jaketts
+Version: 1.0.0
+Summary: Jake's Local CLI Text-to-Speech tool powered by Kokoro-82M
+Author: Jake
+Requires-Python: >=3.10,<3.13
+License-File: LICENSE
+Requires-Dist: kokoro>=0.7.0
+Requires-Dist: sounddevice>=0.4.0
+Requires-Dist: soundfile>=0.4.0
+Requires-Dist: numpy<2.0.0,>=1.20.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: tqdm>=4.65.0
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

jaketts-1.0.0/jaketts.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+jaketts.py
+pyproject.toml
+setup.py
+jaketts.egg-info/PKG-INFO
+jaketts.egg-info/SOURCES.txt
+jaketts.egg-info/dependency_links.txt
+jaketts.egg-info/entry_points.txt
+jaketts.egg-info/requires.txt
+jaketts.egg-info/top_level.txt

jaketts-1.0.0/jaketts.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jaketts-1.0.0/jaketts.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+jaketts = jaketts:main
+jtts = jaketts:main

jaketts-1.0.0/jaketts.egg-info/requires.txt

@@ -0,0 +1,6 @@
+kokoro>=0.7.0
+sounddevice>=0.4.0
+soundfile>=0.4.0
+numpy<2.0.0,>=1.20.0
+torch>=2.0.0
+tqdm>=4.65.0

jaketts-1.0.0/jaketts.egg-info/top_level.txt

@@ -0,0 +1 @@
+jaketts

jaketts-1.0.0/jaketts.py

@@ -0,0 +1,421 @@
+#!/usr/bin/env python3
+import sys
+import os
+import argparse
+import re
+import numpy as np
+import soundfile as sf
+import sounddevice as sd
+
+# Silence torch, tokenizer, and huggingface framework warnings completely
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+os.environ["HF_HUB_DISABLE_SYMLINKS_WARNING"] = "1"
+import warnings
+
+warnings.filterwarnings("ignore")
+
+try:
+    import logging
+
+    logging.getLogger("huggingface_hub").setLevel(logging.ERROR)
+    logging.getLogger("huggingface_hub.utils._validators").setLevel(logging.ERROR)
+    logging.getLogger("huggingface_hub.hub_mixin").setLevel(logging.ERROR)
+except:
+    pass
+
+from kokoro import KPipeline
+
+try:
+    from tqdm import tqdm
+except ImportError:
+
+    def tqdm(iterable, *args, **kwargs):
+        return iterable
+
+
+# --- BATCH PROCESSING PIPELINE ---
+def process_text_in_batches(pipeline, text, voice, speed, pbar=None):
+    """
+    Safely breaks text into smaller paragraph blocks to prevent
+    memory exhaustion on massive inputs.
+    """
+    paragraphs = [p.strip() for p in re.split(r"\n+", text) if p.strip()]
+    if not paragraphs:
+        paragraphs = [text]
+
+    audio_chunks = []
+
+    for para in paragraphs:
+        try:
+            generator = pipeline(para, voice=voice, speed=speed)
+            for _, _, audio in generator:
+                if audio is not None:
+                    audio_chunks.append(audio)
+            if pbar:
+                pbar.update(1)
+        except Exception as e:
+            print(f"\n⚠️ Warning: Failed to synthesize segment: {e}")
+            continue
+
+    return audio_chunks
+
+
+# --- NATIVE DESKTOP GUI APP ---
+def launch_desktop_gui():
+    """
+    Launches a modern, themed Tkinter desktop interface.
+    Only runs if the user executes the command with zero parameters.
+    """
+    import tkinter as tk
+    from tkinter import ttk, filedialog, messagebox
+    import threading
+
+    root = tk.Tk()
+    root.title("🔊 jaketts - Text to Speech")
+    root.geometry("600x500")
+    root.minsize(500, 400)
+
+    style = ttk.Style(root)
+    style.theme_use("clam" if sys.platform == "darwin" else "default")
+
+    main_frame = ttk.Frame(root, padding="15")
+    main_frame.pack(fill=tk.BOTH, expand=True)
+
+    ttk.Label(
+        main_frame, text="Enter Text or Load a File:", font=("Helvetica", 12, "bold")
+    ).pack(anchor=tk.W, pady=(0, 5))
+
+    container = ttk.Frame(main_frame)
+    container.pack(fill=tk.BOTH, expand=True)
+
+    text_scroll = ttk.Scrollbar(container)
+    text_scroll.pack(side=tk.RIGHT, fill=tk.Y)
+
+    text_box = tk.Text(
+        container,
+        yscrollcommand=text_scroll.set,
+        wrap=tk.WORD,
+        font=("Helvetica", 11),
+        height=10,
+    )
+    text_box.pack(fill=tk.BOTH, expand=True, side=tk.LEFT)
+    text_scroll.config(command=text_box.yview)
+
+    control_frame = ttk.Frame(main_frame, padding="10")
+    control_frame.pack(fill=tk.X, pady=10)
+
+    ttk.Label(control_frame, text="Voice:").grid(row=0, column=0, sticky=tk.W, padx=5)
+    voice_var = tk.StringVar(value="bm_george")
+    voice_dropdown = ttk.Combobox(
+        control_frame, textvariable=voice_var, state="readonly", width=12
+    )
+    voice_dropdown["values"] = (
+        "[en-us] af_heart",
+        "[en-us] af_sarah",
+        "[en-us] af_bella",
+        "[en-us] af_nicole",
+        "[en-us] af_sky",
+        "[en-us] af_alloy",
+        "[en-us] af_aoede",
+        "[en-us] af_jessica",
+        "[en-us] af_river",
+        "[en-us] am_adam",
+        "[en-us] am_michael",
+        "[en-us] am_echo",
+        "[en-us] am_eric",
+        "[en-us] am_fenrir",
+        "[en-us] am_liam",
+        "[en-us] am_onizuka",
+        "[en-us] am_puck",
+        "[en-us] am_santa",
+        "[en-gb] bm_george",
+        "[en-gb] bm_lewis",
+        "[en-gb] bf_emma",
+        "[en-gb] bf_isabella",
+        "[en-gb] bm_fable",
+        "[en-gb] bm_daniel",
+        "[en-gb] bf_alice",
+        "[en-gb] bf_lily",
+        "[es] ef_dora",
+        "[es] em_alex",
+        "[fr] ff_sixtine",
+        "[fr] fm_julien",
+        "[hi] hf_ananya",
+        "[hi] hf_kavya",
+        "[hi] hm_anshul",
+        "[hi] hm_shiwani",
+        "[it] if_sara",
+        "[it] im_nicola",
+        "[ja] jf_alpha",
+        "[ja] jf_glowing",
+        "[ja] jf_neutral",
+        "[ja] jf_reader",
+        "[ja] jm_kanta",
+        "[pt] pf_doris",
+        "[pt] pm_ramon",
+        "[zh] zf_xiaobei",
+        "[zh] zf_xiaoni",
+        "[zh] zf_xiaoxiao",
+        "[zh] zf_xiaoyi",
+        "[zh] zm_yunjian",
+        "[zh] zm_yunxi",
+        "[zh] zm_yunxia",
+        "[zh] zm_yunyang",
+    )
+    voice_dropdown.grid(row=0, column=1, padx=5, sticky=tk.W)
+
+    ttk.Label(control_frame, text="Speed:").grid(row=0, column=2, sticky=tk.W, padx=15)
+    speed_var = tk.DoubleVar(value=1.0)
+    speed_scale = ttk.Scale(
+        control_frame,
+        from_=0.5,
+        to=2.0,
+        variable=speed_var,
+        orient=tk.HORIZONTAL,
+        length=120,
+    )
+    speed_scale.grid(row=0, column=3, padx=5, sticky=tk.W)
+
+    speed_label = ttk.Label(control_frame, text="1.0x")
+    speed_label.grid(row=0, column=4, padx=2)
+
+    def update_speed_label(*args):
+        speed_label.config(text=f"{speed_var.get():.2f}x")
+
+    speed_var.trace_add("write", update_speed_label)
+
+    progress_bar = ttk.Progressbar(main_frame, orient=tk.HORIZONTAL, mode="determinate")
+    progress_bar.pack(fill=tk.X, pady=5)
+
+    status_label = ttk.Label(main_frame, text="Ready", font=("Helvetica", 10, "italic"))
+    status_label.pack(anchor=tk.W, pady=2)
+
+    def open_text_file():
+        file_path = filedialog.askopenfilename(
+            filetypes=[("Text Files", "*.txt"), ("All Files", "*.*")]
+        )
+        if file_path:
+            try:
+                with open(file_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                text_box.delete("1.0", tk.END)
+                text_box.insert("1.0", content)
+                status_label.config(
+                    text=f"📖 Loaded file: {os.path.basename(file_path)}"
+                )
+            except Exception as e:
+                messagebox.showerror("Error", f"Failed to read text file:\n{e}")
+
+    def run_synthesis(action_type):
+        input_text = text_box.get("1.0", tk.END).strip()
+        if not input_text:
+            messagebox.showwarning(
+                "Warning", "Please provide or load some text content first!"
+            )
+            return
+
+        dropdown_selection = voice_var.get()
+        # Extracts the raw voice name from the end (e.g., "af_heart")
+        voice = dropdown_selection.split()[-1]
+
+        # Pulls the prefix inside the brackets to set the language code (a, b, e, f, h, i, j, p, z)
+        prefix = dropdown_selection.split("]")[0].replace("[", "").strip()
+        if "-" in prefix:
+            # Safely converts 'en-us' to 'a' and 'en-gb' to 'b'
+            lang_code = "a" if prefix.endswith("us") else "b"
+        else:
+            # Takes the first letter for other locales ('es' -> 'e', 'ja' -> 'j')
+            lang_code = prefix[0]
+
+        speed = speed_var.get()
+
+        def worker():
+            try:
+                status_label.config(text="🤖 Loading AI Neural Engine Checkpoints...")
+                progress_bar.config(mode="indet")
+                progress_bar.start(10)
+
+                pipeline = KPipeline(lang_code=lang_code, repo_id="hexgrad/Kokoro-82M")
+
+                paragraphs = [p for p in input_text.split("\n") if p.strip()]
+                total_p = len(paragraphs) if paragraphs else 1
+
+                progress_bar.stop()
+                progress_bar.config(mode="determinate", maximum=total_p, value=0)
+                status_label.config(text="🗣️  Generating Speech Array Channels...")
+
+                if action_type == "play":
+                    for para in paragraphs:
+                        generator = pipeline(para, voice=voice, speed=speed)
+                        for _, _, audio in generator:
+                            if audio is not None:
+                                sd.play(audio, samplerate=24000)
+                                sd.wait()
+                        progress_bar.step(1)
+                    status_label.config(text="✨ Finished live playback successfully!")
+                else:
+                    audio_chunks = []
+                    for para in paragraphs:
+                        generator = pipeline(para, voice=voice, speed=speed)
+                        for _, _, audio in generator:
+                            if audio is not None:
+                                audio_chunks.append(audio)
+                        progress_bar.step(1)
+
+                    if audio_chunks:
+                        combined = np.concatenate(audio_chunks)
+                        root.after(0, lambda: save_audio_file(combined))
+                    else:
+                        status_label.config(
+                            text="❌ Generation produced no audio data."
+                        )
+
+            except Exception as e:
+                root.after(
+                    0, lambda: messagebox.showerror("Error", f"Synthesis broken:\n{e}")
+                )
+                status_label.config(text="❌ Process Failed.")
+            finally:
+                root.after(0, lambda: progress_bar.config(value=0))
+
+        threading.Thread(target=worker, daemon=True).start()
+
+    def save_audio_file(audio_data):
+        save_path = filedialog.asksaveasfilename(
+            defaultextension=".wav", filetypes=[("WAV Audio", "*.wav")]
+        )
+        if save_path:
+            try:
+                sf.write(save_path, audio_data, 24000)
+                status_label.config(
+                    text=f"✨ Saved track to: {os.path.basename(save_path)}"
+                )
+                messagebox.showinfo(
+                    "Success", f"Audio track exported successfully to:\n{save_path}"
+                )
+            except Exception as e:
+                messagebox.showerror("Error", f"Failed to save file:\n{e}")
+        else:
+            status_label.config(text="⚠️ File export cancelled.")
+
+    btn_frame = ttk.Frame(main_frame)
+    btn_frame.pack(fill=tk.X, pady=10)
+
+    ttk.Button(btn_frame, text="📖 Open File", command=open_text_file).pack(
+        side=tk.LEFT, padx=5
+    )
+    ttk.Button(
+        btn_frame, text="🔊 Play Speech", command=lambda: run_synthesis("play")
+    ).pack(side=tk.RIGHT, padx=5)
+    ttk.Button(
+        btn_frame, text="💾 Save WAV File", command=lambda: run_synthesis("save")
+    ).pack(side=tk.RIGHT, padx=5)
+
+    root.mainloop()
+
+
+# --- PRIMARY COMMAND LINE INTERFACE ROUTING ENGINE ---
+def main():
+    if len(sys.argv) == 1:
+        launch_desktop_gui()
+        sys.exit(0)
+
+    if len(sys.argv) == 3 and sys.argv[1] in ["-o", "--output"]:
+        potential_file = sys.argv[2]
+        if os.path.isfile(potential_file) and not potential_file.lower().endswith(
+            ".wav"
+        ):
+            sys.argv = [sys.argv[0], "-o", "output.wav", potential_file]
+
+    parser = argparse.ArgumentParser(
+        description="🔊 Jake's Text-to-Speech CLI utility powered by Kokoro."
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        nargs="?",
+        const="output.wav",
+        default=None,
+        help="Output filename.",
+    )
+    parser.add_argument(
+        "-v", "--voice", default="bm_george", help="Voice profile ID selection."
+    )
+    parser.add_argument(
+        "-s", "--speed", type=float, default=1.0, help="Vocal speed modifier parameter."
+    )
+    parser.add_argument(
+        "text_input", help="The text string or path to a .txt file input source."
+    )
+
+    args = parser.parse_args()
+
+    final_text = args.text_input
+    if os.path.isfile(args.text_input):
+        print(f"📖 Reading text from file: {os.path.abspath(args.text_input)}")
+        try:
+            with open(args.text_input, "r", encoding="utf-8") as f:
+                final_text = f.read().strip()
+        except Exception as e:
+            print(f"❌ Error reading file: {e}")
+            sys.exit(1)
+
+    if not final_text:
+        print("❌ Error: No text content found to synthesize.")
+        sys.exit(1)
+
+    lang_code = args.voice.lower()
+    if lang_code not in ["a", "b", "e", "f", "h", "i", "j", "p", "z"]:
+        lang_code = "b" if lang_code.startswith("b") else "a"
+
+    print(f"🤖 Initializing Kokoro Engine (Locale: {lang_code})...")
+    try:
+        pipeline = KPipeline(lang_code=lang_code, repo_id="hexgrad/Kokoro-82M")
+    except Exception as e:
+        print(f"❌ Failed to load pipeline: {e}")
+        sys.exit(1)
+
+    print(f"🗣️  Synthesizing text via voice '{args.voice}' (Speed: {args.speed}x)...")
+
+    if args.output is not None:
+        print(f"💾 Gathering audio tracks for batch file output...")
+        paragraphs = [p for p in final_text.split("\n") if p.strip()]
+        total_chunks = len(paragraphs) if paragraphs else 1
+
+        pbar = tqdm(
+            total=total_chunks, desc="Processing Paragraph Blocks", unit="chunk"
+        )
+        audio_chunks = process_text_in_batches(
+            pipeline, final_text, args.voice, args.speed, pbar=pbar
+        )
+
+        pbar.n = pbar.total
+        pbar.refresh()
+        pbar.close()
+
+        if not audio_chunks:
+            print("❌ No audio data generated.")
+            sys.exit(1)
+
+        combined_audio = np.concatenate(audio_chunks)
+        sf.write(args.output, combined_audio, 24000)
+        print(f"✨ Success! Audio file written to: {os.path.abspath(args.output)}")
+    else:
+        print("🔊 Playing audio directly through your speakers...")
+        paragraphs = [p for p in final_text.split("\n") if p.strip()]
+        if not paragraphs:
+            paragraphs = [final_text]
+
+        for para in paragraphs:
+            try:
+                generator = pipeline(para, voice=args.voice, speed=args.speed)
+                for _, _, audio in generator:
+                    if audio is not None:
+                        sd.play(audio, samplerate=24000)
+                        sd.wait()
+            except Exception as e:
+                print(f"\n⚠️ Error speaking segment: {e}")
+
+
+if __name__ == "__main__":
+    main()

jaketts-1.0.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"

jaketts-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jaketts-1.0.0/setup.py

@@ -0,0 +1,24 @@
+from setuptools import setup
+
+setup(
+    name="jaketts",
+    version="1.0.0",
+    description="Jake's Local CLI Text-to-Speech tool powered by Kokoro-82M",
+    author="Jake",
+    py_modules=["jaketts"],
+    install_requires=[
+        "kokoro>=0.7.0",
+        "sounddevice>=0.4.0",
+        "soundfile>=0.4.0",
+        "numpy>=1.20.0,<2.0.0",
+        "torch>=2.0.0",
+        "tqdm>=4.65.0",
+    ],
+    entry_points={
+        "console_scripts": [
+            "jaketts=jaketts:main",
+            "jtts=jaketts:main",
+        ],
+    },
+    python_requires=">=3.10,<3.13",
+)