### Install Project Dependencies Source: https://github.com/robviren/kvoicewalk/blob/main/README.md Clone the repository, navigate into the directory, set up a virtual environment, and install all necessary Python packages using uv. ```bash git clone https://github.com/RobViren/kvoicewalk.git cd kvoicewalk uv venv --python 3.10 source .venv/bin/activate # '.venv\Scripts\activate' if Windows uv sync ``` -------------------------------- ### Install KVoiceWalk and Dependencies Source: https://context7.com/robviren/kvoicewalk/llms.txt Clones the repository, sets up a virtual environment with Python 3.10, and installs dependencies. Includes verification for CUDA availability. ```bash git clone https://github.com/RobViren/kvoicewalk.git cd kvoicewalk uv venv --python 3.10 source .venv/bin/activate # Windows: .venv\Scripts\activate uv sync # Verify CUDA availability (optional but recommended) uv run python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.version.cuda)" ``` -------------------------------- ### Run KVoiceWalk CLI - Interpolated Start Source: https://github.com/robviren/kvoicewalk/blob/main/README.md Initiate KVoiceWalk with an interpolated start. This process searches for optimal starting voices for the random walk and saves them to an 'interpolated' folder. It also continues with a random walk afterwards. ```bash uv run main.py --target_text "The works the speaker says in the audio clip" --target_audio /path/to/target.wav --interpolate_start ``` -------------------------------- ### Launch KVoiceWalk GUI Source: https://github.com/robviren/kvoicewalk/blob/main/README.md Start the graphical user interface for KVoiceWalk. This is the recommended method for managing and running tasks. ```bash uv run gui.py ``` -------------------------------- ### Run KVoiceWalk with Interpolated Start Source: https://context7.com/robviren/kvoicewalk/llms.txt Enables the interpolated start mode, which systematically searches the embedding space between top stock voices before beginning the random walk. This can significantly improve the starting position. ```bash uv run main.py \ --target_text "The old lighthouse keeper never imagined that one day he'd be guiding ships." \ --target_audio ./example/target.wav \ --interpolate_start \ --population_limit 10 \ --device cuda ``` -------------------------------- ### KVoiceWalk Random Walk Console Output Example Source: https://context7.com/robviren/kvoicewalk/llms.txt Illustrates the expected console output during a random walk, showing improvements in target similarity, self-similarity, feature similarity, and overall score. ```text # Target Sim:0.709, Self Sim:0.978, Feature Sim:0.47, Score:81.22 # Step:42 Target Sim:0.741 Self Sim:0.975 Feature Sim:0.481 Score:83.10 Diversity:0.07 # Step:318 Target Sim:0.802 Self Sim:0.971 Feature Sim:0.510 Score:87.44 Diversity:0.03 # ... # Random Walk Final Results for my_cloned_voice # Duration: 14402.3 seconds # Best Score: 92.99_ # Best Similarity: 0.917_ # Random Walk pt and wav files ---> out/my_cloned_voice_target_20250410_120000 ``` -------------------------------- ### Run KVoiceWalk with Logging Control Source: https://github.com/robviren/kvoicewalk/blob/main/README.md This example demonstrates how to run KVoiceWalk with custom logging intervals for non-interactive processes. The `--log_interval` argument controls how often progress logs are emitted. ```bash uv run main.py --target_text "..." --target_audio ./example/target.wav --device cuda --step_limit 10000 --log_interval 100 ``` -------------------------------- ### KVoiceWalk Interpolation Phase Console Output Example Source: https://context7.com/robviren/kvoicewalk/llms.txt Shows console output during the interpolation phase, detailing the scores of stock voices and the process of interpolating between them. ```text # af_heart.pt Target Sim: 0.709, Self Sim: 0.978, Feature Sim: 0.47, Score: 81.22 # ... # Top Performers: # af_heart.pt Target Sim: 0.709, ... # Interpolating Best Voices: # 0 1 -1.50 af_heart af_jessica Target Sim:0.721 ... # ... # Interpolated voices saved to ./interpolated/ ``` -------------------------------- ### Initialize and Run KVoiceWalk Orchestration Source: https://context7.com/robviren/kvoicewalk/llms.txt Instantiate the `KVoiceWalk` class with various parameters for target audio, text, voice folder, and generation settings. Then, initiate the random walk process. ```python from pathlib import Path from utilities.kvoicewalk import KVoiceWalk ktb = KVoiceWalk( target_audio=Path("./example/target.wav"), target_text="The old lighthouse keeper never imagined that one day he'd be guiding ships.", other_text="If you mix vinegar, baking soda, and dish soap in a tall cylinder, the eruption is delightful.", voice_folder="./voices", interpolate_start=False, # True to run interpolation phase first population_limit=10, starting_voice=None, # Path str to a .pt file, or None to use population mean output_name="my_voice", device="cuda", # "auto" | "cpu" | "cuda" ) # Run the walk — saves every improvement to ./out/my_voice_target_/ ktb.random_walk(step_limit=10000, log_interval=100) ``` -------------------------------- ### Initialize FitnessScorer and Evaluate Voice Quality Source: https://context7.com/robviren/kvoicewalk/llms.txt Instantiate `FitnessScorer` with the target audio path and device. Use its methods to calculate individual metrics like target similarity, self-similarity, and feature penalty, or a full hybrid score. ```python from utilities.fitness_scorer import FitnessScorer import numpy as np import soundfile as sf scorer = FitnessScorer(target_path="./example/target.wav", device="cuda") # Load two audio clips synthesized from the same voice tensor audio1, _ = sf.read("./out/candidate.wav", dtype="float32") audio2, _ = sf.read("./out/candidate_other_text.wav", dtype="float32") # Individual metrics t_sim = scorer.target_similarity(audio1) # float — cosine similarity to target embedding s_sim = scorer.self_similarity(audio1, audio2) # float — cross-text speaker stability features = scorer.extract_features(audio1) # dict with ~80 keys (MFCCs, spectral, pitch, etc.) penalty = scorer.target_feature_penalty(features) # float — summed normalized feature deviation # Full hybrid score (all three combined) results = scorer.hybrid_similarity(audio1, audio2, target_similarity=t_sim) # { # "score": 85.34, # "target_similarity": 0.741, # "self_similarity": 0.975, # "feature_similarity": 0.512 # } print(results) ``` -------------------------------- ### Run KVoiceWalk Random Walk (Basic) Source: https://context7.com/robviren/kvoicewalk/llms.txt Executes the core voice-evolution loop using auto device selection (CUDA or CPU) with a target audio file and text prompt. ```bash uv run main.py \ --target_text "The old lighthouse keeper never imagined that one day he'd be guiding ships from the comfort of his living room, but with modern technology and an array of cameras, he did just that." \ --target_audio ./example/target.wav ``` -------------------------------- ### Run KVoiceWalk Random Walk (Full GPU with Custom Limits) Source: https://context7.com/robviren/kvoicewalk/llms.txt Performs a voice evolution run utilizing the GPU, with specified limits for steps and population, and a custom log interval. Output is named 'my_cloned_voice'. ```bash uv run main.py \ --target_text "The old lighthouse keeper never imagined that one day he'd be guiding ships." \ --target_audio ./example/target.wav \ --device cuda \ --step_limit 10000 \ --population_limit 10 \ --log_interval 100 \ --output_name my_cloned_voice ``` -------------------------------- ### Initialize and Use InitialSelector Source: https://context7.com/robviren/kvoicewalk/llms.txt Initializes `InitialSelector` to score voice files and select top candidates. Use `top_performer_start` for fast selection or `interpolate_search` for exploring interpolations between voices. Requires target audio, text, and a voice folder. ```python from utilities.initial_selector import InitialSelector, interpolate selector = InitialSelector( target_path="./example/target.wav", target_text="The old lighthouse keeper...", other_text="If you mix vinegar...", voice_folder="./voices", device="cuda", ) # Simple top-N selection (fast) top_voices = selector.top_performer_start(population_limit=10) # Prints per-voice scores, returns list of torch.Tensor # Interpolation search (slow but finds better starting points) interpolated = selector.interpolate_search(population_limit=10) # Saves best interpolated tensors to ./interpolated/ and returns them as tensors # Direct interpolation helper import torch v1 = torch.load("./voices/af_heart.pt", weights_only=True) v2 = torch.load("./voices/af_jessica.pt", weights_only=True) mid = interpolate(v1, v2, alpha=0.1) # midpoint + diff_vector * alpha/2 ``` -------------------------------- ### Run KVoiceWalk with Device Selection Source: https://github.com/robviren/kvoicewalk/blob/main/README.md Use this command to specify the device for KVoiceWalk operations. Valid options are 'auto', 'cpu', and 'cuda'. The application will fallback to CPU if CUDA is requested but unavailable. ```bash uv run main.py --target_text "..." --target_audio /path/to/target.wav --device cuda ``` -------------------------------- ### Run KVoiceWalk Random Walk (Resume from Tensor) Source: https://context7.com/robviren/kvoicewalk/llms.txt Resumes a voice evolution process from a previously saved voice tensor, continuing the random walk from that specific point. ```bash uv run main.py \ --target_text "The old lighthouse keeper..." \ --target_audio ./example/target.wav \ --starting_voice ./out/my_cloned_voice_target_20250410_120000/my_cloned_voice_4200_89.50_0.91_target.pt \ --device cuda ``` -------------------------------- ### Run KVoiceWalk CLI - Random Walk Source: https://github.com/robviren/kvoicewalk/blob/main/README.md Execute a random walk for voice cloning using the command-line interface. Specify target text, audio, device, and logging interval. ```bash uv run main.py --target_text "The old lighthouse keeper never imagined that one day he'd be guiding ships from the comfort of his living room, but with modern technology and an array of cameras, he did just that, sipping tea while the storm raged outside and gulls shrieked overhead." --target_audio ./example/target.wav --device cuda --log_interval 100 ``` -------------------------------- ### Transcribe Audio with Faster-Whisper Source: https://context7.com/robviren/kvoicewalk/llms.txt Use `--transcribe_start` to automatically transcribe a target WAV file using Faster-Whisper large-v3. The transcription is saved to `./texts/.txt` for later reuse. ```bash uv run main.py \ --target_text "placeholder" \ --target_audio ./example/target.wav \ --transcribe_start \ --device cuda ``` ```bash # Then reuse the saved transcription: uv run main.py \ --target_text ./texts/target.txt \ --target_audio ./example/target.wav \ --device cuda ``` -------------------------------- ### Initialize VoiceGenerator with Seed Voices Source: https://context7.com/robviren/kvoicewalk/llms.txt Create a `VoiceGenerator` instance by providing a list of seed voice tensors and specifying the device. The generator uses these voices to produce new candidate voice tensors. ```python import torch from utilities.voice_generator import VoiceGenerator # Load population of seed voices voices = [torch.load(f"./voices/af_{name}.pt", weights_only=True) for name in ["heart", "bella", "sarah", "jessica"]] gen = VoiceGenerator(voices=voices, starting_voice=None, device="cuda") ``` -------------------------------- ### Run KVoiceWalk CLI - Test Voice Source: https://github.com/robviren/kvoicewalk/blob/main/README.md Use the CLI to generate audio from a provided voice tensor file and target text. The output will be saved as out.wav. ```bash uv run main.py --test_voice /path/to/voice.pt --target_text "Your really awesome text you want spoken" ``` -------------------------------- ### VoiceLoader.load_multiple_voices Source: https://context7.com/robviren/kvoicewalk/llms.txt Loads multiple Kokoro `.pt` voice files, managing shared prompt state. ```APIDOC ## load_multiple_voices ### Description Loads multiple Kokoro `.pt` voice files, sharing interactive prompt state. ### Method `load_multiple_voices(file_paths, auto_allow_unsafe)` ### Parameters - **file_paths** (list[str]) - A list of paths to `.pt` voice files. - **auto_allow_unsafe** (bool) - If True, bypasses all prompts for unsafe files. ### Returns - (dict) A dictionary mapping file names to loaded voice tensors. ``` -------------------------------- ### Verify CUDA Availability Source: https://github.com/robviren/kvoicewalk/blob/main/README.md After synchronizing dependencies, use this command to confirm that CUDA is accessible to PyTorch. This is crucial for GPU acceleration. ```bash uv run python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.version.cuda)" ``` -------------------------------- ### VoiceLoader.load_voice_safely Source: https://context7.com/robviren/kvoicewalk/llms.txt Safely loads a Kokoro `.pt` voice file with multiple fallback mechanisms. ```APIDOC ## load_voice_safely ### Description Safely loads a Kokoro `.pt` voice file, with interactive prompts for unsafe files. ### Method `load_voice_safely(file_path, auto_allow_unsafe)` ### Parameters - **file_path** (str) - The path to the `.pt` voice file. - **auto_allow_unsafe** (bool) - If True, bypasses all prompts for unsafe files. ``` -------------------------------- ### Convert Audio to 24kHz Mono WAV Source: https://context7.com/robviren/kvoicewalk/llms.txt The `convert_to_wav_mono_24k` function normalizes any audio file to the 24 kHz mono WAV format required by Kokoro and Resemblyzer. It automatically resamples and downmixes, and no action is taken if the file already matches the specification. Converted files are saved in the `./out/converted_audio/` directory. ```python from pathlib import Path from utilities.audio_processor import convert_to_wav_mono_24k out_path = convert_to_wav_mono_24k(Path("./my_stereo_44k.wav")) # "Converting my_stereo_44k.wav to Mono Wav 24K..." # "Cenverted to Mono..." # "Resampled to 24K..." # "my_stereo_44k.wav successfully converted to Mono WAV 24K format: out/converted_audio/my_stereo_44k.wav" print(out_path) # PosixPath('out/converted_audio/my_stereo_44k.wav') ``` -------------------------------- ### Safely Load Voice Files Source: https://context7.com/robviren/kvoicewalk/llms.txt Provides `load_voice_safely` for single voice files and `load_multiple_voices` for batches. These utilities prioritize safe loading by attempting `weights_only=True` first, then other methods, with interactive prompts for potentially unsafe files unless `auto_allow_unsafe` is set to `True`. ```python from utilities.pytorch_sanitizer import load_voice_safely, load_multiple_voices import os # Load a single voice — interactive prompt on unsafe files voice = load_voice_safely("./voices/af_heart.pt") # OK: Safely loaded ./voices/af_heart.pt with weights_only=True # Returns: torch.Tensor of shape [1, 256] # Load multiple voices (shared prompt state) file_paths = [os.path.join("./voices", f) for f in os.listdir("./voices") if f.endswith(".pt")] voices_dict = load_multiple_voices( file_paths, auto_allow_unsafe=False, # True to bypass all prompts ) # voices_dict: {"af_heart.pt": tensor, "af_bella.pt": tensor, ...} print(f"Loaded {len(voices_dict)} voices") ``` -------------------------------- ### KVoiceWalk Test Voice Mode Output Source: https://context7.com/robviren/kvoicewalk/llms.txt Indicates that the synthesized audio file 'preview.wav' has been written to the current directory. ```text # Output: preview.wav written to the current directory ``` -------------------------------- ### Export Voices to Bin Archive Source: https://context7.com/robviren/kvoicewalk/llms.txt Use `--export_bin` to package all `.pt` voice files from a specified folder into a single `voices.bin` NumPy `.npz` archive. ```bash uv run main.py --voices_folder ./voices --export_bin # Output: voices.bin in the current directory ``` -------------------------------- ### Convert Audio to Target Format Source: https://github.com/robviren/kvoicewalk/blob/main/README.md Use ffmpeg to convert input audio files to the required Mono 24000 Hz WAV format for KVoiceWalk processing. ```bash ffmpeg -i input_file.wav -ar 24000 target.wav ``` -------------------------------- ### Export Voice Models Source: https://github.com/robviren/kvoicewalk/blob/main/README.md Export all .pt voice models from a specified folder into a single 'voices.bin' file within the same folder. ```bash uv run main.py --voices_folder ./voices --export_bin ``` -------------------------------- ### Transcribe Audio to Text Source: https://github.com/robviren/kvoicewalk/blob/main/README.md Use Faster-Whisper to transcribe audio files and update target text. Transcriptions are saved as .txt files in the ./texts folder. ```bash uv run main.py --target_text "This text will be replaced!" --target_audio /path/to/target.wav --transcribe_start ``` ```bash uv run main.py --target_text /path/to/your/transcribed.txt --target_audio /path/to/target.wav ``` -------------------------------- ### Batch Transcribe Audio Files Source: https://context7.com/robviren/kvoicewalk/llms.txt Use `--transcribe_many` to batch-transcribe WAV files. It can process a single file or an entire directory, saving output to `./texts/.txt` for each file. ```bash # Single file uv run main.py --transcribe_many ./example/target.wav ``` ```bash # Entire folder uv run main.py --transcribe_many /path/to/audio/folder/ ``` -------------------------------- ### Test KVoiceWalk Voice Tensor Source: https://context7.com/robviren/kvoicewalk/llms.txt Synthesizes audio from a specified voice tensor and text prompt without running a full walk. Useful for auditing or previewing saved voice tensors. ```bash uv run main.py \ --test_voice ./voices/af_heart.pt \ --target_text "Hello, this is a quick test of the voice tensor." \ --output_name preview \ --device cuda ``` -------------------------------- ### InitialSelector Source: https://context7.com/robviren/kvoicewalk/llms.txt Scores audio files and selects top-N tensors for voice generation, with an option for interpolation search. ```APIDOC ## InitialSelector ### Description Scores `.pt` files in a voice folder and returns top-N tensors. Optionally explores interpolations between voice pairs. ### Initialization `selector = InitialSelector(target_path, target_text, other_text, voice_folder, device)` ### Methods - `top_performer_start(population_limit)`: Selects top-N performers. - `interpolate_search(population_limit)`: Explores interpolations between voice pairs. ``` ```APIDOC ## interpolate ### Description Helper function to create an interpolated voice tensor. ### Method `interpolate(v1, v2, alpha)` ### Parameters - **v1** (torch.Tensor) - The first voice tensor. - **v2** (torch.Tensor) - The second voice tensor. - **alpha** (float) - Interpolation factor. ``` -------------------------------- ### convert_to_wav_mono_24k Source: https://context7.com/robviren/kvoicewalk/llms.txt Normalizes an audio file to 24 kHz mono WAV format. ```APIDOC ## convert_to_wav_mono_24k ### Description Normalizes any audio file to the 24 kHz mono WAV format. ### Method `convert_to_wav_mono_24k(audio_path)` ### Parameters - **audio_path** (Path) - The path to the audio file to convert. ### Returns - (Path) The path to the converted WAV file. ``` -------------------------------- ### Transcribe Multiple Audio Files Source: https://github.com/robviren/kvoicewalk/blob/main/README.md Transcribe single WAV files or all WAV files within a folder. Transcriptions are saved as individual .txt files in the ./texts folder. ```bash uv run main.py --target_audio /path/to/target.wav --transcribe_many ``` ```bash uv run main.py --target_audio /path/to/audio/Folder/ --transcribe_many ``` -------------------------------- ### Resolve Compute Device Source: https://context7.com/robviren/kvoicewalk/llms.txt Resolves the effective compute device, falling back to CPU if CUDA is requested but unavailable. Use 'auto' for automatic selection, 'cuda' to force CUDA with a warning if unavailable, or 'cpu' to force CPU. ```python from utilities.device_utils import resolve_device resolve_device("auto") # "cuda" if torch.cuda.is_available() else "cpu" resolve_device("cuda") # "cuda" or "cpu" with a printed warning resolve_device("cpu") # "cpu" ``` -------------------------------- ### Transcribe Audio with Transcriber Source: https://context7.com/robviren/kvoicewalk/llms.txt Utilizes `Transcriber` with Faster-Whisper large-v3 to transcribe WAV files to text. It automatically selects the best compute device (CUDA or CPU) and saves transcriptions to the `./texts/` directory. The transcription and timing are printed to the console. ```python from pathlib import Path from utilities.audio_processor import Transcriber transcriber = Transcriber(device="cuda") text = transcriber.transcribe(audio_path=Path("./example/target.wav")) # Prints detected language, transcription, timing # Saves ./texts/target.txt # Returns: "The old lighthouse keeper..." print(text) ``` -------------------------------- ### Synthesize Audio with SpeechGenerator Source: https://context7.com/robviren/kvoicewalk/llms.txt Uses `SpeechGenerator` to synthesize audio from text and a voice tensor or file path. The generated audio is a NumPy array at 24 kHz. Requires `soundfile` for writing to WAV. ```python import soundfile as sf import torch from utilities.speech_generator import SpeechGenerator gen = SpeechGenerator(device="cuda") # From a tensor voice = torch.load("./voices/af_heart.pt", weights_only=True) audio = gen.generate_audio( text="Hello, world! This is synthesized with KVoiceWalk.", voice=voice, speed=1.0, ) # audio: np.ndarray float32 at 24 kHz sf.write("output.wav", audio, 24000) # From a .pt file path audio2 = gen.generate_audio( text="Testing voice from file path.", voice="./voices/af_bella.pt", ) sf.write("output2.wav", audio2, 24000) ``` -------------------------------- ### Score a Single Voice Tensor with KVoiceWalk Source: https://context7.com/robviren/kvoicewalk/llms.txt Directly score a voice tensor using the `KVoiceWalk` class's `score_voice` method. This method returns a dictionary containing audio, score, and similarity metrics. ```python # Score a single tensor directly import torch voice_tensor = torch.load("./voices/af_heart.pt", weights_only=True) results = ktb.score_voice(voice_tensor) # results = { # "audio": np.ndarray, # synthesized float32 audio at 24 kHz # "score": 81.22, # "target_similarity": 0.709, # "self_similarity": 0.978, # "feature_similarity": 0.470 # } print(f"Score: {results['score']:.2f}, Target Sim: {results['target_similarity']:.3f}") ``` -------------------------------- ### Generate Mutated Voice Candidate Source: https://context7.com/robviren/kvoicewalk/llms.txt Generates a mutated voice candidate using a base tensor and diversity parameters. The `clip` parameter controls clamping to population min/max. ```python print(gen.starting_voice.shape) # torch.Size([1, 256]) — typical Kokoro style tensor # Generate a mutated candidate candidate = gen.generate_voice( base_tensor=gen.starting_voice, diversity=0.05, # 0.01–0.15 typical range used by the walk clip=False, # True clamps to population min/max ) print(candidate.shape) # torch.Size([1, 256]) ``` -------------------------------- ### Transcriber.transcribe Source: https://context7.com/robviren/kvoicewalk/llms.txt Transcribes an audio file to text using Faster-Whisper. ```APIDOC ## Transcriber.transcribe ### Description Transcribes an audio file to text using Faster-Whisper. ### Method `transcriber.transcribe(audio_path)` ### Parameters - **audio_path** (Path) - The path to the audio file to transcribe. ### Returns - (str) The transcribed text. ``` -------------------------------- ### SpeechGenerator.generate_audio Source: https://context7.com/robviren/kvoicewalk/llms.txt Synthesizes audio from a text string using a provided voice tensor or file path. ```APIDOC ## SpeechGenerator.generate_audio ### Description Synthesizes audio from text using a specified voice. ### Method `gen.generate_audio(text, voice, speed)` ### Parameters - **text** (str) - The text to synthesize. - **voice** (torch.Tensor or str) - The voice tensor or path to a `.pt` voice file. - **speed** (float) - The speech speed multiplier. Defaults to 1.0. ``` -------------------------------- ### SpeechGenerator.generate_voice Source: https://context7.com/robviren/kvoicewalk/llms.txt Generates a mutated voice candidate tensor based on a base tensor, with adjustable diversity and clipping options. ```APIDOC ## generate_voice ### Description Generates a mutated voice candidate tensor. ### Method `gen.generate_voice(base_tensor, diversity, clip)` ### Parameters - **base_tensor** (torch.Tensor) - The base tensor to mutate. - **diversity** (float) - Controls the degree of mutation. Typical range: 0.01–0.15. - **clip** (bool) - If True, clamps the output to population min/max. ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.