kinescript-elevenlabs 0.1.0__py3-none-any.whl

kinescript_elevenlabs/__init__.py

@@ -0,0 +1,157 @@
+"""ElevenLabs voices for `kine voice`: ElevenLabs' API speaks a sound's text, Eleven v4 and v3 with audio tags such
+as [whispers] or [laughs], and times each character it says; those times become the words.
+
+It needs an API key in ELEVENLABS_API_KEY, and every line it speaks uses characters of that account's quota.
+kine voice calls synth(req) through the "kinescript.voice" entry point; the package has no dependencies, so it
+installs next to Kinescript in any Python it runs on.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+import uuid
+import wave
+from importlib.metadata import PackageNotFoundError, version
+
+API = "https://api.elevenlabs.io"
+MODEL = "eleven_v4"
+SPEAKER = "JBFqnCBsd6RMkjVDRZzb"  # George, the voice in ElevenLabs' own examples
+RATE = 24000  # pcm_24000: raw 16-bit mono, on every plan
+TAG = re.compile(r"(?<!\[)\[(?!\[)[^\[\]()]+\](?![\](])")  # as kinescript.voice.TAG
+SETTINGS = {"stability", "similarity_boost", "style", "use_speaker_boost"}  # voice_settings
+BODY = {"seed", "language_code", "apply_text_normalization"}
+SPEED = (0.7, 1.2)  # what voice_settings.speed takes
+
+
+def acts_on_tags(model: str) -> bool:
+    return model.startswith(("eleven_v3", "eleven_v4"))
+
+
+def _key() -> str:
+    key = os.environ.get("ELEVENLABS_API_KEY") or os.environ.get("XI_API_KEY")
+    if not key:
+        raise RuntimeError("set ELEVENLABS_API_KEY to an ElevenLabs API key (elevenlabs.io > Developers > API keys)")
+    return key
+
+
+def _call(path: str, key: str, body: bytes | None = None, ctype: str = "application/json") -> dict:
+    req = urllib.request.Request(API + path, data=body, method="POST" if body is not None else "GET",
+                                 headers={"xi-api-key": key, "Content-Type": ctype, "Accept": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=300) as r:
+            return json.loads(r.read())
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode("utf-8", "replace")[:600]
+        raise RuntimeError(f"ElevenLabs {path.split('?')[0]} answered {e.code}: {detail}") from None
+
+
+def voice_id(name: str, key: str) -> str:
+    """A voice id as given, or the id of the account's voice with that name (\"George\")."""
+    if re.fullmatch(r"[A-Za-z0-9]{20}", name):
+        return name
+    voices = _call("/v1/voices", key).get("voices") or []
+    for v in voices:
+        if v.get("name", "").split(" - ")[0].strip().lower() == name.strip().lower():
+            return v["voice_id"]
+    names = ", ".join(sorted(v.get("name", "").split(" - ")[0] for v in voices)[:30])
+    raise ValueError(f"no ElevenLabs voice named '{name}' in this account; its voices: {names or 'none'}")
+
+
+def words_from_chars(chars: list[str], starts: list[float], ends: list[float], offset: float = 0.0) -> list[dict]:
+    """ElevenLabs' character times -> [{"word", "start", "end"}], split where the text has spaces, as the text
+    reads. Tags are not words; a word's time runs from its first letter to its last, so punctuation and the pause
+    after it are not stretched in."""
+    text = "".join(chars)
+    at, hidden = 0, [False] * len(chars)
+    spans = [m.span() for m in TAG.finditer(text)]
+    for k, c in enumerate(chars):
+        hidden[k] = any(a <= at < b for a, b in spans)
+        at += len(c)
+    out, cur = [], None
+    for c, s, e, h in zip(chars, starts, ends, hidden):
+        if h or c.isspace():
+            if cur and cur["word"]:
+                out.append(cur)
+            cur = None
+            continue
+        cur = cur or {"word": "", "start": None, "end": None}
+        cur["word"] += c
+        if re.search(r"\w", c):
+            cur["start"] = s if cur["start"] is None else cur["start"]
+            cur["end"] = e
+    if cur and cur["word"]:
+        out.append(cur)
+    timed, last = [], offset
+    for w in out:
+        if not re.search(r"\w", w["word"]):  # punctuation on its own ("—"): nothing is said
+            continue
+        start, end = (w["start"] + offset, w["end"] + offset) if w["start"] is not None else (last, last)
+        timed.append({"word": w["word"], "start": round(start, 4), "end": round(end, 4)})
+        last = end
+    return timed
+
+
+def _wav(path: str, pcm: bytes) -> None:
+    with wave.open(path, "wb") as f:
+        f.setnchannels(1)
+        f.setsampwidth(2)
+        f.setframerate(RATE)
+        f.writeframes(pcm)
+
+
+def _forced(path: str, text: str, key: str) -> list[dict]:
+    """Words timed by ElevenLabs' forced alignment, for a model that returned no character times."""
+    b = uuid.uuid4().hex
+    with open(path, "rb") as f:
+        audio = f.read()
+    body = (f"--{b}\r\nContent-Disposition: form-data; name=\"text\"\r\n\r\n{text}\r\n"
+            f"--{b}\r\nContent-Disposition: form-data; name=\"file\"; filename=\"voice.wav\"\r\n"
+            "Content-Type: audio/wav\r\n\r\n").encode() + audio + f"\r\n--{b}--\r\n".encode()
+    got = _call("/v1/forced-alignment", key, body, f"multipart/form-data; boundary={b}")
+    return [{"word": w["text"].strip(), "start": round(w["start"], 4), "end": round(w["end"], 4)}
+            for w in got.get("words") or [] if re.search(r"\w", w.get("text", ""))]
+
+
+def _version(model: str) -> str:
+    try:
+        own = version("kinescript-elevenlabs")
+    except PackageNotFoundError:
+        own = "?"
+    return f"{model}, kinescript-elevenlabs {own}"
+
+
+def synth(req: dict) -> dict:
+    """Speak req["tagged"] (or req["text"] on a model without tags) with the voice req["speaker"] names (an id or
+    a name in the account, George unless named) into the WAV req["out"], and time each word."""
+    key = _key()
+    opts = dict(req.get("options") or {})
+    model = str(opts.pop("model", MODEL))
+    tags = acts_on_tags(model)
+    text = (req.get("tagged") or req["text"]) if tags else req["text"]
+    speaker = req.get("speaker") or SPEAKER
+    ignored = [f"options.{k}" for k in opts if k not in SETTINGS | BODY]
+    settings = {k: opts[k] for k in SETTINGS if k in opts}
+    rate = float(req.get("rate") or 1)
+    if rate != 1:
+        if SPEED[0] <= rate <= SPEED[1]:
+            settings["speed"] = rate
+        else:
+            ignored.append(f"rate {req['rate']}: ElevenLabs speaks at {SPEED[0]} to {SPEED[1]}")
+    body = {"text": text, "model_id": model, **{k: opts[k] for k in BODY if k in opts}}
+    if settings:
+        body["voice_settings"] = settings
+    vid = voice_id(speaker, key)
+    got = _call(f"/v1/text-to-speech/{vid}/with-timestamps?output_format=pcm_{RATE}", key, json.dumps(body).encode())
+    pcm = base64.b64decode(got["audio_base64"])
+    _wav(req["out"], pcm)
+    timing = got.get("alignment") or {}
+    words = words_from_chars(timing.get("characters") or [], timing.get("character_start_times_seconds") or [],
+                             timing.get("character_end_times_seconds") or [])
+    if not words or not any(w["end"] for w in words):
+        words = _forced(req["out"], TAG.sub("", text), key)
+    return {"words": words, "speaker": speaker, "version": _version(model), "seconds": round(len(pcm) / 2 / RATE, 3),
+            "tags": tags, "ignored": ignored}

