refactor(core): package for distribution & add stdin

- [refactor] Rename `kokoro-tts` entry point (kokoro_tts/__init__.py)
- [refactor] Extract main execution logic into `main()` function (__init__.py:1194)
- [refactor] Adjust unknown command-line option loop in `main()` (__init__.py:1204,1206)
- [refactor] Update `if __name__ == '__main__':` block to call `main()` (__init__.py:1307-1308)
- [add] Create module entry point (kokoro_tts/__main__.py)
- [feat] Add `stdin_indicators` parameter and implement stdin reading logic in `convert_text_to_audio()` (__init__.py:796-813,887-891)
- [feat] Define and pass `stdin_indicators` to `convert_text_to_audio()` in `main()` (__init__.py:1197-1198,1303)
- [feat] Modify input file existence check to allow stdin paths (__init__.py:1287)
- [build] Define `kokoro-tts` console script (pyproject.toml:16-17)
- [build] Specify `hatchling` as build backend (pyproject.toml:19-21)
- [docs] Update Python version prerequisites (README.md)
- [docs] Expand installation instructions, move model download info, and add usage notes for stdin (README.md)
- [docs] Add `[!TIP]` notes for running commands (README.md:162-164)

Author: nazdridoy

README.md

@@ -34,45 +34,107 @@ https://github.com/user-attachments/assets/8413e640-59e9-490e-861d-49187e967526
 
 ## Prerequisites
 
-- Python 3.12
+- Python 3.9-3.12 (Python 3.13+ is not currently supported)
 
 ## Installation
 
+### Method 1: Install from Git (Recommended)
+
+The easiest way to install Kokoro TTS is directly from the repository:
+
+```bash
+# Using uv (recommended)
+uv tool install git+https://github.com/nazdridoy/kokoro-tts
+
+# Using pip
+pip install git+https://github.com/nazdridoy/kokoro-tts
+```
+
+After installation, you can run:
+```bash
+kokoro-tts --help
+```
+
+### Method 2: Clone and Install Locally
+
 1. Clone the repository:
 ```bash
 git clone https://github.com/nazdridoy/kokoro-tts.git
 cd kokoro-tts
 ```
 
-2. Install required packages:
-
-It is recommended to use a virtual environment to avoid dependency conflicts.
+2. Install the package:
 
 **With `uv` (recommended):**
 ```bash
 uv venv
+uv pip install -e .
+```
+
+**With `pip`:**
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+3. Run the tool:
+```bash
+# If using uv
+uv run kokoro-tts --help
+
+# If using pip with activated venv
+kokoro-tts --help
+```
+
+### Method 3: Run Without Installation
+
+If you prefer to run without installing:
+
+1. Clone the repository:
+```bash
+git clone https://github.com/nazdridoy/kokoro-tts.git
+cd kokoro-tts
+```
+
+2. Install dependencies only:
+
+**With `uv`:**
+```bash
+uv venv
 uv sync
 ```
+
 **With `pip`:**
 ```bash
 python -m venv .venv
-source .venv/bin/activate
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 pip install -r requirements.txt
 ```
 
-Note: You can also use `uv` as a faster alternative to pip for package installation. (This is a uv project)
-Note: Python>=3.13 is not currently supported.
+3. Run directly:
+```bash
+# With uv
+uv run -m kokoro_tts --help
+
+# With pip (venv activated)
+python -m kokoro_tts --help
+```
+
+### Download Model Files
+
+After installation, download the required model files to your working directory:
 
-3. Download the required model files:
 ```bash
-# Download either voices.json or voices.bin (bin is preferred)
+# Download voice data (bin format is preferred)
 wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/voices-v1.0.bin
 
 # Download the model
 wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/kokoro-v1.0.onnx
 ```
-Note: The script will automatically use voices.bin if present, falling back to voices.json if bin is not available.
 
