KVoiceWalk

To evolve a new voice tensor to match a target audio file using the random walk algorithm, use main.py with the --target_audio and --target_text arguments.

Important Audio Requirement: Target audio files must be Mono 24000 Hz WAV (approximately 20-30 seconds of a single speaker). If your file is not in this format, convert it using ffmpeg:

ffmpeg -i input_file.wav -ar 24000 target.wav

Example Command:

uv run main.py --target_text "Your target text here" --target_audio ./example/target.wav --device cuda --log_interval 100

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

General Arguments

• --target_text (str): The words in the target audio (100-200 tokens). Can be a path to a .txt file.
• --other_text (str): Text used to compare self-similarity. Default: "If you mix vinegar, baking soda, and a bit of dish soap..."
• --voice_folder (str): Path to voices used in the random walk. Default: ./voices
• --transcribe_start: Transcribes target WAV and replaces --target_text.
• --interpolate_start: Performs interpolation search before random walking.
• --population_limit (int): Limits voices used in random walk. Default: 10
• --step_limit (int): Limits random walk steps. Default: 10000
• --output_name (str): Filename for generated audio. Default: out.wav

Random Walk Mode

• --target_audio (str): Path to target 24000 Hz mono WAV file.
• --starting_voice (str): Path to the starting voice tensor.

Test Mode

• --test_voice (str): Path to the voice tensor to test.

Utility Mode

• --export_bin: Exports voices in --voices_folder to voices.bin.
• --transcribe_many: Transcribes a WAV file or folder to ./texts.

GPU / CUDA

• --device (str): Selection for Kokoro, Resemblyzer, and Faster-Whisper. Options: auto (default), cpu, cuda. Falls back to CPU if CUDA is requested but unavailable.

The core functionality of the project is the KVoiceWalk class, which implements the random walk algorithm to find a voice tensor that matches a target audio's characteristics.

Key Parameters for KVoiceWalk:

• target_audio: Path to the target audio file.
• target_text: The transcription of the target audio.
• other_text: Text used for similarity comparison.
• voice_folder: Directory containing available voice tensors.
• interpolate_start: Boolean; if true, performs interpolation before walking.
• population_limit: Integer; limits the number of voices used.
• starting_voice: Path to an initial voice tensor.
• output_name: Filename for the resulting audio.
• device: Execution device (auto, cpu, or cuda).

To execute the walk, call the .random_walk(step_limit, log_interval) method.

from utilities.kvoicewalk import KVoiceWalk

ktb = KVoiceWalk(
    target_audio="path/to/audio.wav",
    target_text="The transcription text",
    other_text="Similarity comparison text",
    voice_folder="./voices",
    interpolate_start=True,
    population_limit=10,
    starting_voice="path/to/start.pt",
    output_name="output.wav",
    device="cuda"
)
ktb.random_walk(step_limit=1000, log_interval=100)

The following arguments are available for the KVoiceWalk CLI. Note that some arguments are grouped by mode.

### Common required arguments
--target_text [str]: The words contained in the target audio file (100-200 tokens). Can be a path to a .txt file.

### Optional arguments
--other_text [str]: Text used to compare self-similarity (default: provided volcanic activity text).
--voice_folder [str]: Path to the voices used in the random walk (default: ./voices).
--transcribe_start: Transcribes a target wav/folder and replaces --target_text.
--interpolate_start: Performs an interpolation search step before random walking.
--population_limit [int]: Limits voices used in the walk (default: 10).
--step_limit [int]: Limits steps in the walk (default: 10000).
--log_interval [int]: Frequency of progress logs (default: 100).
--output_name [str]: Filename for generated audio (default: my_new_voice).
--device [auto|cpu|cuda]: Execution device (default: auto).

### Random Walk Mode
--target_audio [str]: Path to target 24000 Hz mono wav file.
--starting_voice [str]: Path to the starting voice tensor.

### Test Mode
--test_voice [str]: Path to the voice tensor to test.

### Utility Mode
--export_bin: Exports target voices in --voice_folder to voices.bin.
--transcribe_many: Transcribes a wav file or folder to the ./texts folder.

KVoiceWalk can be executed from the command line to perform voice cloning using a random walk algorithm. The CLI supports several modes: Random Walk Mode (the primary use case), Test Mode (to test a specific voice tensor), and Utility Mode (for exporting voice binaries or batch transcribing audio).

Random Walk Mode

To perform a random walk to clone a voice, you must provide a target audio file and the corresponding transcription text.

python main.py --target_audio path/to/target.wav --target_text "The transcription of the audio" --voice_folder ./my_voices

Test Mode

Use this mode to verify a specific voice tensor by generating speech from a text string.

python main.py --test_voice path/to/voice.pt --target_text "Text to speak" --output_name result.wav

Utility Mode

• Export Binaries: Consolidate all .pt files in a folder into a single voices.bin file.
• Batch Transcription: Transcribe a single .wav file or an entire directory of .wav files into text files in the ./texts folder.