vcref 0.1.0__tar.gz

vcref-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+node_modules/
+*.tmp
+_js.vcref
+js-packed.vcref

vcref-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bhavya091213
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vcref-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: vcref
+Version: 0.1.0
+Summary: Read, write and verify .vcref voice reference bundles for zero-shot voice-cloning TTS.
+Project-URL: Homepage, https://github.com/bhavya091213/vcref
+License: MIT
+License-File: LICENSE
+Keywords: audio,speech,tts,vcref,voice-cloning
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.9
+Provides-Extra: audio
+Requires-Dist: numpy; extra == 'audio'
+Requires-Dist: soundfile>=0.12; extra == 'audio'
+Description-Content-Type: text/markdown
+
+# vcref (Python)
+
+Read, write and verify `.vcref` voice reference bundles. Format: [SPEC.md](https://github.com/bhavya091213/vcref/blob/main/SPEC.md).
+
+```
+pip install vcref            # no dependencies
+pip install "vcref[audio]"   # + soundfile/numpy: decode clips to arrays, pack from WAV/ndarray
+```
+
+```python
+import vcref
+
+with vcref.Bundle("dean.vcref") as b:          # path, bytes or file object
+    b.name, b.default, b.tags, b.config, b.cadence, b.id
+    b.verify()                                  # SHA-256 of every clip and part
+    tag = b.select_tag("Really?")               # first matching rule, else the default
+    clip = b.clip(tag)                          # Clip(tag, text, seconds, label, sample_rate, flac)
+    audio, sr = b.read(tag)                     # float32 array (needs the audio extra)
+    b.unpack("out/")                            # <tag>.flac + <tag>.txt (wav=True for WAV)
+
+vcref.pack("voice.vcref",
+           {"neutral": {"wav": "neutral.wav", "text": "What is said in the clip."},
+            "question": {"flac": flac_bytes, "text": "Is it?"}},
+           name="voice", rules=[{"pattern": r"\?\s*$", "tag": "question"}], config={"engine": "voxcpm"})
+
+vcref.set_cadence("voice.vcref", cadence_dict)  # rewrite only the cadence block
+```
+
+Errors are `vcref.VcrefError`. Command line: `vcref info|verify <file>`, `vcref unpack <file> <dir> [--wav]`.

vcref-0.1.0/README.md

@@ -0,0 +1,29 @@
+# vcref (Python)
+
+Read, write and verify `.vcref` voice reference bundles. Format: [SPEC.md](https://github.com/bhavya091213/vcref/blob/main/SPEC.md).
+
+```
+pip install vcref            # no dependencies
+pip install "vcref[audio]"   # + soundfile/numpy: decode clips to arrays, pack from WAV/ndarray
+```
+
+```python
+import vcref
+
+with vcref.Bundle("dean.vcref") as b:          # path, bytes or file object
+    b.name, b.default, b.tags, b.config, b.cadence, b.id
+    b.verify()                                  # SHA-256 of every clip and part
+    tag = b.select_tag("Really?")               # first matching rule, else the default
+    clip = b.clip(tag)                          # Clip(tag, text, seconds, label, sample_rate, flac)
+    audio, sr = b.read(tag)                     # float32 array (needs the audio extra)
+    b.unpack("out/")                            # <tag>.flac + <tag>.txt (wav=True for WAV)
+
+vcref.pack("voice.vcref",
+           {"neutral": {"wav": "neutral.wav", "text": "What is said in the clip."},
+            "question": {"flac": flac_bytes, "text": "Is it?"}},
+           name="voice", rules=[{"pattern": r"\?\s*$", "tag": "question"}], config={"engine": "voxcpm"})
+
+vcref.set_cadence("voice.vcref", cadence_dict)  # rewrite only the cadence block
+```
+
+Errors are `vcref.VcrefError`. Command line: `vcref info|verify <file>`, `vcref unpack <file> <dir> [--wav]`.

vcref-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vcref"
+version = "0.1.0"
+description = "Read, write and verify .vcref voice reference bundles for zero-shot voice-cloning TTS."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["tts", "voice-cloning", "speech", "audio", "vcref"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+
+[project.optional-dependencies]
+audio = ["soundfile>=0.12", "numpy"]
+
+[project.scripts]
+vcref = "vcref.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/bhavya091213/vcref"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vcref"]

vcref-0.1.0/src/vcref/__init__.py

@@ -0,0 +1,5 @@
+"""vcref: read, write and verify .vcref voice reference bundles (format spec: SPEC.md)."""
+from .bundle import MAGIC, VERSION, Bundle, Clip, VcrefError, pack, set_cadence
+
+__all__ = ["Bundle", "Clip", "VcrefError", "pack", "set_cadence", "MAGIC", "VERSION"]
+__version__ = "0.1.0"

vcref-0.1.0/src/vcref/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

vcref-0.1.0/src/vcref/bundle.py

@@ -0,0 +1,225 @@
+"""The .vcref container. Standard library only; decoding audio to arrays needs the optional `audio` extra."""
+import hashlib
+import io
+import json
+import re
+import struct
+import time
+import zipfile
+from collections import namedtuple
+from pathlib import Path
+
+MAGIC = b"VCREF1"
+VERSION = 1
+_TAG = re.compile(r"^[A-Za-z0-9_-]+$")
+
+Clip = namedtuple("Clip", "tag text seconds label sample_rate flac")
+
+
+class VcrefError(Exception):
+    pass
+
+
+def _sha(b):
+    return hashlib.sha256(b).hexdigest()
+
+
+def _check_tag(tag):
+    if not _TAG.match(tag):
+        raise VcrefError(f"bad tag {tag!r}: use letters, digits, '_' or '-'")
+
+
+def _soundfile():
+    try:
+        import soundfile as sf
+    except ImportError:
+        raise VcrefError("this needs the audio extra: pip install 'vcref[audio]'")
+    return sf
+
+
+def _flac_rate(data):
+    if data[:4] != b"fLaC":
+        raise VcrefError("flac bytes do not start with 'fLaC'")
+    return (struct.unpack(">I", data[18:22])[0] >> 12) & 0xFFFFF  # STREAMINFO sample rate (20 bits)
+
+
+def pack(out, clips, name=None, default=None, rules=None, config=None, cadence=None, parts=None):
+    """Write a bundle and return its path.
+
+    clips  {tag: {"text": str, plus one of "flac": bytes | "wav": path | "audio": (ndarray, sr),
+                  optional "label", "source"}}
+           "wav"/"audio" are encoded to 24-bit FLAC (needs vcref[audio]); "flac" bytes are stored as given.
+    parts  {name: same audio keys}   optional full enrollment recordings
+    """
+    if not clips:
+        raise VcrefError("a bundle needs at least one clip")
+    out = Path(out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    def to_flac(spec):
+        if "flac" in spec:
+            data = bytes(spec["flac"])
+            return data, _flac_rate(data), spec.get("seconds")
+        sf = _soundfile()
+        if "wav" in spec:
+            x, sr = sf.read(spec["wav"], dtype="float32")
+        elif "audio" in spec:
+            x, sr = spec["audio"]
+        else:
+            raise VcrefError("each clip needs 'flac', 'wav' or 'audio'")
+        buf = io.BytesIO()
+        sf.write(buf, x, sr, format="FLAC", subtype="PCM_24")
+        return buf.getvalue(), int(sr), round(len(x) / sr, 2)
+
+    tmp = out.with_suffix(out.suffix + ".tmp")
+    mclips, mparts = {}, {}
+    with zipfile.ZipFile(tmp, "w", zipfile.ZIP_STORED) as z:
+        z.comment = MAGIC
+        for tag, spec in clips.items():
+            _check_tag(tag)
+            if not spec.get("text"):
+                raise VcrefError(f"clip {tag!r} has no transcript text")
+            data, sr, secs = to_flac(spec)
+            z.writestr(f"clips/{tag}.flac", data)
+            entry = {"file": f"clips/{tag}.flac", "text": spec["text"], "seconds": secs, "label": spec.get("label"),
+                     "source": spec.get("source"), "sample_rate": sr, "sha256": _sha(data)}
+            mclips[tag] = {k: v for k, v in entry.items() if v is not None}
+        for pname, spec in (parts or {}).items():
+            _check_tag(pname)
+            data, sr, secs = to_flac(spec)
+            z.writestr(f"parts/{pname}.flac", data)
+            entry = {"file": f"parts/{pname}.flac", "seconds": secs, "sha256": _sha(data)}
+            mparts[pname] = {k: v for k, v in entry.items() if v is not None}
+        default = default or ("neutral" if "neutral" in mclips else next(iter(mclips)))
+        if default not in mclips:
+            raise VcrefError(f"default {default!r} is not a clip")
+        for r in rules or []:
+            re.compile(r["pattern"])  # fail now, not at read time
+            if r["tag"] not in mclips:
+                raise VcrefError(f"rule tag {r['tag']!r} is not a clip")
+        manifest = {"format": "vcref", "version": VERSION, "name": name or out.stem, "created": time.strftime("%Y-%m-%d"),
+                    "default": default, "clips": mclips, "rules": rules or [], "config": config or {}, "parts": mparts}
+        if cadence:
+            manifest["cadence"] = cadence
+        z.writestr("manifest.json", json.dumps(manifest, indent=1, ensure_ascii=False))
+    tmp.replace(out)
+    return out
+
+
+class Bundle:
+    """Open a bundle from a path, bytes or a binary file object."""
+
+    def __init__(self, source):
+        if isinstance(source, (bytes, bytearray)):
+            source = io.BytesIO(source)
+        try:
+            self._z = zipfile.ZipFile(source)
+        except (zipfile.BadZipFile, FileNotFoundError) as e:
+            raise VcrefError(f"not a readable vcref ({e})")
+        self.path = Path(source) if isinstance(source, (str, Path)) else None
+        if self._z.comment != MAGIC:
+            raise VcrefError("not a vcref file (bad magic)")
+        try:
+            m = json.loads(self._z.read("manifest.json"))
+        except (KeyError, ValueError) as e:
+            raise VcrefError(f"bad manifest.json ({e})")
+        if m.get("format") != "vcref" or m.get("version", 0) > VERSION:
+            raise VcrefError(f"unsupported vcref version {m.get('version')}")
+        if m.get("default") not in m.get("clips", {}):
+            raise VcrefError("manifest default is not a clip")
+        self.manifest = m
+
+    def _read(self, name):
+        try:
+            return self._z.read(name)
+        except KeyError:
+            raise VcrefError(f"missing entry {name}")
+        except zipfile.BadZipFile as e:
+            raise VcrefError(f"corrupt entry {name} ({e})")
+
+    def close(self):
+        self._z.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    name = property(lambda s: s.manifest["name"])
+    default = property(lambda s: s.manifest["default"])
+    config = property(lambda s: s.manifest.get("config", {}))
+    tags = property(lambda s: list(s.manifest["clips"]))
+    parts = property(lambda s: list(s.manifest.get("parts", {})))
+    cadence = property(lambda s: s.manifest.get("cadence"))
+
+    @property
+    def id(self):
+        """12-hex content id: hash of the sorted clip hashes (ignores names and settings)."""
+        return _sha("".join(sorted(c["sha256"] for c in self.manifest["clips"].values())).encode())[:12]
+
+    def rules(self):
+        """[(compiled regex, tag)] in order."""
+        return [(re.compile(r["pattern"]), r["tag"]) for r in self.manifest.get("rules", [])]
+
+    def select_tag(self, text):
+        """The clip tag the rules choose for `text` (first match), else the default."""
+        for rx, tag in self.rules():
+            if rx.search(text) and tag in self.manifest["clips"]:
+                return tag
+        return self.default
+
+    def clip(self, tag=None):
+        """Clip for `tag` (unknown or None -> default) with its FLAC bytes."""
+        if tag not in self.manifest["clips"]:
+            tag = self.default
+        c = self.manifest["clips"][tag]
+        return Clip(tag, c["text"], c.get("seconds"), c.get("label"), c.get("sample_rate"), self._read(c["file"]))
+
+    def part(self, name):
+        """FLAC bytes of an enrollment recording."""
+        return self._read(self.manifest["parts"][name]["file"])
+
+    def read(self, tag=None):
+        """(float32 ndarray, sample_rate) for a clip. Needs vcref[audio]."""
+        return _soundfile().read(io.BytesIO(self.clip(tag).flac), dtype="float32")
+
+    def verify(self):
+        """Raise VcrefError on any hash mismatch or missing entry; return True otherwise."""
+        for kind in ("clips", "parts"):
+            for key, meta in self.manifest.get(kind, {}).items():
+                data = self._read(meta["file"])
+                if _sha(data) != meta["sha256"]:
+                    raise VcrefError(f"{kind[:-1]} {key!r} is corrupt (hash mismatch)")
+        return True
+
+    def unpack(self, out_dir, wav=False):
+        """Write <tag>.flac (or .wav with the audio extra) and <tag>.txt for every clip."""
+        out_dir = Path(out_dir)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        for tag in self.tags:
+            c = self.clip(tag)
+            if wav:
+                x, sr = self.read(tag)
+                _soundfile().write(out_dir / f"{tag}.wav", x, sr, subtype="PCM_24")
+            else:
+                (out_dir / f"{tag}.flac").write_bytes(c.flac)
+            (out_dir / f"{tag}.txt").write_text(c.text, encoding="utf-8")
+        return out_dir
+
+
+def set_cadence(path, cadence):
+    """Replace the cadence block of an existing bundle; every other entry is copied byte for byte."""
+    path = Path(path)
+    with Bundle(path) as b:
+        m = dict(b.manifest)
+        m["cadence"] = cadence
+        tmp = path.with_suffix(path.suffix + ".tmp")
+        with zipfile.ZipFile(tmp, "w", zipfile.ZIP_STORED) as z:
+            z.comment = MAGIC
+            for n in b._z.namelist():
+                if n != "manifest.json":
+                    z.writestr(n, b._z.read(n))
+            z.writestr("manifest.json", json.dumps(m, indent=1, ensure_ascii=False))
+    tmp.replace(path)
+    return path

vcref-0.1.0/src/vcref/cli.py

@@ -0,0 +1,34 @@
+import argparse
+import sys
+
+from .bundle import Bundle, VcrefError
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="vcref", description="Inspect and check .vcref voice bundles")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    for n in ("info", "verify"):
+        sub.add_parser(n).add_argument("file")
+    u = sub.add_parser("unpack")
+    u.add_argument("file")
+    u.add_argument("dir")
+    u.add_argument("--wav", action="store_true", help="decode to 24-bit WAV (needs vcref[audio])")
+    a = ap.parse_args(argv)
+    try:
+        with Bundle(a.file) as b:
+            if a.cmd == "info":
+                print(f"{b.name}  id={b.id}  default={b.default}  rules={len(b.manifest.get('rules', []))}  "
+                      f"parts={len(b.parts)}  cadence={'yes' if b.cadence else 'no'}")
+                for t, c in b.manifest["clips"].items():
+                    print(f"  {t:12} {c.get('seconds') or 0:6.1f}s {c.get('sample_rate') or 0:>6} Hz  {c['text'][:60]}")
+            elif a.cmd == "verify":
+                b.verify()
+                print("ok")
+            else:
+                print(b.unpack(a.dir, wav=a.wav))
+    except VcrefError as e:
+        sys.exit(f"vcref: {e}")
+
+
+if __name__ == "__main__":
+    main()

vcref-0.1.0/tests/test_bundle.py

@@ -0,0 +1,103 @@
+import io
+import tempfile
+import unittest
+import zipfile
+from pathlib import Path
+
+import vcref
+
+FIX = Path(__file__).resolve().parents[2] / "fixtures" / "tiny.vcref"
+
+
+class FixtureTests(unittest.TestCase):
+    def test_reads_shared_fixture(self):
+        with vcref.Bundle(FIX) as b:
+            self.assertEqual((b.name, b.default), ("tiny", "neutral"))
+            self.assertEqual(b.tags, ["neutral", "question"])
+            self.assertEqual(b.parts, ["A"])
+            self.assertEqual(b.config["lufs"], -16)
+            self.assertEqual(b.cadence["global"]["artic"], 5.6)
+            self.assertTrue(b.verify())
+            self.assertEqual(len(b.id), 12)
+
+    def test_rules_and_fallback(self):
+        with vcref.Bundle(FIX) as b:
+            self.assertEqual(b.select_tag("Really?"), "question")
+            self.assertEqual(b.select_tag("Plain."), "neutral")
+            self.assertEqual(b.clip("nope").tag, "neutral")
+
+    def test_clip_bytes_are_flac(self):
+        with vcref.Bundle(FIX) as b:
+            c = b.clip("question")
+            self.assertEqual(c.flac[:4], b"fLaC")
+            self.assertEqual(c.sample_rate, 16000)
+            x, sr = b.read("question")
+            self.assertEqual(sr, 16000)
+            self.assertAlmostEqual(len(x) / sr, 0.5, places=2)
+
+
+class RoundTripTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = Path(tempfile.mkdtemp())
+
+    def test_pack_from_flac_bytes_and_unpack(self):
+        with vcref.Bundle(FIX) as src:
+            flac = src.clip("neutral").flac
+        out = vcref.pack(self.tmp / "a.vcref", {"neutral": {"flac": flac, "text": "hello"}})
+        with vcref.Bundle(out) as b:
+            self.assertTrue(b.verify())
+            self.assertEqual(b.clip().flac, flac)
+            d = b.unpack(self.tmp / "u")
+        self.assertEqual((d / "neutral.txt").read_text(encoding="utf-8"), "hello")
+        self.assertEqual((d / "neutral.flac").read_bytes(), flac)
+
+    def test_set_cadence_keeps_audio(self):
+        import shutil
+        p = self.tmp / "c.vcref"
+        shutil.copy(FIX, p)
+        with vcref.Bundle(p) as b:
+            before = b.clip("neutral").flac, b.id
+        vcref.set_cadence(p, {"v": 1, "global": {"artic": 4.0}})
+        with vcref.Bundle(p) as b:
+            self.assertEqual((b.clip("neutral").flac, b.id), before)
+            self.assertEqual(b.cadence["global"]["artic"], 4.0)
+
+    def test_pack_validation(self):
+        with self.assertRaises(vcref.VcrefError):
+            vcref.pack(self.tmp / "x.vcref", {})
+        with self.assertRaises(vcref.VcrefError):
+            vcref.pack(self.tmp / "x.vcref", {"bad tag": {"flac": b"fLaC", "text": "t"}})
+
+
+class RejectTests(unittest.TestCase):
+    def test_bad_magic(self):
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w") as z:
+            z.writestr("manifest.json", "{}")
+        with self.assertRaises(vcref.VcrefError):
+            vcref.Bundle(buf.getvalue())
+
+    def test_not_a_zip(self):
+        with self.assertRaises(vcref.VcrefError):
+            vcref.Bundle(b"nope")
+
+    def test_corruption_detected(self):
+        data = bytearray(FIX.read_bytes())
+        i = data.index(b"fLaC") + 60
+        data[i] ^= 0xFF
+        with vcref.Bundle(bytes(data)) as b:
+            with self.assertRaises(vcref.VcrefError):
+                b.verify()
+
+    def test_future_version_refused(self):
+        import json
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w") as z:
+            z.comment = vcref.MAGIC
+            z.writestr("manifest.json", json.dumps({"format": "vcref", "version": 99, "default": "a", "clips": {"a": {}}}))
+        with self.assertRaises(vcref.VcrefError):
+            vcref.Bundle(buf.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()