vcref 0.1.0__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: vcref
3
- Version: 0.1.0
3
+ Version: 0.2.0
4
4
  Summary: Read, write and verify .vcref voice reference bundles for zero-shot voice-cloning TTS.
5
5
  Project-URL: Homepage, https://github.com/bhavya091213/vcref
6
6
  License: MIT
@@ -44,3 +44,14 @@ vcref.set_cadence("voice.vcref", cadence_dict) # rewrite only the cadence block
44
44
  ```
45
45
 
46
46
  Errors are `vcref.VcrefError`. Command line: `vcref info|verify <file>`, `vcref unpack <file> <dir> [--wav]`.
47
+
48
+ ## Choosing and inspecting references
49
+
50
+ ```python
51
+ b.explain("Really?") # {'tag', 'why': 'rule'|'default', 'rule', 'pattern'}
52
+ b.prompt("Really?", stack=True) # [selected clip, default clip] ready for a TTS prompt
53
+ b.search("podcast") # tags whose tag, label or transcript contain the text
54
+ b.stats() # clip/part bytes, kbps, pcm16_ratio, per-clip sizes (no decoding)
55
+ ```
56
+
57
+ Guides: [compression](../docs/compression.md), [extracting references](../docs/extracting-references.md), [best practices](../docs/best-practices.md).
@@ -27,3 +27,14 @@ vcref.set_cadence("voice.vcref", cadence_dict) # rewrite only the cadence block
27
27
  ```
28
28
 
29
29
  Errors are `vcref.VcrefError`. Command line: `vcref info|verify <file>`, `vcref unpack <file> <dir> [--wav]`.
30
+
31
+ ## Choosing and inspecting references
32
+
33
+ ```python
34
+ b.explain("Really?") # {'tag', 'why': 'rule'|'default', 'rule', 'pattern'}
35
+ b.prompt("Really?", stack=True) # [selected clip, default clip] ready for a TTS prompt
36
+ b.search("podcast") # tags whose tag, label or transcript contain the text
37
+ b.stats() # clip/part bytes, kbps, pcm16_ratio, per-clip sizes (no decoding)
38
+ ```
39
+
40
+ Guides: [compression](../docs/compression.md), [extracting references](../docs/extracting-references.md), [best practices](../docs/best-practices.md).
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "vcref"
7
- version = "0.1.0"
7
+ version = "0.2.0"
8
8
  description = "Read, write and verify .vcref voice reference bundles for zero-shot voice-cloning TTS."
9
9
  readme = "README.md"
10
10
  license = { text = "MIT" }
@@ -2,4 +2,4 @@
2
2
  from .bundle import MAGIC, VERSION, Bundle, Clip, VcrefError, pack, set_cadence
3
3
 
4
4
  __all__ = ["Bundle", "Clip", "VcrefError", "pack", "set_cadence", "MAGIC", "VERSION"]
5
- __version__ = "0.1.0"
5
+ __version__ = "0.2.0"
@@ -169,6 +169,46 @@ class Bundle:
169
169
  return tag
170
170
  return self.default
171
171
 
172
+ def explain(self, text):
173
+ """Why `select_tag(text)` returns what it does: {"tag", "why": "rule"|"default", "rule", "pattern"}."""
174
+ for i, (rx, tag) in enumerate(self.rules()):
175
+ if rx.search(text) and tag in self.manifest["clips"]:
176
+ return {"tag": tag, "why": "rule", "rule": i, "pattern": rx.pattern}
177
+ return {"tag": self.default, "why": "default", "rule": None, "pattern": None}
178
+
179
+ def prompt(self, text, stack=False):
180
+ """Reference clips to hand a TTS model for `text`: the rule-selected clip first, then (stack=True) the
181
+ default clip as a second, neutral anchor when it differs."""
182
+ tag = self.select_tag(text)
183
+ clips = [self.clip(tag)]
184
+ if stack and tag != self.default:
185
+ clips.append(self.clip(self.default))
186
+ return clips
187
+
188
+ def search(self, query):
189
+ """Tags whose tag, label or transcript contains `query` (case-insensitive), in manifest order."""
190
+ q = query.lower()
191
+ return [t for t, c in self.manifest["clips"].items()
192
+ if q in t.lower() or q in (c.get("label") or "").lower() or q in c["text"].lower()]
193
+
194
+ def stats(self):
195
+ """Sizes and bitrates from the zip directory (no audio decoding). bytes are stored sizes; `pcm16_ratio`
196
+ compares the clips with the same audio as raw 16-bit PCM at each clip's own sample rate."""
197
+ per, raw = [], 0
198
+ for tag, c in self.manifest["clips"].items():
199
+ size = self._z.getinfo(c["file"]).file_size
200
+ secs, sr = c.get("seconds"), c.get("sample_rate")
201
+ if secs and sr:
202
+ raw += int(secs * sr * 2)
203
+ per.append({"tag": tag, "seconds": secs, "sample_rate": sr, "bytes": size,
204
+ "kbps": round(size * 8 / secs / 1000) if secs else None})
205
+ clip_bytes = sum(p["bytes"] for p in per)
206
+ part_bytes = sum(self._z.getinfo(p["file"]).file_size for p in self.manifest.get("parts", {}).values())
207
+ secs = sum(p["seconds"] or 0 for p in per)
208
+ return {"clips": len(per), "clip_seconds": round(secs, 1), "clip_bytes": clip_bytes, "part_bytes": part_bytes,
209
+ "file_bytes": clip_bytes + part_bytes, "kbps": round(clip_bytes * 8 / secs / 1000) if secs else None,
210
+ "pcm16_ratio": round(raw / clip_bytes, 2) if raw and clip_bytes else None, "per_clip": per}
211
+
172
212
  def clip(self, tag=None):
173
213
  """Clip for `tag` (unknown or None -> default) with its FLAC bytes."""
174
214
  if tag not in self.manifest["clips"]:
@@ -36,6 +36,26 @@ class FixtureTests(unittest.TestCase):
36
36
  self.assertAlmostEqual(len(x) / sr, 0.5, places=2)
37
37
 
38
38
 
39
+ class HelperTests(unittest.TestCase):
40
+ def test_explain_and_prompt(self):
41
+ with vcref.Bundle(FIX) as b:
42
+ e = b.explain("Really?")
43
+ self.assertEqual((e["tag"], e["why"], e["rule"]), ("question", "rule", 0))
44
+ self.assertEqual(b.explain("Plain.")["why"], "default")
45
+ self.assertEqual([c.tag for c in b.prompt("Really?")], ["question"])
46
+ self.assertEqual([c.tag for c in b.prompt("Really?", stack=True)], ["question", "neutral"])
47
+ self.assertEqual([c.tag for c in b.prompt("Plain.", stack=True)], ["neutral"])
48
+
49
+ def test_search_and_stats(self):
50
+ with vcref.Bundle(FIX) as b:
51
+ self.assertIn("question", b.search("QUEST"))
52
+ s = b.stats()
53
+ self.assertEqual(s["clips"], 2)
54
+ self.assertEqual(s["file_bytes"], s["clip_bytes"] + s["part_bytes"])
55
+ self.assertEqual(len(s["per_clip"]), 2)
56
+ self.assertGreater(s["clip_bytes"], 0)
57
+
58
+
39
59
  class RoundTripTests(unittest.TestCase):
40
60
  def setUp(self):
41
61
  self.tmp = Path(tempfile.mkdtemp())
File without changes
File without changes
File without changes
File without changes