Metadata-Version: 2.4
Name: vyonica-report
Version: 0.0.1
Summary: Objective voice-clone evaluation — metrics, graphs, and PDF reports. CLI + Python SDK.
Project-URL: Homepage, https://github.com/NexVoice/platform
Project-URL: Repository, https://github.com/NexVoice/platform
Author: NexVoice
License: MIT
Keywords: evaluation,metrics,speech,tts,voice-cloning,vyonica
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: faster-whisper>=1.2.1
Requires-Dist: jiwer>=4.0.0
Requires-Dist: librosa>=0.10.2
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: numpy<3,>=1.26.0
Requires-Dist: praat-parselmouth>=0.4.7
Requires-Dist: pyloudnorm>=0.2.0
Requires-Dist: reportlab>=4.5.1
Requires-Dist: scipy>=1.12.0
Requires-Dist: soundfile>=0.12.1
Requires-Dist: speechbrain>=1.1.0
Requires-Dist: torch>=2.12.0
Requires-Dist: torchaudio>=2.11.0
Requires-Dist: torchmetrics>=1.9.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# vyonica-report

Objective voice-clone evaluation — **CLI + Python SDK**.

Computes ~50 objective metrics across acoustic quality, prosody, speaker
identity, linguistic accuracy, and perceptual approximation. Emits:

- **CSV** (wide format) — stackable across many runs
- **PNG graphs** — waveform, pitch, energy, spectrogram, band energy
- **PDF report** — closeness score, verdict, all charts, metric evidence table

No LLM commentary. No database. No web server. Just metrics.

## Install

```bash
pip install vyonica-report
# or, from a local checkout:
pip install /path/to/trainer/voice-cloning-result-comp/vyonica_report
```

Python 3.11+ required. The first run downloads ~2 GB of ML model weights
(Whisper, ECAPA, NISQA, DNSMOS); subsequent runs are cached. Use `--no-heavy`
to skip those models and keep the run pure-DSP (~5 s).

## CLI

```bash
vyonica-report \
  --original ref.wav \
  --clone synth.wav \
  --transcript "The quick brown fox jumps over the lazy dog." \
  --language en \
  --output metrics.csv \
  --graphs graphs/ \
  --pdf report.pdf
```

| Flag | Default | Purpose |
| --- | --- | --- |
| `--language` | `en` | ISO 639-1 transcript language |
| `--output / -o` | `metrics.csv` | Wide-format CSV (one row per run) |
| `--graphs DIR` | — | Write diagnostic PNGs here |
| `--pdf PATH` | — | Write a PDF evaluation report here |
| `--run-id ID` | ISO timestamp | Label this row in the CSV |
| `--append` | off | Append a row instead of overwriting |
| `--no-heavy` | off | Skip Whisper / ECAPA / NISQA / DNSMOS / Praat |
| `--whisper-model` | `small` | Whisper size when heavy models are on |

## Python SDK

```python
from vyonica_report import (
    analyze,
    to_csv,
    plot_graphs,
    generate_pdf,
    closeness_score,
)

metrics, summary = analyze(
    original_path="ref.wav",
    clone_path="synth.wav",
    transcript="The quick brown fox jumps over the lazy dog.",
    language="en",
    enable_heavy_models=True,
)

print(f"Voice closeness: {closeness_score(metrics):.1f}%")

to_csv(metrics, "metrics.csv", run_id="experiment_42")
plot_graphs(summary, "graphs/")
generate_pdf(metrics, summary, "report.pdf", run_label="experiment_42")
```

Each `Metric` has `domain`, `name`, `value`, `unit`, `direction`
(`higher` / `lower` / `near_1` / `neutral`), `status`, and `note` fields.

## CSV format (wide)

One row per run; columns are `{domain_slug}__{metric_slug}`:

```
run_id,timestamp,acoustic_quality__log_spectral_distance,prosody__f0_contour_correlation,speaker_identity__mfcc_timbre_similarity,...
experiment_42,2026-05-23T11:22:33,2.31,0.87,0.91,...
```

Use `--append` to stack many runs into the same CSV.

## Building & publishing

From the package directory:

```bash
# build wheel + sdist into dist/
uv build                   # or: python -m build

# install the built wheel into another local repo for testing
pip install dist/vyonica_report-0.1.0-py3-none-any.whl

# publish to PyPI (requires a token from https://pypi.org/manage/account/token/)
pip install twine
twine upload dist/*
```
