afrispeech-synth 0.1.0__py3-none-any.whl

afrispeech_synth/__init__.py

@@ -0,0 +1,23 @@
+"""afrispeech-synth — synthetic speech datasets for African languages.
+
+    from afrispeech_synth import RunConfig, run
+
+    config = RunConfig(language="twi", sources=["corpus:twi"])
+    config.select.max_sentences = 500
+    run(config)
+"""
+from .config import RunConfig, SelectConfig, TTSConfig, PackageConfig, load, from_dict
+from .lang import Language, LanguageNotSupported, resolve
+from .normalise import Normaliser
+from .pipeline import run, stage_sources, stage_select, stage_synthesise, stage_package
+from .select import Selection
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RunConfig", "SelectConfig", "TTSConfig", "PackageConfig",
+    "load", "from_dict", "run",
+    "stage_sources", "stage_select", "stage_synthesise", "stage_package",
+    "Language", "LanguageNotSupported", "resolve", "Normaliser", "Selection",
+    "__version__",
+]

afrispeech_synth/card.py

@@ -0,0 +1,268 @@
+"""Generate the dataset card.
+
+Provenance is the whole point: a synthetic dataset is only trustworthy if a
+reader can see which text it came from, how sentences were chosen, which G2P
+produced the transcripts and which model and voices spoke them. All of that is
+already in the run config, so the card is generated rather than hand-written.
+"""
+from __future__ import annotations
+
+import datetime
+from typing import Optional
+
+from .lang import Language
+from .normalise import describe as describe_g2p
+
+TEMPLATE = """---
+language:
+- {lang_code}
+license: cc-by-4.0
+task_categories:
+- text-to-speech
+- automatic-speech-recognition
+tags:
+- audio
+- tts
+- synthetic
+- african-languages
+- {lang_slug}
+pretty_name: {title}
+configs:
+- config_name: default
+  data_files:
+  - split: train
+    path: data/*.parquet
+---
+
+# {title}
+
+Synthetic speech for **{lang_name}** ({lang_code}), generated with
+[`afrispeech-synth`](https://github.com/AfriSpeech/afrispeech-synth).
+
+{counts}
+
+> **Synthetic data.** Every clip here was generated by {tts_credit}, not recorded
+> from a speaker. It is meant to bootstrap and supplement TTS/ASR training for a
+> low-resource language, not to replace recorded speech. The audio carries whatever
+> accent and pronunciation the model has for this language — check a sample by ear
+> before training on it, and see {terms_note}
+
+## How it was built
+
+| Stage | What ran |
+|---|---|
+| Source text | {sources} |
+| Selection | {selection} |
+| Normalisation | {normalisation} |
+| Synthesis | {synthesis} |
+
+### 1. Source text
+
+{sources_detail}
+
+### 2. Sentence selection
+
+{selection_detail}
+
+### 3. Normalisation
+
+{normalisation_detail}
+
+### 4. Synthesis
+
+Audio was generated with **{tts_model}** (backend `{tts_backend}`), voice(s)
+**{voices}**, prompted with:
+
+```text
+{prompt_example}
+```
+
+## Dataset structure
+
+- `data/train-*.parquet` — audio bytes embedded inline (WAV, {sample_rate} Hz mono),
+  so the dataset viewer plays each clip next to its text.
+- `metadata.jsonl` — one record per clip: `index`, `text`, `normalised_text`,
+  `voice`, `shard`, `file_name`.
+- `sentences.txt` — the selected source sentences, one per line.
+
+| Column | Description |
+|---|---|
+| `audio` | Generated speech, WAV @ {sample_rate} Hz mono |
+| `text` | The original sentence |
+| `normalised_text` | The transcript actually given to the TTS model |
+| `voice` | Which voice spoke this clip |
+
+## Reproducing it
+
+```bash
+pip install afrispeech-synth
+afrispeech-synth run config.yaml
+```
+
+```yaml
+{config_yaml}```
+
+## Acknowledgements and terms
+
+The audio was generated by {tts_credit}. Clips are model output and are subject to
+{terms_link} — check them before redistributing or training on this data.
+Phonemisation is [africa-g2p](https://github.com/AfriSpeech/africa-g2p);
+text and language metadata come from
+[africa-corpus-builder](https://github.com/AfriSpeech/africa-corpus-builder) and
+[afriso](https://github.com/AfriSpeech/afriso).
+
+## License
+
+Transcripts and the dataset structure: CC-BY-4.0. The audio is model output — see the
+terms above. Source text keeps the licence of its own corpus, linked above.
+
+---
+
+Built with [afrispeech-synth](https://github.com/AfriSpeech/afrispeech-synth) ·
+[africa-g2p](https://github.com/AfriSpeech/africa-g2p) ·
+[africa-corpus-builder](https://github.com/AfriSpeech/africa-corpus-builder) ·
+[afriso](https://github.com/AfriSpeech/afriso) — generated {date}.
+"""
+
+PROVIDERS = {
+    "gemini": {
+        "credit": "**[Google Gemini TTS](https://ai.google.dev/gemini-api/docs/speech-generation)**",
+        "terms": "[Google's Gemini API terms](https://ai.google.dev/gemini-api/terms)",
+    },
+}
+
+
+def _provider(backend: str, model: str) -> dict:
+    known = PROVIDERS.get(backend)
+    if known:
+        return known
+    return {"credit": f"the `{backend}` TTS backend (`{model}`)",
+            "terms": "your TTS provider's terms"}
+
+
+SOURCE_LINKS = {
+    "corpus": ("africa-corpus-builder",
+               "https://huggingface.co/datasets/AfriSpeech/africa-corpus"),
+    "hf": ("HuggingFace dataset", "https://huggingface.co/datasets/{target}"),
+    "file": ("local file", None),
+}
+
+
+def _source_detail(uri: str) -> str:
+    from .sources import _parse
+    scheme, target, column, qualifier = _parse(uri)
+    if scheme == "corpus":
+        cap = f", capped at {qualifier} sentences" if qualifier else ""
+        return (f"- **{target}** monolingual text from "
+                f"[`AfriSpeech/africa-corpus`](https://huggingface.co/datasets/AfriSpeech/africa-corpus) "
+                f"via [africa-corpus-builder](https://github.com/AfriSpeech/africa-corpus-builder){cap}.")
+    if scheme == "hf":
+        split = f", split `{qualifier}`" if qualifier else ", all splits"
+        return (f"- Column `{column}` of "
+                f"[`{target}`](https://huggingface.co/datasets/{target}){split}.")
+    return f"- Local file `{target}`" + (f", column `{column}`" if column else "") + "."
+
+
+def _selection_detail(select_config, selection) -> str:
+    if select_config.cover == "none":
+        return ("No coverage selection — every sentence within the length filter was kept"
+                f" ({select_config.min_chars}–{select_config.max_chars} characters).")
+    unit = "phoneme" if select_config.cover == "phoneme" else "word"
+    detail = (
+        f"Greedy **set cover** over {unit} units: the smallest set of sentences such that every "
+        f"{unit} in the corpus appears at least once. This is what keeps a synthetic corpus "
+        f"small without leaving sounds unheard — every sentence dropped is an API call saved, "
+        f"and every {unit} kept is one the model gets to learn.\n\n"
+        f"Sentences were filtered to {select_config.min_chars}–{select_config.max_chars} characters"
+    )
+    if select_config.min_freq > 1:
+        detail += f", and only {unit}s occurring at least {select_config.min_freq} times were targeted"
+    detail += "."
+    if selection is not None and selection.total_units:
+        detail += (f"\n\n**{selection.covered:,} of {selection.total_units:,} {unit} units covered "
+                   f"({selection.coverage:.1%}) by {len(selection.sentences):,} sentences.**")
+    return detail
+
+
+def _normalisation_detail(language: Language, mode: str) -> str:
+    if mode == "none":
+        return "None — the raw source text was sent to the TTS model unchanged."
+    if mode == "universal":
+        return (
+            "Each sentence was rewritten in **universal graphemes** with "
+            "[`africa-g2p`](https://github.com/AfriSpeech/africa-g2p):\n\n"
+            "```python\n"
+            "from africa_g2p import GraphemeConverter, UNIVERSAL\n"
+            f"GraphemeConverter({language.g2p_code!r}, UNIVERSAL).convert(text)\n"
+            "```\n\n"
+            "Universal graphemes write every phoneme with the letter most African languages "
+            "use for it — `ɔ` becomes `o`, `ɛ` becomes `e` — so the same sound is spelled the "
+            "same way across languages, in plain letters rather than IPA symbols. The result "
+            "is stored as `normalised_text` and is the transcript the TTS model was given."
+        )
+    if mode == "ipa":
+        return (
+            "Each sentence was converted to **IPA** with "
+            "[`africa-g2p`](https://github.com/AfriSpeech/africa-g2p):\n\n"
+            "```python\n"
+            "from africa_g2p import AfricaPipeline\n"
+            f"AfricaPipeline(lang={language.g2p_code!r}, output='ipa').run(text)\n"
+            "```\n\n"
+            "IPA puts every language on one shared symbol inventory, which is what you want "
+            "when a single model is trained across several languages."
+        )
+    return (
+        "Each sentence was rewritten into **native-orthography phoneme units** with "
+        "[`africa-g2p`](https://github.com/AfriSpeech/africa-g2p):\n\n"
+        "```python\n"
+        "from africa_g2p import AfricaPipeline\n"
+        f"AfricaPipeline(lang={language.g2p_code!r}).run(text)\n"
+        "```\n\n"
+        "Multigraphs (`ny`, `kp`, `gb`, …) stay whole and the text stays inside the language's "
+        "own inventory, which trains TTS better than IPA for a single language. The result is "
+        "stored as `normalised_text` and is the transcript the TTS model was actually given."
+    )
+
+
+def render(config, language: Language, clips: int, selection=None,
+           title: Optional[str] = None) -> str:
+    import yaml
+
+    from .synth import render_prompt
+
+    title = title or f"{language.name} Synthetic Speech"
+    sources = ", ".join(f"`{uri}`" for uri in config.sources) or "—"
+    counts = f"**{clips:,} clips** · {language.name} (`{language.code}`)"
+    if language.family:
+        counts += f" · {language.family}"
+
+    safe_config = config.to_dict()
+    safe_config["tts"].pop("api_key_env", None)
+
+    provider = _provider(config.tts.backend, config.tts.model)
+
+    return TEMPLATE.format(
+        tts_credit=provider["credit"],
+        terms_note=provider["terms"] + " for how the audio may be used.",
+        terms_link=provider["terms"],
+        lang_code=language.code,
+        lang_slug=language.name.lower().replace(" ", "-"),
+        lang_name=language.name,
+        title=title,
+        counts=counts,
+        sources=sources,
+        selection=(f"greedy set cover ({config.select.cover})"
+                   if config.select.cover != "none" else "length filter only"),
+        normalisation=describe_g2p(language, config.normalise) or "none",
+        synthesis=f"{config.tts.backend} / {config.tts.model}",
+        sources_detail="\n".join(_source_detail(uri) for uri in config.sources) or "—",
+        selection_detail=_selection_detail(config.select, selection),
+        normalisation_detail=_normalisation_detail(language, config.normalise),
+        tts_model=config.tts.model,
+        tts_backend=config.tts.backend,
+        voices=", ".join(config.tts.voices),
+        prompt_example=render_prompt(config.tts, language, "<normalised_text>"),
+        sample_rate=config.tts.sample_rate,
+        config_yaml=yaml.safe_dump(safe_config, sort_keys=False, allow_unicode=True),
+        date=datetime.date.today().isoformat(),
+    )