kinescript_elevenlabs/__main__.py

@@ -0,0 +1,10 @@
+"""For KINE_VOICE_CMD_ELEVENLABS: a JSON list of requests on stdin, the list of results on stdout.
+
+    KINE_VOICE_CMD_ELEVENLABS='["/path/to/python", "-m", "kinescript_elevenlabs"]' kine voice scene.json
+"""
+import json
+import sys
+
+from . import synth
+
+sys.stdout.write(json.dumps([synth(r) for r in json.loads(sys.stdin.read())]))

kinescript_elevenlabs-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: kinescript-elevenlabs
+Version: 0.1.0
+Summary: ElevenLabs voices for kine voice: audio tags such as whispers, any voice in your account, and word times
+Author: Dr. Know How
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/drknowhow/kinescript/tree/main/plugins/kinescript-elevenlabs
+Project-URL: Documentation, https://drknowhow.github.io/kinescript/
+Project-URL: Source, https://github.com/drknowhow/kinescript/tree/main/plugins/kinescript-elevenlabs
+Project-URL: Issues, https://github.com/drknowhow/kinescript/issues
+Project-URL: Changelog, https://github.com/drknowhow/kinescript/blob/main/CHANGELOG.md
+Keywords: kinescript,elevenlabs,text to speech,tts,voice-over,audio tags,word timestamps
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# kinescript-elevenlabs
+
+[ElevenLabs](https://elevenlabs.io) voices for `kine voice`. It speaks the `text` of a scene's sounds through
+ElevenLabs' API into WAV files and writes the time of each word, so layers can start on a word and captions follow
+the voice. Eleven v4 and v3 act on audio tags such as `[whispers]`, `[laughs]` or `[sighs]`.
+
+```json
+{"id": "vo1", "role": "voice", "backend": "elevenlabs", "speaker": "George",
+ "text": "[whispers] Nobody knows yet. [[go]][laughs] Render it.", "options": {"stability": 0.3}}
+```
+
+```bash
+kine voice scene.json     # writes voice/vo1.wav and voice/vo1.words.json
+kine check scene.json
+```
+
+## Install
+
+It needs Kinescript 1.3 or newer. It has no dependencies of its own, so it installs next to Kinescript on any
+Python 3.10 or newer:
+
+```bash
+pip install kinescript-elevenlabs
+```
+
+From a checkout of [Kinescript](https://github.com/drknowhow/kinescript), `pip install ./plugins/kinescript-elevenlabs`
+does the same.
+
+It needs an API key from your ElevenLabs account (Developers > API keys) in `ELEVENLABS_API_KEY`. Every line it
+speaks uses characters of that account's quota. `kine voice` speaks a line again only when its text, speaker, rate,
+backend or options changed, so re-running it on an unchanged scene costs nothing.
+
+## Voices and settings
+
+`speaker` is a voice id, or the name of a voice in your account (`George`, `Aria`); George unless the sound names one.
+`rate` sets ElevenLabs' speed, which takes 0.7 to 1.2; a rate outside that is spoken at 1 and listed under
+`ignored`.
+
+`options` passes these on:
+
+- `model`: `eleven_v4` by default. `eleven_v3` also acts on tags; other models, such as `eleven_multilingual_v2`
+  or `eleven_flash_v2_5`, get the text without its tags.
+- `stability`, `similarity_boost`, `style`, `use_speaker_boost`: ElevenLabs' voice settings. Lower stability gives
+  a wider emotional range.
+- `seed`, `language_code`, `apply_text_normalization`: passed to the request as they are.
+
+An option it does not know is listed under `ignored` in what `kine voice` prints.
+
+## Word times
+
+ElevenLabs returns the time of each character it says; the plugin joins them into the words of the text as written,
+leaving tags out and timing each word from its first letter to its last. When a model returns no character times,
+the plugin asks ElevenLabs' forced alignment for them, which is billed like speech to text.
+
+## Another Python
+
+To run it from a Python other than Kinescript's, set `KINE_VOICE_CMD_ELEVENLABS` to that Python and the module:
+`["/path/to/python", "-m", "kinescript_elevenlabs"]`.

kinescript_elevenlabs-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+kinescript_elevenlabs/__init__.py,sha256=JlJqT5qDxmgIje86ZvCGEhE0J7Wd63_3MprlcWGcMAc,7167
+kinescript_elevenlabs/__main__.py,sha256=OWrkTgoc0B4X76AGCeoiODVDfOQWIcxkWV2Kkwy0Bu4,333
+kinescript_elevenlabs-0.1.0.dist-info/licenses/LICENSE,sha256=1dTEpVbx7pmCEJy776QUX7yDNLQKZ2csOgwWSqXa_o8,1260
+kinescript_elevenlabs-0.1.0.dist-info/METADATA,sha256=Q3N7_0R9MsQw4wFM0z822_M7AXwg-l0WYU1JOUDURM8,4054
+kinescript_elevenlabs-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+kinescript_elevenlabs-0.1.0.dist-info/entry_points.txt,sha256=ZX-1c26Q_oTeMY8ZLCm98PlJSlPYo25RhOFfRB0_JBs,60
+kinescript_elevenlabs-0.1.0.dist-info/top_level.txt,sha256=TI1vKI5aJQYV-gUpEWTF5pBFVd6SCtQ9zMNThh0ugKo,22
+kinescript_elevenlabs-0.1.0.dist-info/RECORD,,

kinescript_elevenlabs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kinescript_elevenlabs-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[kinescript.voice]
+elevenlabs = kinescript_elevenlabs:synth

kinescript_elevenlabs-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Dr. Know How
+
+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.
+
+The fonts in kinescript/fonts/ (Space Grotesk, IBM Plex Mono) are not covered by
+this license. They are distributed under the SIL Open Font License 1.1; see the
+-OFL.txt files next to them.

kinescript_elevenlabs-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+kinescript_elevenlabs