stt2vtt 0.0.1__tar.gz

stt2vtt-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - '*'
+
+jobs:
+  pypi:
+    name: "Publish to PyPI"
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish -t ${{ secrets.PYPI_TOKEN }}

stt2vtt-0.0.1/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[dev]
+    
+    - name: Run tests
+      run: |
+        pytest tests/ -v --tb=short
+

stt2vtt-0.0.1/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment
+.env
+.env.local
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Models (large files)
+models/
+
+# Temporary files
+*.tmp
+*.log
+.DS_Store

stt2vtt-0.0.1/.python-version

@@ -0,0 +1 @@
+3.12

stt2vtt-0.0.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 audio-subtitler contributors
+
+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.
+

stt2vtt-0.0.1/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include src *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+

stt2vtt-0.0.1/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: stt2vtt
+Version: 0.0.1
+Summary: Convert STT result (Azure or fast-whisper JSON) to WebVTT
+Author: Gary Lab
+License: MIT License
+        
+        Copyright (c) 2025 audio-subtitler contributors
+        
+        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.
+        
+        
+Project-URL: Homepage, https://github.com/garylab/stt2vtt
+Project-URL: Author Blog, https://garymeng.com
+Keywords: stt,vtt,webvtt,subtitles,speech-to-text,azure,whisper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# stt2vtt
+
+Convert STT (speech-to-text) results with timestamps to WebVTT. Input can be JSON from **Azure Speech-to-Text** or **fast-whisper** (or compatible segment + word timestamps). Output is VTT text.
+
+No audio processing or ML models — this repo only converts existing STT JSON to VTT.
+
+## Installation
+
+```bash
+pip install stt2vtt
+```
+
+Dev dependencies:
+
+```bash
+pip install stt2vtt[dev]
+```
+
+## Usage
+
+### CLI
+
+```bash
+# From file
+stt2vtt result.json -o output.vtt
+
+# To stdout
+stt2vtt result.json
+
+# From stdin
+cat result.json | stt2vtt -o output.vtt
+```
+
+### Python
+
+```python
+from src.stt_to_vtt import stt_to_vtt
+
+# JSON string or parsed list/dict
+vtt = stt_to_vtt('{"phrases": [...]}')   # Azure style
+vtt = stt_to_vtt([{"id": 1, "start": 0, "end": 1, "text": "...", "words": [...]}])  # fast-whisper style
+
+print(vtt)  # "WEBVTT\n\n00:00:00.000 --> ..."
+```
+
+## Input formats
+
+- **fast-whisper**: List of segments, each with `start`, `end`, `text`, and `words` (list of `{start, end, word}`).
+- **Azure**: Object with `phrases` (or `recognizedPhrases`), each phrase with `offsetMilliseconds`, `durationMilliseconds`, and `words` with `text`, `offsetMilliseconds`, `durationMilliseconds`.
+
+## Output
+
+WebVTT subtitle content: `WEBVTT` header plus timestamped cues with capitalized text.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

stt2vtt-0.0.1/README.md

@@ -0,0 +1,57 @@
+# stt2vtt
+
+Convert STT (speech-to-text) results with timestamps to WebVTT. Input can be JSON from **Azure Speech-to-Text** or **fast-whisper** (or compatible segment + word timestamps). Output is VTT text.
+
+No audio processing or ML models — this repo only converts existing STT JSON to VTT.
+
+## Installation
+
+```bash
+pip install stt2vtt
+```
+
+Dev dependencies:
+
+```bash
+pip install stt2vtt[dev]
+```
+
+## Usage
+
+### CLI
+
+```bash
+# From file
+stt2vtt result.json -o output.vtt
+
+# To stdout
+stt2vtt result.json
+
+# From stdin
+cat result.json | stt2vtt -o output.vtt
+```
+
+### Python
+
+```python
+from src.stt_to_vtt import stt_to_vtt
+
+# JSON string or parsed list/dict
+vtt = stt_to_vtt('{"phrases": [...]}')   # Azure style
+vtt = stt_to_vtt([{"id": 1, "start": 0, "end": 1, "text": "...", "words": [...]}])  # fast-whisper style
+
+print(vtt)  # "WEBVTT\n\n00:00:00.000 --> ..."
+```
+
+## Input formats
+
+- **fast-whisper**: List of segments, each with `start`, `end`, `text`, and `words` (list of `{start, end, word}`).
+- **Azure**: Object with `phrases` (or `recognizedPhrases`), each phrase with `offsetMilliseconds`, `durationMilliseconds`, and `words` with `text`, `offsetMilliseconds`, `durationMilliseconds`.
+
+## Output
+
+WebVTT subtitle content: `WEBVTT` header plus timestamped cues with capitalized text.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

