xscribe 0.1.0__tar.gz

xscribe-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/

xscribe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 edbutlerx
+
+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.

xscribe-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: xscribe
+Version: 0.1.0
+Summary: Transcribe video and audio to markdown with timestamps. Supports local files and streams.
+Project-URL: Homepage, https://github.com/edbutlerx/xscribe
+Project-URL: Issues, https://github.com/edbutlerx/xscribe/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,markdown,transcription,video,whisper
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Requires-Dist: faster-whisper
+Description-Content-Type: text/markdown
+
+# xscribe
+
+**Download and transcribe any online video in minutes.**
+
+Turn any video or audio file into a clean, timestamped markdown transcript. Just point xscribe at a file or stream URL and get a readable transcript — no cloud services, no subscriptions, everything runs locally on your machine.
+
+Powered by [faster-whisper](https://github.com/SYSTRAN/faster-whisper).
+
+## Install
+
+```bash
+pip install xscribe
+```
+
+You also need **ffmpeg** installed on your system:
+
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu/Debian
+sudo apt install ffmpeg
+
+# Windows
+winget install ffmpeg
+```
+
+## Quick start
+
+**Transcribe a video file on your computer:**
+
+```bash
+xscribe interview.mp4
+```
+
+This creates `interview.md` in your current folder with the full transcript and timestamps.
+
+**Transcribe an online video stream:**
+
+```bash
+xscribe "https://stream.example.com/video/playlist.m3u8"
+```
+
+xscribe will download the video first, then transcribe it. You'll need [yt-dlp](https://github.com/yt-dlp/yt-dlp) installed for this (`brew install yt-dlp` or `pip install yt-dlp`).
+
+## Usage examples
+
+```bash
+# Transcribe a podcast episode you downloaded
+xscribe episode-42.mp3
+
+# Transcribe a lecture recording
+xscribe lecture.mov
+
+# Transcribe a YouTube stream you grabbed the URL for
+xscribe "https://manifest.googlevideo.com/.../playlist.m3u8"
+
+# Use a more accurate model (slower but better for tricky audio)
+xscribe meeting.mp4 -m large-v3
+
+# Save the transcript to a specific file
+xscribe keynote.mp4 -o keynote-notes.md
+```
+
+**Supported file types:** mp4, mp3, wav, mov, mkv, webm, m4a, flac, ogg, and anything else ffmpeg can read.
+
+## How to get an .m3u8 URL from any website
+
+Most streaming videos use .m3u8 playlist URLs behind the scenes. Here's how to find them:
+
+1. Open the website with the video in Chrome or any browser
+2. Right-click anywhere on the page and select **Inspect** (or press `F12`)
+3. Click the **Network** tab in the developer tools panel
+4. Play the video on the page
+5. In the Network tab's filter/search bar, type `.m3u8`
+6. You'll see one or more requests appear — right-click the URL and select **Copy URL**
+7. Paste it into xscribe: `xscribe "https://...your-copied-url.m3u8"`
+
+## Model sizes
+
+xscribe uses OpenAI's Whisper speech recognition. You can choose different model sizes depending on whether you want speed or accuracy:
+
+| Model | Flag | Best for |
+|-------|------|----------|
+| Tiny | `-m tiny` | Quick and dirty, when you just need the gist |
+| Base | *(default)* | General use, good balance of speed and quality |
+| Small | `-m small` | Better accuracy, still reasonably fast |
+| Medium | `-m medium` | High accuracy for important transcripts |
+| Large | `-m large-v3` | Best possible accuracy, but slowest |
+
+The model downloads automatically the first time you use it and gets cached for future runs.
+
+## Output format
+
+xscribe saves transcripts as markdown files with timestamps:
+
+```markdown
+# Transcription
+
+**Source:** `interview.mp4`
+
+---
+
+**[00:03]** Hello and welcome to the show.
+
+**[00:07]** Today we're joined by a special guest...
+
+**[01:24]** Let's dive into the first topic.
+```
+
+## License
+
+MIT

xscribe-0.1.0/README.md

@@ -0,0 +1,113 @@
+# xscribe
+
+**Download and transcribe any online video in minutes.**
+
+Turn any video or audio file into a clean, timestamped markdown transcript. Just point xscribe at a file or stream URL and get a readable transcript — no cloud services, no subscriptions, everything runs locally on your machine.
+
+Powered by [faster-whisper](https://github.com/SYSTRAN/faster-whisper).
+
+## Install
+
+```bash
+pip install xscribe
+```
+
+You also need **ffmpeg** installed on your system:
+
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu/Debian
+sudo apt install ffmpeg
+
+# Windows
+winget install ffmpeg
+```
+
+## Quick start
+
+**Transcribe a video file on your computer:**
+
+```bash
+xscribe interview.mp4
+```
+
+This creates `interview.md` in your current folder with the full transcript and timestamps.
+
+**Transcribe an online video stream:**
+
+```bash
+xscribe "https://stream.example.com/video/playlist.m3u8"
+```
+
+xscribe will download the video first, then transcribe it. You'll need [yt-dlp](https://github.com/yt-dlp/yt-dlp) installed for this (`brew install yt-dlp` or `pip install yt-dlp`).
+
+## Usage examples
+
+```bash
+# Transcribe a podcast episode you downloaded
+xscribe episode-42.mp3
+
+# Transcribe a lecture recording
+xscribe lecture.mov
+
+# Transcribe a YouTube stream you grabbed the URL for
+xscribe "https://manifest.googlevideo.com/.../playlist.m3u8"
+
+# Use a more accurate model (slower but better for tricky audio)
+xscribe meeting.mp4 -m large-v3
+
+# Save the transcript to a specific file
+xscribe keynote.mp4 -o keynote-notes.md
+```
+
+**Supported file types:** mp4, mp3, wav, mov, mkv, webm, m4a, flac, ogg, and anything else ffmpeg can read.
+
+## How to get an .m3u8 URL from any website
+
+Most streaming videos use .m3u8 playlist URLs behind the scenes. Here's how to find them:
+
+1. Open the website with the video in Chrome or any browser
+2. Right-click anywhere on the page and select **Inspect** (or press `F12`)
+3. Click the **Network** tab in the developer tools panel
+4. Play the video on the page
+5. In the Network tab's filter/search bar, type `.m3u8`
+6. You'll see one or more requests appear — right-click the URL and select **Copy URL**
+7. Paste it into xscribe: `xscribe "https://...your-copied-url.m3u8"`
+
+## Model sizes
+
+xscribe uses OpenAI's Whisper speech recognition. You can choose different model sizes depending on whether you want speed or accuracy:
+
+| Model | Flag | Best for |
+|-------|------|----------|
+| Tiny | `-m tiny` | Quick and dirty, when you just need the gist |
+| Base | *(default)* | General use, good balance of speed and quality |
+| Small | `-m small` | Better accuracy, still reasonably fast |
+| Medium | `-m medium` | High accuracy for important transcripts |
+| Large | `-m large-v3` | Best possible accuracy, but slowest |
+
+The model downloads automatically the first time you use it and gets cached for future runs.
+
+## Output format
+
+xscribe saves transcripts as markdown files with timestamps:
+
+```markdown
+# Transcription
+
+**Source:** `interview.mp4`
+
+---
+
+**[00:03]** Hello and welcome to the show.
+
+**[00:07]** Today we're joined by a special guest...
+
+**[01:24]** Let's dive into the first topic.
+```
+
+## License
+
+MIT

xscribe-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "xscribe"
+version = "0.1.0"
+description = "Transcribe video and audio to markdown with timestamps. Supports local files and streams."
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+keywords = ["transcription", "whisper", "video", "audio", "markdown"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+dependencies = [
+    "faster-whisper",
+]
+
+[project.scripts]
+xscribe = "xscribe:main"
+
+[project.urls]
+Homepage = "https://github.com/edbutlerx/xscribe"
+Issues = "https://github.com/edbutlerx/xscribe/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

xscribe-0.1.0/xscribe.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""Video transcription CLI. Transcribes video/audio files to markdown with timestamps."""
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+import threading
+from pathlib import Path
+
+
+def is_stream_url(path: str) -> bool:
+    return path.startswith("http://") or path.startswith("https://") or path.endswith(".m3u8")
+
+
+def download_stream(url: str, output_dir: str) -> str:
+    """Download a stream URL using yt-dlp and return the output file path."""
+    output_path = os.path.join(output_dir, "downloaded_video.%(ext)s")
+    cmd = [
+        "yt-dlp",
+        "-o", output_path,
+        "--no-playlist",
+        url,
+    ]
+    spinner = ProgressSpinner("Downloading stream...")
+    spinner.start()
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        spinner.stop("✗ Download failed")
+        print(f"yt-dlp error: {result.stderr}", file=sys.stderr)
+        sys.exit(1)
+    spinner.stop("✓ Download complete")
+
+    # Find the downloaded file
+    for f in os.listdir(output_dir):
+        if f.startswith("downloaded_video"):
+            return os.path.join(output_dir, f)
+
+    print("Error: could not find downloaded file", file=sys.stderr)
+    sys.exit(1)
+
+
+SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+
+def get_audio_duration(file_path: str) -> float | None:
+    """Get duration of a media file in seconds using ffprobe."""
+    try:
+        result = subprocess.run(
+            ["ffprobe", "-v", "quiet", "-show_entries", "format=duration",
+             "-of", "default=noprint_wrappers=1:nokey=1", file_path],
+            capture_output=True, text=True,
+        )
+        return float(result.stdout.strip())
+    except (ValueError, FileNotFoundError):
+        return None
+
+
+class ProgressSpinner:
+    """Spinner with percentage progress on a single line."""
+
+    def __init__(self, label: str, total: float | None = None):
+        self.label = label
+        self.total = total
+        self.current = 0.0
+        self._stop = threading.Event()
+        self._frame = 0
+        self._thread = threading.Thread(target=self._spin, daemon=True)
+
+    def start(self):
+        self._thread.start()
+
+    def update(self, value: float):
+        self.current = value
+
+    def _spin(self):
+        while not self._stop.is_set():
+            frame = SPINNER_FRAMES[self._frame % len(SPINNER_FRAMES)]
+            if self.total and self.total > 0:
+                pct = min(self.current / self.total * 100, 100)
+                sys.stdout.write(f"\r{frame} {self.label} {pct:.0f}%")
+            else:
+                sys.stdout.write(f"\r{frame} {self.label}")
+            sys.stdout.flush()
+            self._frame += 1
+            self._stop.wait(0.1)
+
+    def stop(self, final_message: str = ""):
+        self._stop.set()
+        self._thread.join()
+        sys.stdout.write(f"\r\033[K{final_message}\n")
+        sys.stdout.flush()
+
+
+def format_timestamp(seconds: float) -> str:
+    """Format seconds into HH:MM:SS."""
+    h = int(seconds // 3600)
+    m = int((seconds % 3600) // 60)
+    s = int(seconds % 60)
+    if h > 0:
+        return f"{h:02d}:{m:02d}:{s:02d}"
+    return f"{m:02d}:{s:02d}"
+
+
+def transcribe(file_path: str, model_size: str) -> list[dict]:
+    """Transcribe a file using faster-whisper. Returns list of segments."""
+    try:
+        from faster_whisper import WhisperModel
+    except ImportError:
+        print("Error: faster-whisper is not installed.", file=sys.stderr)
+        print("Install it with: pip install faster-whisper", file=sys.stderr)
+        sys.exit(1)
+
+    duration = get_audio_duration(file_path)
+
+    spinner = ProgressSpinner("Loading model...", total=None)
+    spinner.start()
+    model = WhisperModel(model_size, device="auto", compute_type="auto")
+    spinner.stop(f"✓ Model loaded: {model_size}")
+
+    spinner = ProgressSpinner("Transcribing...", total=duration)
+    spinner.start()
+    segments_gen, info = model.transcribe(file_path, beam_size=5)
+
+    segments = []
+    for segment in segments_gen:
+        segments.append({
+            "start": segment.start,
+            "end": segment.end,
+            "text": segment.text.strip(),
+        })
+        spinner.update(segment.end)
+
+    spinner.stop(f"✓ Transcription complete ({info.language})")
+
+    return segments
+
+
+def write_markdown(segments: list[dict], output_path: str, source: str):
+    """Write transcription segments to a markdown file."""
+    with open(output_path, "w") as f:
+        f.write(f"# Transcription\n\n")
+        f.write(f"**Source:** `{source}`\n\n")
+        f.write("---\n\n")
+
+        for seg in segments:
+            ts = format_timestamp(seg["start"])
+            f.write(f"**[{ts}]** {seg['text']}\n\n")
+
+    print(f"✓ Saved to: {output_path}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Transcribe video/audio to markdown with timestamps.")
+    parser.add_argument("input", help="File path or stream URL (m3u8, etc.) to transcribe")
+    parser.add_argument("-o", "--output", help="Output markdown file path (default: <input_name>.md)")
+    parser.add_argument("-m", "--model", default="base", choices=["tiny", "base", "small", "medium", "large-v3"],
+                        help="Whisper model size (default: base)")
+    args = parser.parse_args()
+
+    source = args.input
+    temp_dir = None
+
+    try:
+        if is_stream_url(source):
+            temp_dir = tempfile.mkdtemp(prefix="xscribe_")
+            file_path = download_stream(source, temp_dir)
+        else:
+            file_path = os.path.abspath(source)
+            if not os.path.isfile(file_path):
+                print(f"Error: file not found: {file_path}", file=sys.stderr)
+                sys.exit(1)
+
+        # Determine output path
+        if args.output:
+            output_path = os.path.abspath(args.output)
+        else:
+            base_name = Path(source).stem if not is_stream_url(source) else "transcription"
+            output_path = os.path.join(os.getcwd(), f"{base_name}.md")
+
+        segments = transcribe(file_path, args.model)
+
+        if not segments:
+            print("No speech detected.", file=sys.stderr)
+            sys.exit(1)
+
+        write_markdown(segments, output_path, source)
+
+    finally:
+        # Clean up temp files
+        if temp_dir and os.path.exists(temp_dir):
+            import shutil
+            shutil.rmtree(temp_dir)
+
+
+if __name__ == "__main__":
+    main()