+> [!NOTE]
+> The script will automatically use `voices-v1.0.bin` if present, falling back to `voices.json` if the bin file is not available. Place these files in the same directory where you run the `kokoro-tts` command.
 
 ## Supported voices:
 
@@ -86,16 +148,18 @@ Note: The script will automatically use voices.bin if present, falling back to v
 | 🇯🇵 | jf\_alpha, jf\_gongitsune, jf\_nezumi, jf\_tebukuro, jm\_kumo | **ja** |
 | 🇨🇳 | zf\_xiaobei, zf\_xiaoni, zf\_xiaoxiao, zf\_xiaoyi, zm\_yunjian, zm\_yunxi, zm\_yunxia, zm\_yunyang | **cmn** |
 
-
 ## Usage
 
-Basic usage:
+### Basic Usage
+
 ```bash
-./kokoro-tts <input_text_file> [<output_audio_file>] [options]
+kokoro-tts <input_text_file> [<output_audio_file>] [options]
 ```
 
 > [!NOTE]
-> If you have installed the dependencies in a virtual environment, you need to either activate it first (e.g., `source .venv/bin/activate`) or use `uv run` to execute the commands.
+> - If you installed via Method 1 (git install), use `kokoro-tts` directly
+> - If you installed via Method 2 (local install), use `uv run kokoro-tts` or activate your virtual environment first
+> - If you're using Method 3 (no install), use `uv run -m kokoro_tts` or `python -m kokoro_tts` with activated venv
 
 ### Commands
 
@@ -121,6 +185,7 @@ Basic usage:
 - `.txt`: Text file input
 - `.epub`: EPUB book input (will process chapters)
 - `.pdf`: PDF document input (extracts chapters from TOC or content)
+- `-` or `/dev/stdin` (Linux/macOS) or `CONIN$` (Windows): Standard input (stdin)
 
 ### Examples
 
@@ -129,11 +194,13 @@ Basic usage:
 kokoro-tts input.txt output.wav --speed 1.2 --lang en-us --voice af_sarah
 
 # Read from standard input (stdin)
-echo "Hello World" | uv run kokoro-tts /dev/stdin --stream
-cat input.txt | kokoro-tts /dev/stdin output.wav
+echo "Hello World" | kokoro-tts - --stream
+cat input.txt | kokoro-tts - output.wav
 
-# Use voice blending (60-40 mix) (with uv run)
-uv run kokoro-tts input.txt output.wav --voice "af_sarah:60,am_adam:40"
+# Cross-platform stdin support:
+# Linux/macOS: echo "text" | kokoro-tts - --stream
+# Windows: echo "text" | kokoro-tts - --stream
+# All platforms also support: kokoro-tts /dev/stdin --stream (Linux/macOS) or kokoro-tts CONIN$ --stream (Windows)
 
 # Use voice blending (60-40 mix)
 kokoro-tts input.txt output.wav --voice "af_sarah:60,am_adam:40"
@@ -155,13 +222,18 @@ kokoro-tts input.epub --split-output ./chunks/ --debug
 
 # Process PDF and split into chapters
 kokoro-tts input.pdf --split-output ./chunks/ --format mp3
