vcref 0.1.0__py3-none-any.whl

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/__main__.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+vcref/__init__.py,sha256=njjnW7WM1rQ34EW-uvsXcQcnsAb17Jlpz_MhqUjSYk0,280
+vcref/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+vcref/bundle.py,sha256=cfxtPtYr-C2R3-mPbvw5QJIR55np9igVbnmOYSIQ8uA,8908
+vcref/cli.py,sha256=azrGqKMFPY0Yuhp8DCN5W8eT0CUcTVMgBjP_Kzgw5LA,1248
+vcref-0.1.0.dist-info/METADATA,sha256=G4MJVnYOeugIo6mrNjARyDKcSI6Vlf1fDiNFiuJrw3w,2007
+vcref-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+vcref-0.1.0.dist-info/entry_points.txt,sha256=l9lx4X7etWIUJBU0Iayakplg_3i90hAdwDFIXttUKcA,41
+vcref-0.1.0.dist-info/licenses/LICENSE,sha256=Duv0nbattyqyG15S7Q8_7BCmnIyaIQJOghA0mxVmZXM,1069
+vcref-0.1.0.dist-info/RECORD,,

vcref-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vcref-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vcref = vcref.cli:main

vcref-0.1.0.dist-info/licenses/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.