yapsnap 0.1.0__py3-none-any.whl

yapsnap-0.1.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: yapsnap
+Version: 0.1.0
+Summary: Snap any video URL or local audio/video into a plaintext transcript. CPU-first, offline, single command.
+Author: yapsnap
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/kouhxp/yapsnap
+Project-URL: Issues, https://github.com/kouhxp/yapsnap/issues
+Keywords: asr,transcription,sherpa-onnx,kroko,yt-dlp,youtube,tiktok,instagram,transcribe
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sherpa-onnx>=1.10
+Requires-Dist: numpy>=1.23
+Requires-Dist: yt-dlp>=2026.3.17
+Dynamic: license-file
+
+# yapsnap
+
+> **Snap any video URL or audio file into plaintext. No GPU. No cloud. One command.**
+
+![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green) ![Platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)
+
+```bash
+yapsnap "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+```
+
+That's it. You get a `.txt` next to your shell, transcribed on your CPU, in less time than it took the video to play.
+
+---
+
+## Why yapsnap
+
+- ⚡ **Fast on CPU.** Streaming Zipformer transducer (Kroko English) chews through audio at several times realtime on a laptop. No CUDA. No M-series-only tricks. Plain old cores.
+- 🌐 **Any video URL, plus local files.** YouTube. X. TikTok. Instagram Reels. Direct `.mp4`/`.mp3` links. Or just point it at a file on disk. yt-dlp handles the fetch, ffmpeg handles the decode, the rest is yours.
+- 📴 **Offline after first run.** ~80 MB model downloads once to your cache and stays there. No API keys. No quotas. Your audio never leaves your machine.
+- 🪶 **One file, three deps.** `sherpa-onnx`, `numpy`, `yt-dlp`. The whole tool is a single Python module.
+- 🗣 **Ten-plus languages.** English out of the box; French, German, Spanish, Italian, Portuguese, Dutch, Swedish, Swiss German, Hebrew, and Turkish are a one-line `--model` swap away. See [Other languages](#other-languages).
+- ⏱ **Sentence-level timestamps when you want them.** `--timestamps` adds `[MM:SS]` per sentence using Kroko's built-in punctuation. Timing stays correct even when you transcribe at 2x.
+
+---
+
+## Quickstart
+
+```bash
+# 1. ffmpeg on PATH (one-time, per OS — see below)
+# 2. Install (from PyPI, or `pip install .` from a clone)
+pip install yapsnap
+
+# 3. Snap something
+yapsnap https://www.tiktok.com/@user/video/7234567890123456789
+yapsnap meeting.mp4 --timestamps
+yapsnap podcast.mp3 -o ~/notes/episode.txt
+```
+
+The first run downloads the model (~80 MB). Every run after is offline.
+
+---
+
+## What it handles
+
+Any URL `yt-dlp` understands works. The big ones:
+
+| Source            | Example                                                 |
+|-------------------|---------------------------------------------------------|
+| YouTube           | `https://www.youtube.com/watch?v=...`                   |
+| YouTube Shorts    | `https://www.youtube.com/shorts/...`                    |
+| X / Twitter       | `https://x.com/user/status/.../video/1`                 |
+| TikTok            | `https://www.tiktok.com/@user/video/...`                |
+| Instagram Reels   | `https://www.instagram.com/reel/.../`                   |
+| Direct media URL  | `https://example.com/clip.mp4`                          |
+
+Plus any local file ffmpeg can decode: `.mp3`, `.mp4`, `.m4a`, `.wav`, `.webm`, `.mov`, `.mkv`, `.aac`, `.opus`, `.ogg`, `.flac`, and friends.
+
+---
+
+## Install
+
+### 1. ffmpeg
+
+| OS      | Command                                                  |
+|---------|----------------------------------------------------------|
+| macOS   | `brew install ffmpeg`                                    |
+| Linux   | `sudo apt install ffmpeg` *or* `sudo dnf install ffmpeg` |
+| Windows | `winget install ffmpeg` *or* `choco install ffmpeg`      |
+
+### 2. yapsnap
+
+From PyPI (recommended):
+
+```bash
+pip install yapsnap
+```
+
+From source:
+
+```bash
+git clone https://github.com/kouhxp/yapsnap
+cd yapsnap
+pip install .
+```
+
+Installs two equivalent commands on your `PATH`: **`yapsnap`** (canonical) and **`transcribe`** (alias, for when the name slips your mind).
+
+---
+
+## Usage
+
+```bash
+# Local file
+yapsnap path/to/audio.mp3
+
+# Any video URL
+yapsnap "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+
+# Sentence-level timestamps
+yapsnap input.mp4 --timestamps
+
+# Custom output path
+yapsnap input.mp4 -o ./transcripts/talk.txt
+
+# Don't speed audio up before transcribing (default is 1.5x, pitch preserved)
+yapsnap input.mp4 --speed 1.0
+
+# Keep the downloaded audio (URL inputs only)
+yapsnap "https://..." --keep-audio
+```
+
+---
+
+## Output
+
+Plaintext, UTF-8. Default location is `./transcripts/` (created if missing) under the current working directory; override with `-o`. For URL inputs the filename is derived from the video ID (`dQw4w9WgXcQ_transcript.txt`, etc.).
+
+**Without `--timestamps`** — one paragraph of recognized text:
+
+```
+Welcome to the show. Today we're talking about transcription. Let's get started.
+```
+
+**With `--timestamps`** — one sentence per line, timed against the original audio:
+
+```
+[00:00] Welcome to the show.
+[00:03] Today we're talking about transcription.
+[00:08] Let's get started.
+```
+
+Timestamps stay in original-audio time even at `--speed 1.5` or higher.
+
+---
+
+## Flags
+
+| Flag              | Description                                                          |
+|-------------------|----------------------------------------------------------------------|
+| `-o`, `--output`  | Output `.txt` path. Default: `./transcripts/<input>_transcript.txt`. |
+| `--timestamps`    | Emit `[MM:SS] sentence.` lines instead of a single paragraph.        |
+| `--speed`         | Pre-transcription speedup factor, pitch preserved. Default `1.5`.    |
+| `--keep-audio`    | Keep the downloaded audio (URL inputs only).                         |
+| `--model`         | Override the model directory. Also reads `KROKO_MODEL` env var.      |
+
+---
+
+## How it works
+
+1. **Fetch.** If the input is a URL, `yt-dlp` grabs the best audio-only stream to a temp directory. If it's a local path, this step is skipped.
+2. **Decode.** `ffmpeg` pipes the media into 16 kHz mono PCM. The optional `atempo` filter speeds it up without raising pitch.
+3. **Recognize.** A streaming Zipformer2 transducer (Kroko English, INT8 ONNX, ~80 MB) eats the PCM in chunks. CPU-only. Greedy decode.
+4. **Format.** Plain text by default. With `--timestamps`, token timestamps are grouped on `.!?` into sentences and scaled back to original-audio time.
+
+No frame is sent anywhere. No state is kept between runs except the cached model.
+
+---
+
+## Model & cache
+
+The default Kroko English model is downloaded on first run to:
+
+- **macOS** — `~/Library/Caches/yapsnap/`
+- **Linux** — `$XDG_CACHE_HOME/yapsnap/` (or `~/.cache/yapsnap/`)
+- **Windows** — `%LOCALAPPDATA%\yapsnap\`
+
+To use a different streaming transducer (other languages, larger Kroko variants, etc.), point `--model` at a directory containing `encoder(.int8).onnx`, `decoder(.int8).onnx`, `joiner(.int8).onnx`, and `tokens.txt`. Or set `KROKO_MODEL` in your environment.
+
+---
+
+## Other languages
+
+The default model is English, but yapsnap isn't limited to it. To transcribe another language, just download the matching model and point yapsnap at it — no code changes, no reinstall.
+
+Kroko publishes streaming models for a growing list of languages on Hugging Face: <https://huggingface.co/Banafo/Kroko-ASR/tree/main>. As of now that includes:
+
+- Dutch
+- French
+- German
+- Hebrew
+- Italian
+- Portuguese
+- Spanish
+- Swedish
+- Swiss German
+- Turkish
+
+Download the one you need, unpack it into its own folder, and run:
+
+```bash
+# Per-run: pass the model folder explicitly
+yapsnap interview.mp3 --model /path/to/kroko-french
+
+# Or set it once as your default for the session
+export KROKO_MODEL=/path/to/kroko-french
+yapsnap interview.mp3
+```
+
+Each model is single-language, so to work across several languages keep them in separate folders and switch with `--model` (or re-export `KROKO_MODEL`) as you go. Any other sherpa-onnx streaming transducer with the standard `encoder` / `decoder` / `joiner` / `tokens.txt` layout works too, not just the Kroko ones.
+
+---
+
+## Notes & limits
+
+- The default model is **English**. For other languages, download a matching model and pass it with `--model` — see [Other languages](#other-languages) for the current list and instructions.
+- `--speed 1.5` shaves about a third off transcription time with minimal accuracy cost. Try `2.0` if you want it even faster, or `1.0` for noisy, mumbled, or fast-speech sources.
+- Some social-media URLs are geo-locked or login-walled; `yt-dlp` will say so explicitly.
+- This is a streaming model, so timestamps come from token positions in the recognized stream. They're accurate enough for navigation, not for subtitling-grade alignment.
+
+---
+
+## License
+
+Apache-2.0 for this project. The Kroko model is distributed under its own license — see <https://huggingface.co/Banafo/Kroko-ASR>. Powered by [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) and [yt-dlp](https://github.com/yt-dlp/yt-dlp).

yapsnap-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+yapsnap.py,sha256=seAP6DQMJuPvi3eBq9rRshNvuFl2Ct-1Deg_7OLe2v8,19703
+yapsnap-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+yapsnap-0.1.0.dist-info/METADATA,sha256=TkKuEaDFrq8rltsFo03faWrvDVHXnZedvXGgxrjp8VI,9297
+yapsnap-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+yapsnap-0.1.0.dist-info/entry_points.txt,sha256=JitfXD0bS1PD21mHbG8NKeoXzHXuVkutGR6eh1QffCQ,67
+yapsnap-0.1.0.dist-info/top_level.txt,sha256=H2UXXeoQ0sz5UTQrlyBVjxFSbtgQwWPpDYOsMzuW2x8,8
+yapsnap-0.1.0.dist-info/RECORD,,

yapsnap-0.1.0.dist-info/WHEEL

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

yapsnap-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+transcribe = yapsnap:main
+yapsnap = yapsnap:main

yapsnap-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

yapsnap-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+yapsnap

yapsnap.py

@@ -0,0 +1,522 @@
+#!/usr/bin/env python3
+"""
+yapsnap — snap any video or audio into plaintext.
+
+Transcribes a local audio/video file or a URL (YouTube, X, TikTok, Instagram,
+or any direct mp3/mp4 URL) using the sherpa-onnx streaming Kroko English
+transducer. Runs entirely on CPU.
+
+Usage:
+    yapsnap INPUT [-o OUTPUT.txt] [--timestamps] [--speed 1.5] [--keep-audio] [--model DIR]
+
+INPUT may be:
+    - a local file (.mp3, .mp4, .m4a, .wav, .webm, ...)
+    - a URL (YouTube, X/Twitter, TikTok, Instagram, generic mp4/mp3, ...)
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+
+SAMPLE_RATE = 16000
+FEATURE_DIM = 80
+
+# Auto-download source for the default Kroko English streaming model.
+# The repo ships plain .onnx (no .int8 variants); find_model_file still prefers
+# int8 if a custom --model dir provides them.
+DEFAULT_MODEL_REPO = "csukuangfj/sherpa-onnx-streaming-zipformer-en-kroko-2025-08-06"
+DEFAULT_MODEL_FILES = ("encoder.onnx", "decoder.onnx", "joiner.onnx", "tokens.txt")
+HF_BASE = "https://huggingface.co"
+HTTP_UA = "yapsnap/0.1 (+https://github.com/)"
+
+URL_RE = re.compile(r"^https?://", re.IGNORECASE)
+
+
+# ---------------------------------------------------------------------------
+# Model resolution / auto-download
+# ---------------------------------------------------------------------------
+
+def user_cache_dir() -> Path:
+    """Return a per-user cache dir for storing the auto-downloaded model.
+    Cross-platform: XDG on Linux, ~/Library/Caches on macOS, %LOCALAPPDATA% on Windows.
+    """
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+        return Path(base) / "yapsnap"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Caches" / "yapsnap"
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".cache"
+    return base / "yapsnap"
+
+
+def find_model_file(model_dir: Path, base: str) -> str:
+    """Find encoder/decoder/joiner ONNX, preferring int8."""
+    for name in (f"{base}.int8.onnx", f"{base}.onnx"):
+        p = model_dir / name
+        if p.is_file():
+            return str(p)
+    raise FileNotFoundError(f"No {base}(.int8).onnx found in {model_dir}")
+
+
+def _download(url: str, dest: Path) -> None:
+    """Download a URL to a file, showing simple progress.
+
+    Sends a User-Agent (HuggingFace sometimes rejects the default urllib UA).
+    Sanity-checks tokens.txt as text and .onnx as binary > 1KB, so we fail loud
+    instead of writing an HTML error page to disk.
+    """
+    print(f"  fetching {url}", file=sys.stderr)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_suffix(dest.suffix + ".part")
+
+    req = urllib.request.Request(url, headers={"User-Agent": HTTP_UA})
+    try:
+        resp = urllib.request.urlopen(req)
+    except urllib.error.HTTPError as e:
+        raise RuntimeError(f"HTTP {e.code} {e.reason} for {url}") from e
+    except urllib.error.URLError as e:
+        raise RuntimeError(f"network error for {url}: {e.reason}") from e
+
+    with resp, open(tmp, "wb") as f:
+        total = int(resp.headers.get("Content-Length", 0))
+        read = 0
+        chunk = 1 << 16
+        while True:
+            buf = resp.read(chunk)
+            if not buf:
+                break
+            f.write(buf)
+            read += len(buf)
+            if total:
+                pct = 100.0 * read / total
+                print(f"\r    {read/1e6:.1f} / {total/1e6:.1f} MB  ({pct:.0f}%)",
+                      end="", file=sys.stderr)
+        print("", file=sys.stderr)
+
+    # Sanity check: don't accept tiny HTML error pages as ONNX files.
+    size = tmp.stat().st_size
+    if dest.suffix == ".onnx" and size < 1024:
+        tmp.unlink(missing_ok=True)
+        raise RuntimeError(
+            f"downloaded {dest.name} is only {size} bytes \u2014 likely an error page, not a model"
+        )
+    tmp.replace(dest)
+
+
+def ensure_default_model() -> Path:
+    """Download the default Kroko English model into the user cache if missing.
+    Returns the directory containing encoder/decoder/joiner/tokens."""
+    cache = user_cache_dir() / DEFAULT_MODEL_REPO.replace("/", "__")
+    cache.mkdir(parents=True, exist_ok=True)
+    missing = [f for f in DEFAULT_MODEL_FILES if not (cache / f).is_file()]
+    if not missing:
+        return cache
+
+    print(f"Downloading Kroko English model to {cache}", file=sys.stderr)
+    for fname in missing:
+        url = f"{HF_BASE}/{DEFAULT_MODEL_REPO}/resolve/main/{fname}"
+        try:
+            _download(url, cache / fname)
+        except Exception as e:
+            raise RuntimeError(
+                f"failed to download {fname} from {url}: {e}\n"
+                f"You can download the model manually from {HF_BASE}/{DEFAULT_MODEL_REPO} "
+                f"and pass its directory via --model."
+            ) from e
+    return cache
+
+
+def resolve_model_dir(model_arg: Optional[Path]) -> Path:
+    """Resolve the model directory from CLI arg, env var, or auto-download."""
+    candidate = model_arg or (
+        Path(os.environ["KROKO_MODEL"]) if os.environ.get("KROKO_MODEL") else None
+    )
+    if candidate is not None:
+        if not candidate.is_dir():
+            raise FileNotFoundError(f"--model directory not found: {candidate}")
+        if not (candidate / "tokens.txt").is_file():
+            raise FileNotFoundError(f"tokens.txt not found in {candidate}")
+        return candidate
+    return ensure_default_model()
+
+
+# ---------------------------------------------------------------------------
+# Input handling: download URLs, decode any media to PCM
+# ---------------------------------------------------------------------------
+
+def _require_tool(name: str) -> None:
+    if shutil.which(name) is None:
+        raise RuntimeError(
+            f"required tool '{name}' not found in PATH. "
+            f"Install it and try again (see README)."
+        )
+
+
+def is_url(s: str) -> bool:
+    return bool(URL_RE.match(s))
+
+
+def download_url(url: str, workdir: Path) -> Path:
+    """Use yt-dlp to download audio from any supported URL.
+
+    Format selection is tuned to avoid TikTok's audio-stripped 'Playback video'
+    formats. The chain tries, in order:
+
+      1. download_addr   \u2014 TikTok's regular download format (always carries audio)
+      2. h264            \u2014 TikTok's 'Direct video' h264 format (also has audio)
+      3. bestaudio       \u2014 audio-only stream when offered (YouTube etc.)
+      4. best            \u2014 generic fallback
+
+    The first two are TikTok-specific format IDs; on every other site they
+    simply don't match and yt-dlp falls through to bestaudio/best cleanly.
+
+    Returns path to a single media file in workdir.
+    """
+    _require_tool("yt-dlp")
+    workdir.mkdir(parents=True, exist_ok=True)
+    out_tpl = str(workdir / "%(id)s.%(ext)s")
+    cmd = [
+        "yt-dlp",
+        "--no-playlist",
+        "--no-warnings",
+        "-f", "download_addr/h264/bestaudio/best",
+        "-o", out_tpl,
+        url,
+    ]
+    try:
+        subprocess.run(cmd, check=True)
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(f"yt-dlp failed for {url}: exit {e.returncode}") from e
+
+    files = sorted(p for p in workdir.iterdir() if p.is_file())
+    if not files:
+        raise RuntimeError(f"yt-dlp produced no files for {url}")
+    files.sort(key=lambda p: p.stat().st_size, reverse=True)
+    return files[0]
+
+
+def _has_audio_stream(media_path: Path) -> bool:
+    """Return True if ffprobe finds at least one audio stream."""
+    if shutil.which("ffprobe") is None:
+        # ffprobe ships with ffmpeg; if it's missing, skip the check.
+        return True
+    try:
+        proc = subprocess.run(
+            ["ffprobe", "-v", "error", "-select_streams", "a",
+             "-show_entries", "stream=codec_type", "-of", "csv=p=0",
+             str(media_path)],
+            capture_output=True, check=True, text=True,
+        )
+    except subprocess.CalledProcessError:
+        return False
+    return "audio" in proc.stdout.lower()
+
+
+def decode_to_pcm(media_path: Path, speed: float = 1.0) -> np.ndarray:
+    """Decode any audio/video file ffmpeg understands to 16kHz mono float32.
+    `speed` applies atempo (pitch-preserving). atempo accepts 0.5..2.0 per stage.
+    """
+    _require_tool("ffmpeg")
+
+    if not _has_audio_stream(media_path):
+        raise RuntimeError(
+            f"{media_path.name} has no audio stream that ffmpeg can read. "
+            f"For TikTok this can happen when only the 'Playback video' format was "
+            f"available; updating yt-dlp (pip install -U yt-dlp) usually fixes it."
+        )
+
+    cmd = ["ffmpeg", "-nostdin", "-loglevel", "error", "-i", str(media_path)]
+    if abs(speed - 1.0) > 1e-5:
+        stages, remaining = [], float(speed)
+        while remaining > 2.0:
+            stages.append("atempo=2.0")
+            remaining /= 2.0
+        while remaining < 0.5:
+            stages.append("atempo=0.5")
+            remaining /= 0.5
+        if abs(remaining - 1.0) > 1e-5:
+            stages.append(f"atempo={remaining}")
+        if stages:
+            cmd += ["-filter:a", ",".join(stages)]
+
+    cmd += ["-f", "s16le", "-acodec", "pcm_s16le", "-ac", "1", "-ar", str(SAMPLE_RATE), "-"]
+
+    try:
+        proc = subprocess.run(cmd, capture_output=True, check=True)
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(
+            f"ffmpeg failed for {media_path}: {e.stderr.decode('utf-8', errors='ignore')}"
+        ) from e
+
+    if not proc.stdout:
+        return np.array([], dtype=np.float32)
+    return np.frombuffer(proc.stdout, dtype=np.int16).astype(np.float32) / 32768.0
+
+
+# ---------------------------------------------------------------------------
+# Transcription
+# ---------------------------------------------------------------------------
+
+def _format_mmss(seconds: float) -> str:
+    seconds = max(0.0, float(seconds))
+    m, s = divmod(int(seconds), 60)
+    return f"{m:02d}:{s:02d}"
+
+
+def _join_tokens(tokens: list[str]) -> str:
+    """Reconstruct text from BPE-style tokens that use ▁ for word starts."""
+    out = []
+    for t in tokens:
+        if t.startswith("\u2581"):
+            out.append(" " + t[1:])
+        else:
+            out.append(t)
+    return "".join(out).strip()
+
+
+def _group_into_sentences(tokens: list[str], timestamps: list[float], speed: float
+                          ) -> list[tuple[float, str]]:
+    """Group tokens into sentences ending in .!? and tag each sentence with its
+    start time, scaled by `speed` to map back to original-audio time.
+    """
+    sentences: list[tuple[float, str]] = []
+    buf_tokens: list[str] = []
+    buf_start: Optional[float] = None
+    end_chars = (".", "!", "?")
+
+    for tok, ts in zip(tokens, timestamps):
+        if not buf_tokens:
+            buf_start = ts
+        buf_tokens.append(tok)
+        if tok and tok[-1] in end_chars:
+            text = _join_tokens(buf_tokens)
+            if text:
+                sentences.append(((buf_start or 0.0) * speed, text))
+            buf_tokens = []
+            buf_start = None
+
+    # Flush any trailing tokens with no terminal punctuation.
+    if buf_tokens:
+        text = _join_tokens(buf_tokens)
+        if text:
+            sentences.append(((buf_start or 0.0) * speed, text))
+    return sentences
+
+
+def transcribe(samples: np.ndarray, model_dir: Path,
+               timestamps: bool, speed: float) -> str:
+    import json
+    import sherpa_onnx  # imported lazily so --help is fast
+
+    if len(samples) == 0:
+        return ""
+
+    recognizer = sherpa_onnx.OnlineRecognizer.from_transducer(
+        encoder=find_model_file(model_dir, "encoder"),
+        decoder=find_model_file(model_dir, "decoder"),
+        joiner=find_model_file(model_dir, "joiner"),
+        tokens=str(model_dir / "tokens.txt"),
+        num_threads=os.cpu_count() or 1,
+        sample_rate=SAMPLE_RATE,
+        feature_dim=FEATURE_DIM,
+        decoding_method="greedy_search",
+        provider="cpu",
+        enable_endpoint_detection=False,
+    )
+
+    stream = recognizer.create_stream()
+    stream.accept_waveform(SAMPLE_RATE, samples)
+    # Tail padding flushes the final chunk through the streaming model.
+    tail_len = int(0.66 * SAMPLE_RATE)
+    if tail_len > 0:
+        stream.accept_waveform(SAMPLE_RATE, np.zeros(tail_len, dtype=np.float32))
+    stream.input_finished()
+
+    while recognizer.is_ready(stream):
+        recognizer.decode_stream(stream)
+
+    # In the Python wrapper, OnlineRecognizer.get_result(stream) returns a
+    # plain str (just the text). Different versions expose token/timestamp
+    # data through different paths; try each.
+    text_result = recognizer.get_result(stream)
+    text = (text_result if isinstance(text_result, str)
+            else getattr(text_result, "text", "") or "").strip()
+
+    if not timestamps:
+        return text
+
+    toks, times = _try_extract_timestamps(recognizer, stream, text_result)
+    if not toks or not times or len(toks) != len(times):
+        # No alignment data available for this build of sherpa-onnx; fall
+        # back to plain text and warn the user once.
+        print("warning: this sherpa-onnx build did not return timestamp data; "
+              "emitting plain text instead", file=sys.stderr)
+        return text
+
+    sentences = _group_into_sentences(toks, [float(t) for t in times], speed)
+    return "\n".join(f"[{_format_mmss(t)}] {s}" for t, s in sentences)
+
+
+def _try_extract_timestamps(recognizer, stream, text_result):
+    """Best-effort extraction of (tokens, timestamps) across sherpa-onnx
+    Python wrapper versions. Returns ([], []) if nothing usable is found.
+    """
+    import json
+
+    # Path 1: recognizer.get_result_as_json_string(stream) (C-API parity)
+    json_method = getattr(recognizer, "get_result_as_json_string", None)
+    if callable(json_method):
+        try:
+            parsed = json.loads(json_method(stream))
+            toks = list(parsed.get("tokens") or [])
+            times = list(parsed.get("timestamps") or [])
+            if toks and times:
+                return toks, times
+        except Exception:
+            pass
+
+    # Path 2: stream.result.tokens / stream.result.timestamps
+    sresult = getattr(stream, "result", None)
+    if sresult is not None:
+        toks = list(getattr(sresult, "tokens", None) or [])
+        times = list(getattr(sresult, "timestamps", None) or [])
+        if toks and times:
+            return toks, times
+
+    # Path 3: text_result is itself a struct (some wrappers wrap a struct)
+    if not isinstance(text_result, str) and text_result is not None:
+        toks = list(getattr(text_result, "tokens", None) or [])
+        times = list(getattr(text_result, "timestamps", None) or [])
+        if toks and times:
+            return toks, times
+
+    return [], []
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def _default_output_name(input_arg: str) -> str:
+    """Pick a default output filename in cwd."""
+    if is_url(input_arg):
+        from urllib.parse import urlparse, parse_qs
+
+        parsed = urlparse(input_arg)
+        stem: Optional[str] = None
+
+        # Prefer ?v=<id> on YouTube watch URLs.
+        if "v" in parse_qs(parsed.query):
+            stem = parse_qs(parsed.query)["v"][0]
+        else:
+            # For sites like x.com/user/status/<id>/video/1, the last path segment
+            # is often "1"; pick the longest path segment instead (usually the ID).
+            segments = [s for s in parsed.path.split("/") if s]
+            if segments:
+                stem = max(segments, key=len)
+                # If it has a media extension (e.g. clip.mp4), drop it.
+                stem = re.sub(r"\.(mp3|mp4|m4a|wav|webm|mov|mkv|aac|opus|ogg|flac)$",
+                              "", stem, flags=re.IGNORECASE)
+
+        stem = (stem or "transcript").strip()
+        stem = re.sub(r"[^A-Za-z0-9._-]+", "_", stem) or "transcript"
+        return f"{stem}_transcript.txt"
+    return f"{Path(input_arg).stem}_transcript.txt"
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="yapsnap",
+        description="Snap a local audio/video file or any video URL into a "
+                    "plaintext transcript using sherpa-onnx (Kroko English streaming).",
+    )
+    ap.add_argument("input", help="Local file path or URL (YouTube, X, TikTok, Instagram, mp4/mp3 URL).")
+    ap.add_argument("-o", "--output", type=Path, default=None,
+                    help="Output .txt path (default: ./transcripts/<input>_transcript.txt).")
+    ap.add_argument("--timestamps", action="store_true",
+                    help="Include [MM:SS] sentence-level timestamps in output.")
+    ap.add_argument("--speed", type=float, default=1.5,
+                    help="Audio speedup factor (default 1.5; pitch preserved).")
+    ap.add_argument("--keep-audio", action="store_true",
+                    help="Keep the downloaded/intermediate audio file instead of deleting it.")
+    ap.add_argument("--model", type=Path, default=None,
+                    help="Path to a sherpa-onnx streaming transducer model directory "
+                         "(or set KROKO_MODEL). Default: auto-download Kroko English.")
+    args = ap.parse_args(argv)
+
+    if args.speed <= 0:
+        print("error: --speed must be > 0", file=sys.stderr)
+        return 2
+
+    # Resolve the model first so we fail fast if it can't be obtained.
+    try:
+        model_dir = resolve_model_dir(args.model)
+    except Exception as e:
+        print(f"model error: {e}", file=sys.stderr)
+        return 1
+
+    # Resolve input -> a local media path.
+    tmp_root: Optional[Path] = None
+    cleanup_root: Optional[Path] = None
+    try:
+        if is_url(args.input):
+            tmp_root = Path(tempfile.mkdtemp(prefix="transcribe-"))
+            cleanup_root = None if args.keep_audio else tmp_root
+            try:
+                media_path = download_url(args.input, tmp_root)
+            except Exception as e:
+                print(f"download error: {e}", file=sys.stderr)
+                return 1
+            if args.keep_audio:
+                print(f"audio kept at: {media_path}", file=sys.stderr)
+        else:
+            media_path = Path(args.input)
+            if not media_path.is_file():
+                print(f"error: file not found: {media_path}", file=sys.stderr)
+                return 1
+
+        try:
+            samples = decode_to_pcm(media_path, speed=args.speed)
+        except Exception as e:
+            print(f"decode error: {e}", file=sys.stderr)
+            return 1
+
+        try:
+            text = transcribe(samples, model_dir,
+                              timestamps=args.timestamps, speed=args.speed)
+        except Exception as e:
+            print(f"transcription error: {e}", file=sys.stderr)
+            return 1
+
+        out_path = args.output if args.output else (
+            Path.cwd() / "transcripts" / _default_output_name(args.input)
+        )
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            out_path.write_text(text + "\n", encoding="utf-8")
+        except Exception as e:
+            print(f"error writing output: {e}", file=sys.stderr)
+            return 1
+
+        print(out_path)
+        return 0
+    finally:
+        if cleanup_root is not None and cleanup_root.is_dir():
+            shutil.rmtree(cleanup_root, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())