afrispeech_synth/cli.py

@@ -0,0 +1,308 @@
+"""Command line interface.
+
+    afrispeech-synth run config.yaml            # the whole pipeline
+    afrispeech-synth run config.yaml --dry-run  # select sentences only
+    afrispeech-synth select --lang twi --source corpus:twi --max-sentences 2000
+    afrispeech-synth synth  config.yaml         # resume synthesis only
+    afrispeech-synth package config.yaml        # rebuild parquet from the work dir
+    afrispeech-synth push    config.yaml --repo AfriSpeech/twi-synthetic-speech
+    afrispeech-synth langs --search yor
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__
+from . import card as card_module
+from . import config as config_module
+from . import package as package_module
+from . import pipeline
+from . import publish as publish_module
+from . import tts as tts_registry
+from .lang import resolve
+from .normalise import Normaliser
+
+
+def _config_from_args(args) -> config_module.RunConfig:
+    """A config file, CLI flags, or both — flags always win."""
+    if getattr(args, "config", None):
+        config = config_module.load(args.config)
+    else:
+        config = config_module.RunConfig()
+
+    overrides = {}
+    for flag, target in [
+        ("lang", "language"), ("out", "out"), ("work", "work"),
+        ("normalise", "normalise"),
+        ("cover", "select.cover"), ("min_freq", "select.min_freq"),
+        ("max_sentences", "select.max_sentences"),
+        ("min_chars", "select.min_chars"), ("max_chars", "select.max_chars"),
+        ("backend", "tts.backend"), ("model", "tts.model"),
+        ("concurrency", "tts.concurrency"), ("rpm", "tts.rpm"),
+        ("repo", "package.push_to"),
+    ]:
+        value = getattr(args, flag, None)
+        if value is not None:
+            overrides[target] = value
+    if getattr(args, "voices", None):
+        overrides["tts.voices"] = [v.strip() for v in args.voices.split(",") if v.strip()]
+    if getattr(args, "source", None):
+        config.sources = list(args.source)
+    if getattr(args, "format", None):
+        overrides["package.formats"] = [f.strip() for f in args.format.split(",") if f.strip()]
+
+    config_module.apply_overrides(config, overrides)
+    if not config.sources and getattr(args, "_needs_sources", True):
+        config.sources = [f"corpus:{resolve(config.language).code}"]
+    return config
+
+
+def cmd_run(args) -> int:
+    config = _config_from_args(args)
+    pipeline.run(config, resume=not args.no_resume, dry_run=args.dry_run)
+    return 0
+
+
+def cmd_select(args) -> int:
+    config = _config_from_args(args)
+    language = resolve(config.language)
+    normaliser = Normaliser(language, config.normalise)
+    sentences = pipeline.stage_sources(config, language)
+    selection = pipeline.stage_select(config, language, sentences, normaliser)
+    pipeline._save_sentences(config, selection.sentences, selection)
+    out = os.path.join(config.work_dir, pipeline.SENTENCES_FILE)
+    print(f"\n{len(selection.sentences)} sentences -> {out}")
+    return 0
+
+
+def cmd_synth(args) -> int:
+    config = _config_from_args(args)
+    language = resolve(config.language)
+    sentences = pipeline.load_sentences(config)
+    if sentences is None:
+        print(f"No {pipeline.SENTENCES_FILE} in {config.work_dir}. Run `select` first, "
+              f"or use `run` to do everything.", file=sys.stderr)
+        return 1
+    normaliser = Normaliser(language, config.normalise)
+    pipeline.stage_synthesise(config, language, sentences, normaliser,
+                              resume=not args.no_resume)
+    return 0
+
+
+def cmd_package(args) -> int:
+    config = _config_from_args(args)
+    language = resolve(config.language)
+    pipeline.stage_package(config, language)
+    return 0
+
+
+def cmd_push(args) -> int:
+    config = _config_from_args(args)
+    repo = args.repo or config.package.push_to
+    if not repo:
+        print("No target repo. Pass --repo org/name or set package.push_to.", file=sys.stderr)
+        return 1
+    publish_module.push(config.out, repo, private=config.package.private)
+    return 0
+
+
+def cmd_card(args) -> int:
+    config = _config_from_args(args)
+    language = resolve(config.language)
+    clips = len(package_module.Workspace(config.work_dir).records()) if \
+        os.path.exists(config.work_dir) else 0
+    print(card_module.render(config, language, clips))
+    return 0
+
+
+STATUS_HELP = {
+    "ready": "text + G2P available — just name the language",
+    "bring text": "G2P available; supply text with a file: or hf: source",
+    "no g2p": "text available; run with --normalise none",
+}
+
+
+def cmd_langs(args) -> int:
+    from . import coverage
+
+    catalogue = coverage.load()
+    entries = catalogue.search(args.search) if args.search else catalogue.sorted()
+    if args.ready:
+        entries = [e for e in entries if e.ready]
+
+    for entry in entries:
+        print(f"{entry.code:<6} {entry.name[:34]:<35} {entry.status:<11} {entry.family}")
+
+    counts = catalogue.counts()
+    print(f"\n{len(entries)} shown.", file=sys.stderr)
+    print(f"  {counts['ready']:>4} ready       {STATUS_HELP['ready']}", file=sys.stderr)
+    print(f"  {counts['g2p'] - counts['ready']:>4} bring text  {STATUS_HELP['bring text']}",
+          file=sys.stderr)
+    print(f"  {counts['text'] - counts['ready']:>4} no g2p      {STATUS_HELP['no g2p']}",
+          file=sys.stderr)
+    if not counts["text"]:
+        print("\n  (africa-corpus-builder not found, so no language shows as ready — "
+              "see the README to install it.)", file=sys.stderr)
+    return 0
+
+
+def cmd_samples(args) -> int:
+    from . import samples as samples_module
+
+    config = _config_from_args(args)
+    codes = [c.strip() for c in args.langs.split(",") if c.strip()] if args.langs else None
+    built = samples_module.build(config, args.dir, codes=codes, limit=args.limit,
+                                 resume=not args.no_resume)
+    print(f"\n{len(built)} samples in {args.dir}. Next: afrispeech-synth space "
+          f"--dir {args.dir} --repo org/name")
+    return 0
+
+
+def cmd_space(args) -> int:
+    from . import samples as samples_module
+    from . import space as space_module
+
+    built = samples_module.load_manifest(args.dir)
+    if not built:
+        print(f"No samples.json in {args.dir}. Run `samples` first.", file=sys.stderr)
+        return 1
+    space_module.build(built, args.dir, title=args.title)
+    if args.repo:
+        space_module.push(args.dir, args.repo, private=args.private)
+    else:
+        print(f"\nOpen {os.path.join(args.dir, 'index.html')} to preview, then re-run "
+              f"with --repo org/name to publish.")
+    return 0
+
+
+def cmd_voices(args) -> int:
+    from .voices import GEMINI_VOICES
+
+    print("Gemini TTS voices — set any of these in `tts.voices`, "
+          "or several to rotate speakers:\n")
+    for name, character in GEMINI_VOICES.items():
+        print(f"  {name:<16} {character}")
+    print(f"\n{len(GEMINI_VOICES)} voices. Example:  --voices Zephyr,Kore,Sulafat",
+          file=sys.stderr)
+    return 0
+
+
+def cmd_init(args) -> int:
+    language = resolve(args.lang)
+    config = config_module.RunConfig(
+        language=language.code,
+        sources=[f"corpus:{language.code}"],
+        out=args.out or f"out/{language.code}",
+    )
+    config.select.max_sentences = 2000
+    config.tts.context = f"speak in {language.name} accent"
+    path = args.config or f"{language.code}.yaml"
+    config_module.dump(config, path)
+    print(f"Wrote {path}. Edit it, then: afrispeech-synth run {path}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="afrispeech-synth",
+        description="Generate synthetic speech datasets for African languages.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    def add_common(sub, with_config=True):
+        if with_config:
+            sub.add_argument("config", nargs="?", help="YAML run config")
+        sub.add_argument("--lang", help="Language name or code (e.g. Twi, twi, yor)")
+        sub.add_argument("--source", action="append",
+                         help="Text source URI; repeatable (corpus:twi, hf:org/ds#col, file:x.txt)")
+        sub.add_argument("--out", help="Output directory")
+        sub.add_argument("--work", help="Work directory (default: <out>/work)")
+        sub.add_argument("--normalise", choices=["grapheme", "universal", "ipa", "none"])
+        sub.add_argument("--cover", choices=["phoneme", "word", "none"])
+        sub.add_argument("--min-freq", type=int)
+        sub.add_argument("--max-sentences", type=int)
+        sub.add_argument("--min-chars", type=int)
+        sub.add_argument("--max-chars", type=int)
+        sub.add_argument("--backend", choices=tts_registry.available())
+        sub.add_argument("--model")
+        sub.add_argument("--voices", help="Comma-separated voice names, round-robined")
+        sub.add_argument("--concurrency", type=int)
+        sub.add_argument("--rpm", type=int)
+        sub.add_argument("--format", help="Comma-separated: parquet,ljspeech")
+        sub.add_argument("--repo", help="HuggingFace dataset repo to push to")
+        return sub
+
+    run_parser = add_common(subparsers.add_parser("run", help="Run the whole pipeline"))
+    run_parser.add_argument("--dry-run", action="store_true",
+                            help="Select sentences and stop, without calling the TTS API")
+    run_parser.add_argument("--no-resume", action="store_true",
+                            help="Ignore existing work and start over")
+    run_parser.set_defaults(func=cmd_run)
+
+    add_common(subparsers.add_parser("select", help="Source + select sentences only")
+               ).set_defaults(func=cmd_select)
+
+    synth_parser = add_common(subparsers.add_parser("synth", help="Synthesise selected sentences"))
+    synth_parser.add_argument("--no-resume", action="store_true")
+    synth_parser.set_defaults(func=cmd_synth)
+
+    add_common(subparsers.add_parser("package", help="Build parquet + manifest + card")
+               ).set_defaults(func=cmd_package)
+    add_common(subparsers.add_parser("push", help="Upload a packaged dataset to the Hub")
+               ).set_defaults(func=cmd_push)
+    add_common(subparsers.add_parser("card", help="Print the dataset card")
+               ).set_defaults(func=cmd_card)
+
+    init_parser = subparsers.add_parser("init", help="Write a starter config for a language")
+    init_parser.add_argument("lang", help="Language name or code")
+    init_parser.add_argument("--config", help="Config path to write")
+    init_parser.add_argument("--out", help="Output directory to record in the config")
+    init_parser.set_defaults(func=cmd_init)
+
+    langs_parser = subparsers.add_parser(
+        "langs", help="List languages and what each one needs to run")
+    langs_parser.add_argument("--search", help="Filter by code or name")
+    langs_parser.add_argument("--ready", action="store_true",
+                              help="Only languages that run with no text of your own")
+    langs_parser.set_defaults(func=cmd_langs)
+
+    voices_parser = subparsers.add_parser("voices", help="List the TTS voices you can choose")
+    voices_parser.set_defaults(func=cmd_voices)
+
+    samples_parser = add_common(
+        subparsers.add_parser("samples", help="Generate one sample clip per language"))
+    samples_parser.add_argument("--dir", default="space",
+                                help="Where samples and the gallery are built (default: space/)")
+    samples_parser.add_argument("--langs", help="Comma-separated codes (default: every ready language)")
+    samples_parser.add_argument("--limit", type=int, help="Stop after this many languages")
+    samples_parser.add_argument("--no-resume", action="store_true")
+    samples_parser.set_defaults(func=cmd_samples)
+
+    space_parser = subparsers.add_parser(
+        "space", help="Build the samples gallery page, and optionally push it as a HF Space")
+    space_parser.add_argument("--dir", default="space", help="Directory holding samples.json")
+    space_parser.add_argument("--repo", help="HuggingFace Space to push to, e.g. AfriSpeech/samples")
+    space_parser.add_argument("--title", default="African Speech Samples")
+    space_parser.add_argument("--private", action="store_true")
+    space_parser.set_defaults(func=cmd_space)
+
+    return parser
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        print("\nInterrupted. Re-run the same command to resume.", file=sys.stderr)
+        return 130
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())