+
 # List available voices
 kokoro-tts --help-voices
 
 # List supported languages
 kokoro-tts --help-languages
 ```
 
+> [!TIP]
+> If you're using Method 2, replace `kokoro-tts` with `uv run kokoro-tts` in the examples above.
+> If you're using Method 3, replace `kokoro-tts` with `uv run -m kokoro_tts` or `python -m kokoro_tts` in the examples above.
+
 ## Features in Detail
 
 ### EPUB Processing

kokoro-tts kokoro_tts/__init__.pykokoro-tts renamed to kokoro_tts/__init__.py

@@ -779,8 +779,13 @@ def process_chunk_sequential(chunk: str, kokoro: Kokoro, voice: str, speed: floa
         return None, None
 
 def convert_text_to_audio(input_file, output_file=None, voice=None, speed=1.0, lang="en-us", 
-                         stream=False, split_output=None, format="wav", debug=False):
+                         stream=False, split_output=None, format="wav", debug=False, stdin_indicators=None):
     global stop_spinner
+    
+    # Define stdin indicators if not provided
+    if stdin_indicators is None:
+        stdin_indicators = ['/dev/stdin', '-', 'CONIN$']  # CONIN$ is Windows stdin
+    
     # Load Kokoro model
     try:
         kokoro = Kokoro("kokoro-v1.0.onnx", "voices-v1.0.bin")
@@ -792,48 +797,53 @@ def convert_text_to_audio(input_file, output_file=None, voice=None, speed=1.0, l
         if voice:
             voice = validate_voice(voice, kokoro)
         else:
-            # Interactive voice selection
-            voices = list_available_voices(kokoro)
-            print("\nHow to choose a voice:")
-            print("You can use either a single voice or blend two voices together.")
-            print("\nFor a single voice:")
-            print("  • Just enter one number (example: '7')")
-            print("\nFor blending two voices:")
-            print("  • Enter two numbers separated by comma")
-            print("  • Optionally add weights after each number using ':weight'")
-            print("\nExamples:")
-            print("  • '7'      - Use voice #7 only")
-            print("  • '7,11'   - Mix voices #7 and #11 equally (50% each)")
-            print("  • '7:60,11:40' - Mix 60% of voice #7 with 40% of voice #11")
-            try:
-                voice_input = input("Choose voice(s) by number: ")
-                if ',' in voice_input:
-                    # Handle blended voices
-                    pairs = []
-                    for pair in voice_input.split(','):
-                        if ':' in pair:
-                            num, weight = pair.strip().split(':')
-                            voice_idx = int(num.strip()) - 1
-                            if not (0 <= voice_idx < len(voices)):
-                                raise ValueError(f"Invalid voice number: {int(num)}")
-                            pairs.append(f"{voices[voice_idx]}:{weight}")
-                        else:
-                            voice_idx = int(pair.strip()) - 1
-                            if not (0 <= voice_idx < len(voices)):
-                                raise ValueError(f"Invalid voice number: {int(pair)}")
-                            pairs.append(voices[voice_idx])
-                    voice = ','.join(pairs)
-                else:
-                    # Single voice
-                    voice_choice = int(voice_input) - 1
-                    if not (0 <= voice_choice < len(voices)):
-                        raise ValueError("Invalid choice")
-                    voice = voices[voice_choice]
-                # Validate and potentially convert to blend
-                voice = validate_voice(voice, kokoro)
-            except (ValueError, IndexError):
-                print("Invalid choice. Using default voice.")
+            # Check if we're using stdin (can't do interactive input)
+            if input_file in stdin_indicators:
+                print("Using stdin - automatically selecting default voice (af_sarah)")
                 voice = "af_sarah"  # default voice
+            else:
+                # Interactive voice selection
+                voices = list_available_voices(kokoro)
+                print("\nHow to choose a voice:")
+                print("You can use either a single voice or blend two voices together.")
+                print("\nFor a single voice:")
+                print("  • Just enter one number (example: '7')")
+                print("\nFor blending two voices:")
+                print("  • Enter two numbers separated by comma")
+                print("  • Optionally add weights after each number using ':weight'")
+                print("\nExamples:")
+                print("  • '7'      - Use voice #7 only")
+                print("  • '7,11'   - Mix voices #7 and #11 equally (50% each)")
+                print("  • '7:60,11:40' - Mix 60% of voice #7 with 40% of voice #11")
+                try:
+                    voice_input = input("Choose voice(s) by number: ")
+                    if ',' in voice_input:
+                        # Handle blended voices
+                        pairs = []
+                        for pair in voice_input.split(','):
+                            if ':' in pair:
+                                num, weight = pair.strip().split(':')
+                                voice_idx = int(num.strip()) - 1
+                                if not (0 <= voice_idx < len(voices)):
+                                    raise ValueError(f"Invalid voice number: {int(num)}")
+                                pairs.append(f"{voices[voice_idx]}:{weight}")
+                            else:
+                                voice_idx = int(pair.strip()) - 1
+                                if not (0 <= voice_idx < len(voices)):
+                                    raise ValueError(f"Invalid voice number: {int(pair)}")
+                                pairs.append(voices[voice_idx])
+                        voice = ','.join(pairs)
+                    else:
+                        # Single voice
+                        voice_choice = int(voice_input) - 1
+                        if not (0 <= voice_choice < len(voices)):
+                            raise ValueError("Invalid choice")
+                        voice = voices[voice_choice]
+                    # Validate and potentially convert to blend
+                    voice = validate_voice(voice, kokoro)
+                except (ValueError, IndexError):
+                    print("Invalid choice. Using default voice.")
+                    voice = "af_sarah"  # default voice
     except ValueError as e:
         print(f"Error: {e}")
         sys.exit(1)
@@ -875,8 +885,12 @@ def convert_text_to_audio(input_file, output_file=None, voice=None, speed=1.0, l
         parser = PdfParser(input_file, debug=debug)
         chapters = parser.get_chapters()
     else:
-        with open(input_file, 'r', encoding='utf-8') as file:
-            text = file.read()
+        # Handle stdin specially (cross-platform)
+        if input_file in stdin_indicators:
+            text = sys.stdin.read()
+        else:
+            with open(input_file, 'r', encoding='utf-8') as file:
+                text = file.read()
         # Treat single text file as one chapter
         chapters = [{'title': 'Chapter 1', 'content': text}]
 
@@ -1194,22 +1208,27 @@ def get_valid_options():
         '--debug'  # Add debug option
     }
 
-if __name__ == "__main__":
-    # Validate command line options first
+
+
+
+def main():
+    """Main entry point for the kokoro-tts CLI tool."""
+    # Define stdin indicators once (cross-platform)
+    stdin_indicators = ['/dev/stdin', '-', 'CONIN$']  # CONIN$ is Windows stdin
+    
+    # Validate command line arguments
     valid_options = get_valid_options()
-    unknown_options = []
 
     # Check for unknown options
-    i = 1
+    unknown_options = []
+    i = 0
     while i < len(sys.argv):
         arg = sys.argv[i]
-        if arg.startswith('--') or arg.startswith('-'):
-            # Check if it's a valid option
-            if arg not in valid_options:
-                unknown_options.append(arg)
+        if arg.startswith('--') and arg not in valid_options:
+            unknown_options.append(arg)
             # Skip the next argument if it's a value for an option that takes parameters
-            elif arg in {'--speed', '--lang', '--voice', '--split-output', '--format'}:
-                i += 1
+        elif arg in {'--speed', '--lang', '--voice', '--split-output', '--format'}:
+            i += 1
         i += 1
 
     # If unknown options were found, show error and help
@@ -1287,8 +1306,8 @@ def get_valid_options():
         print_usage()
         sys.exit(1)
 
-    # Ensure the input file exists
-    if not os.access(input_file, os.R_OK):
+    # Ensure the input file exists (skip check for stdin)
+    if input_file not in stdin_indicators and not os.access(input_file, os.R_OK):
         print(f"Error: Cannot read from {input_file}. File may not exist or you may not have permission to read it.")
         sys.exit(1)
 
@@ -1303,5 +1322,9 @@ def get_valid_options():
     # Convert text to audio with debug flag
     convert_text_to_audio(input_file, output_file, voice=voice, stream=stream, 
                          speed=speed, lang=lang, split_output=split_output, 
-                         format=format, debug=debug)
+                         format=format, debug=debug, stdin_indicators=stdin_indicators)
+
+
+if __name__ == '__main__':
+    main()
 

kokoro_tts/__main__.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+
+"""
+Entry point for running kokoro-tts as a module.
+This allows users to run: python -m kokoro_tts
+"""
+
+from . import main
+
+if __name__ == "__main__":
+    main()