Metadata-Version: 2.5
Name: huggingface-hub-rvc
Version: 0.1.4
Summary: Hugging Face Hub reader, writer, and runnable pipeline for RVC voice conversion models.
Project-URL: Homepage, https://github.com/SimpleTuner-io/huggingface-hub-rvc
Project-URL: Repository, https://github.com/SimpleTuner-io/huggingface-hub-rvc
Author: SimpleTuner Contributors
License-Expression: MIT
Keywords: huggingface,rvc,safetensors,voice-conversion
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.10
Requires-Dist: huggingface-hub>=0.24
Requires-Dist: librosa>=0.10.2
Requires-Dist: numpy>=1.24
Requires-Dist: packaging>=23
Requires-Dist: safetensors>=0.5
Requires-Dist: scipy>=1.11
Requires-Dist: torch>=2.1
Requires-Dist: torchaudio>=2.1
Requires-Dist: transformers>=4.40
Provides-Extra: dev
Requires-Dist: demucs>=4.0; extra == 'dev'
Requires-Dist: faiss-cpu>=1.8; extra == 'dev'
Requires-Dist: praat-parselmouth>=0.4.5; extra == 'dev'
Requires-Dist: pymss>=2.1.3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: torchfcpe>=0.0.4; extra == 'dev'
Provides-Extra: inference
Requires-Dist: demucs>=4.0; extra == 'inference'
Requires-Dist: faiss-cpu>=1.8; extra == 'inference'
Requires-Dist: praat-parselmouth>=0.4.5; extra == 'inference'
Requires-Dist: pymss>=2.1.3; extra == 'inference'
Requires-Dist: torchfcpe>=0.0.4; extra == 'inference'
Provides-Extra: pitch
Requires-Dist: praat-parselmouth>=0.4.5; extra == 'pitch'
Requires-Dist: torchfcpe>=0.0.4; extra == 'pitch'
Provides-Extra: retrieval
Requires-Dist: faiss-cpu>=1.8; extra == 'retrieval'
Provides-Extra: separation
Requires-Dist: demucs>=4.0; extra == 'separation'
Requires-Dist: pymss>=2.1.3; extra == 'separation'
Provides-Extra: train
Requires-Dist: demucs>=4.0; extra == 'train'
Requires-Dist: faiss-cpu>=1.8; extra == 'train'
Requires-Dist: praat-parselmouth>=0.4.5; extra == 'train'
Requires-Dist: pymss>=2.1.3; extra == 'train'
Requires-Dist: torchfcpe>=0.0.4; extra == 'train'
Description-Content-Type: text/markdown

# huggingface-hub-rvc

`huggingface-hub-rvc` provides a small Hugging Face style API for RVC voice conversion artifacts:

- `RVCPipeline.from_pretrained(...)`
- `RVCPipeline.save_pretrained(...)`
- `RVCPipeline.push_to_hub(...)`
- `RVCPipeline.export_webui(...)`
- `RVCPipeline.train(...)`
- `RVCPipeline.convert_file(...)`
- `RVCPipeline.convert_directory(...)`

Training currently produces RVC v2 F0 48 kHz models and stores new weights as safetensors. Inference also loads classic
RVC WebUI v1/v2, F0/non-F0, multi-speaker `.pth` checkpoints and their optional retrieval indexes with restricted
`weights_only=True` deserialization.

## Artifact Layout

```text
config.json
voice_transform/
  manifest.json
  model.safetensors
  features.safetensors
  index.index
```

`model.safetensors` contains the RVC generator weights plus string metadata for the RVC config and training summary.
`features.safetensors` contains retrieval vectors as tensor payload. `index.index` is the FAISS index and remains a separate binary file.
`config.json` includes `model_name`, which is also mirrored into `voice_transform/manifest.json` so the artifact remains identifiable even if it is downloaded into a generic cache or renamed folder.
`README.md` is generated as a Hub model card when `save_pretrained` writes the artifact.

Legacy `model.pth`, WebUI `.pth`, and `features.npy` artifacts can still be loaded. New writes prefer safetensors.

## Load

```python
from huggingface_hub_rvc import RVCPipeline

pipe = RVCPipeline.from_pretrained("org/rvc-model")
pipe.convert_directory(
    "input_audio",
    "converted_audio",
    pitch_shift=0,
    f0_method="rmvpe",  # rmvpe, fcpe, or pm
    protect=0.33,
    rms_mix_rate=1.0,
    retrieval_strength=0.75,
    speaker_id=0,
)
```

Use `local_files_only=True` to avoid network lookup:

```python
pipe = RVCPipeline.from_pretrained("./my-rvc-model", local_files_only=True)
```

The converter uses reflected context padding, low-energy chunk boundaries, and standard RVC consonant protection and
volume-envelope mixing. `audio_mode="separate_convert_remix"` supports `separation_method="pymss"` (default) or
`separation_method="demucs"`. CUDA Graph capture is opt-in with `use_cuda_graph=True` because its benefit depends on
input-shape reuse.

## Train

```python
from huggingface_hub_rvc import RVCPipeline

pipe = RVCPipeline.train(
    identity_dir="identity_audio",
    output_dir="rvc_artifact",
    model_name="Example Voice",
    training_steps=1000,
    identity_audio_mode="separate",
)
pipe.convert_directory("source_audio", "converted_audio")
```

Set `separation_method="demucs"` in `RVCPipeline.train(...)` to retain Demucs preprocessing instead of the default
PyMSS vocal separator. Already-isolated vocals should use `identity_audio_mode="vocal_only"`.

## Save And Push

```python
pipe.save_pretrained("rvc_artifact", model_name="Example Voice")
pipe.push_to_hub("org/rvc-model", folder_path="rvc_artifact")
```

or:

```python
pipe.save_pretrained("rvc_artifact", push_to_hub=True, repo_id="org/rvc-model")
```

Export a classic WebUI bundle when needed:

```python
pipe.export_webui("rvc_artifact/webui", model_name="Example Voice", training_steps=1000)
```