stt2vtt-0.0.1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "stt2vtt"
+dynamic = ["version"]
+description = "Convert STT result (Azure or fast-whisper JSON) to WebVTT"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Gary Lab"},
+]
+keywords = ["stt", "vtt", "webvtt", "subtitles", "speech-to-text", "azure", "whisper"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = []
+
+[project.scripts]
+stt2vtt = "src.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/garylab/stt2vtt"
+"Author Blog" = "https://garymeng.com"
+
+[build-system]
+requires = ["setuptools>=61.0", "setuptools-scm"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+version_scheme = "post-release"
+local_scheme = "no-local-version"
+
+[tool.setuptools]
+packages = ["src"]

stt2vtt-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stt2vtt-0.0.1/src/__init__.py

@@ -0,0 +1,5 @@
+from .stt_to_vtt import stt_to_vtt
+
+__version__ = "0.1.0"
+__author__ = "Gary Lab"
+__all__ = ["stt_to_vtt"]

stt2vtt-0.0.1/src/cli.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Command-line interface: read STT JSON, write VTT."""
+
+import sys
+import argparse
+from pathlib import Path
+
+from src.stt_to_vtt import stt_to_vtt
+
+__version__ = "0.1.0"
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Convert STT result (Azure or fast-whisper JSON) to WebVTT",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  stt2vtt result.json -o output.vtt
+  stt2vtt result.json
+  cat result.json | stt2vtt -o output.vtt
+        """,
+    )
+    parser.add_argument(
+        "input",
+        nargs="?",
+        type=str,
+        default=None,
+        help="Input JSON file (STT result). Omit to read from stdin.",
+    )
+    parser.add_argument(
+        "-o", "--output",
+        type=str,
+        default=None,
+        help="Output VTT file (default: stdout)",
+    )
+    parser.add_argument(
+        "-q", "--quiet",
+        action="store_true",
+        help="Suppress messages",
+    )
+    parser.add_argument(
+        "-v", "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    args = parser.parse_args()
+
+    try:
+        if args.input:
+            path = Path(args.input)
+            if not path.exists():
+                print(f"Error: Input file not found: {args.input}", file=sys.stderr)
+                sys.exit(1)
+            if not path.is_file():
+                print(f"Error: Not a file: {args.input}", file=sys.stderr)
+                sys.exit(1)
+            content = path.read_text(encoding="utf-8")
+        else:
+            content = sys.stdin.read()
+
+        vtt = stt_to_vtt(content)
+
+        if args.output:
+            Path(args.output).write_text(vtt, encoding="utf-8")
+            if not args.quiet:
+                print(f"Written: {args.output}", file=sys.stderr)
+        else:
+            print(vtt)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except KeyboardInterrupt:
+        print("\nInterrupted", file=sys.stderr)
+        sys.exit(130)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        if not args.quiet:
+            import traceback
+            traceback.print_exc(file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

stt2vtt-0.0.1/src/stt_to_vtt.py

@@ -0,0 +1,193 @@
+"""Convert STT (speech-to-text) results with timestamps to WebVTT.
+
+Supports input from Azure Speech-to-Text or fast-whisper style JSON.
+"""
+
+import json
+from types import SimpleNamespace
+from typing import Any, List, Union
+
+STOP_CHARS = set(
+    ".!?,:;…‥"
+    "。！？，、；："
+    "।"
+    "܀።፧"
+    "؟؛"
+    "၊။"
+    "⸮⁇⁈⁉"
+)
+
+
+def _seconds_to_vtt_time(seconds: float) -> str:
+    hours = int(seconds // 3600)
+    seconds = seconds % 3600
+    minutes = int(seconds // 60)
+    milliseconds = int(seconds * 1000) % 1000
+    secs = int(seconds % 60)
+    return f"{hours:02d}:{minutes:02d}:{secs:02d}.{milliseconds:03d}"
+
+
+def _capitalize_text(text: str) -> str:
+    text = text.strip()
+    return text[0].upper() + text[1:] if text else text
+
+
+def _end_with_stop_char(text: str) -> bool:
+    if not text:
+        return False
+    return any(text.endswith(c) for c in STOP_CHARS)
+
+
+def _normalize_fast_whisper(segments: List[Any]) -> List[SimpleNamespace]:
+    """Normalize fast-whisper style segments to internal format."""
+    out = []
+    for seg in segments:
+        words = []
+        for w in seg.get("words", []):
+            start = float(w.get("start", 0))
+            end = float(w.get("end", 0))
+            word = w.get("word", "")
+            words.append(SimpleNamespace(start=start, end=end, word=word))
+        start = float(seg.get("start", 0))
+        end = float(seg.get("end", 0))
+        if words and start == 0 and end == 0:
+            start = words[0].start
+            end = words[-1].end
+        out.append(
+            SimpleNamespace(
+                start=start,
+                end=end,
+                text=seg.get("text", ""),
+                words=words,
+            )
+        )
+    return out
+
+
+def _normalize_azure(data: Any) -> List[SimpleNamespace]:
+    """Normalize Azure Speech-to-Text result to internal format."""
+    phrases = data.get("phrases") or data.get("recognizedPhrases") or []
+    if not phrases and isinstance(data, list):
+        phrases = data
+    out = []
+    for p in phrases:
+        words = []
+        for w in p.get("words", []):
+            offset_ms = w.get("offsetMilliseconds", w.get("offset", 0))
+            duration_ms = w.get("durationMilliseconds", w.get("duration", 0))
+            start = offset_ms / 1000.0
+            end = start + duration_ms / 1000.0
+            word = w.get("text", w.get("word", ""))
+            words.append(SimpleNamespace(start=start, end=end, word=word))
+        offset_ms = p.get("offsetMilliseconds", p.get("offset", 0))
+        duration_ms = p.get("durationMilliseconds", p.get("duration", 0))
+        start = offset_ms / 1000.0
+        end = start + duration_ms / 1000.0
+        if words and (duration_ms == 0 or end <= start):
+            start = words[0].start
+            end = words[-1].end
+        out.append(
+            SimpleNamespace(
+                start=start,
+                end=end,
+                text=p.get("text", p.get("display", "")),
+                words=words,
+            )
+        )
+    return out
+
+
+def _detect_and_normalize(data: Any) -> List[SimpleNamespace]:
+    """Detect input format and return normalized segments."""
+    if isinstance(data, str):
+        data = json.loads(data)
+    if isinstance(data, list) and data and isinstance(data[0], dict):
+        seg = data[0]
+        if "words" in seg and seg["words"]:
+            w = seg["words"][0]
+            if "start" in w and "end" in w and "word" in w:
+                return _normalize_fast_whisper(data)
+        if "offsetMilliseconds" in seg or "offset" in seg:
+            return _normalize_azure(data)
+        return _normalize_fast_whisper(data)
+    if isinstance(data, dict):
+        if "phrases" in data or "recognizedPhrases" in data:
+            return _normalize_azure(data)
+        if "segments" in data:
+            return _detect_and_normalize(data["segments"])
+    raise ValueError("Unsupported STT result format: expected list of segments or Azure-style dict with 'phrases'.")
+
+
+def _segments_to_subtitle(segments: List[SimpleNamespace]) -> List[dict]:
+    subtitles = []
+    for segment in segments:
+        words_idx = 0
+        words_len = len(segment.words)
+        seg_start = 0.0
+        seg_end = 0.0
+        seg_text = ""
+
+        if segment.words:
+            is_segmented = False
+            for word in segment.words:
+                if not is_segmented:
+                    seg_start = word.start
+                    is_segmented = True
+                seg_end = word.end
+                seg_text += word.word
+
+                if _end_with_stop_char(word.word):
+                    seg_text = seg_text[:-1]
+                    if not seg_text:
+                        continue
+                    if seg_start < seg_end and seg_text.strip():
+                        subtitles.append(
+                            {"msg": seg_text, "start_time": seg_start, "end_time": seg_end}
+                        )
+                    is_segmented = False
+                    seg_text = ""
+
+                if words_idx == 0 and segment.start < word.start:
+                    seg_start = word.start
+                if words_idx == (words_len - 1) and segment.end > word.end:
+                    seg_end = segment.end
+                words_idx += 1
+
+        if not seg_text:
+            continue
+        if seg_start < seg_end and seg_text.strip():
+            subtitles.append(
+                {"msg": seg_text, "start_time": seg_start, "end_time": seg_end}
+            )
+    return subtitles
+
+
+def _format_vtt(subtitles: List[dict]) -> str:
+    lines = []
+    for sub in subtitles:
+        msg = sub.get("msg")
+        if not msg:
+            continue
+        start = sub.get("start_time", 0)
+        end = sub.get("end_time", 0)
+        start_str = _seconds_to_vtt_time(start)
+        end_str = _seconds_to_vtt_time(end)
+        text = _capitalize_text(msg)
+        lines.append(f"{start_str} --> {end_str}\n{text}\n")
+    return "WEBVTT\n\n" + "\n".join(lines)
+
+
+def stt_to_vtt(stt_result: Union[str, bytes, list, dict]) -> str:
+    """Convert STT result (Azure or fast-whisper style) to WebVTT text.
+
+    Args:
+        stt_result: JSON string, parsed list of segments, or Azure-style dict.
+
+    Returns:
+        WebVTT subtitle content as a string.
+    """
+    if isinstance(stt_result, bytes):
+        stt_result = stt_result.decode("utf-8")
+    segments = _detect_and_normalize(stt_result)
+    subtitles = _segments_to_subtitle(segments)
+    return _format_vtt(subtitles)