whisper-smith 0.1.0__tar.gz

whisper_smith-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# IDE
+.idea/
+.nova/
+
+.ruff_cache/
+
+# Data directory
+data/
+!data/.gitkeep
+
+# macOS
+.DS_Store

whisper_smith-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

whisper_smith-0.1.0/.readthedocs.yaml

@@ -0,0 +1,17 @@
+# .readthedocs.yaml
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/source/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

whisper_smith-0.1.0/LICENSE

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

whisper_smith-0.1.0/Makefile

@@ -0,0 +1,27 @@
+.PHONY: help clean
+
+# --- Variables ---
+
+.DEFAULT_GOAL := help
+
+# --- General Targets ---
+
+help: ## Show this help message
+	@echo "Usage: make [target]"
+	@echo ""
+	@echo "Targets:"
+	@printf "  \033[36m%-28s\033[0m %s\n" "help" "Show this help message"
+	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) \
+		| grep -v '^help:' \
+		| sort \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-28s\033[0m %s\n", $$1, $$2}'
+
+
+clean: ## Remove cache files and generated local artifacts
+	@echo "Cleaning up..."
+	@find . -type d -name "__pycache__" -not -path "*/.venv/*" -exec rm -rf {} +
+	@find . -type d -name ".pytest_cache" -not -path "*/.venv/*" -exec rm -rf {} +
+	@find . -type d -name ".ruff_cache" -not -path "*/.venv/*" -exec rm -rf {} +
+	@rm -rf .coverage htmlcov/
+	@echo "Cleanup complete."
+

whisper_smith-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: whisper-smith
+Version: 0.1.0
+Summary: A small Python transcription helper using OpenAI speech-to-text APIs.
+Project-URL: Documentation, https://whisper-smith.readthedocs.io/
+Project-URL: Homepage, https://github.com/yeiichi/whisper-smith
+Project-URL: Repository, https://github.com/yeiichi/whisper-smith
+Project-URL: Issues, https://github.com/yeiichi/whisper-smith/issues
+Author-email: Eiichi YAMAMOTO <info@yeiichi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,diarization,openai,speech-to-text,transcription
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: imageio-ffmpeg
+Requires-Dist: openai
+Requires-Dist: python-dotenv
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Provides-Extra: diarize
+Requires-Dist: huggingface-hub<1; extra == 'diarize'
+Requires-Dist: numpy<2; extra == 'diarize'
+Requires-Dist: pyannote-audio; extra == 'diarize'
+Requires-Dist: torch<2.9; extra == 'diarize'
+Requires-Dist: torchaudio<2.9; extra == 'diarize'
+Description-Content-Type: text/markdown
+
+# whisper-smith
+
+[![PyPI version](https://img.shields.io/pypi/v/whisper-smith)](https://pypi.org/project/whisper-smith/)
+[![Python versions](https://img.shields.io/pypi/pyversions/whisper-smith)](https://pypi.org/project/whisper-smith/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/yeiichi/whisper-smith/blob/main/LICENSE)
+[![Docs](https://readthedocs.org/projects/whisper-smith/badge/?version=latest)](https://whisper-smith.readthedocs.io/)
+
+`whisper-smith` is a small Python CLI/app helper for transcribing audio files with OpenAI speech-to-text models.
+
+## Features
+
+- Transcribe local audio files
+- CLI-first workflow for quick terminal use
+- Output as `txt`, `json`, `srt`, or `vtt`
+- Automatically infer output format from output file extension
+- Load environment variables from `.env`
+
+## Requirements
+
+- Python `3.10+`
+- An OpenAI API key (`OPENAI_API_KEY`)
+- For large-file fallback: either system `ffmpeg` in `PATH`, or Python package `imageio-ffmpeg`
+- For optional speaker diarization: a Hugging Face token (`HUGGINGFACE_TOKEN`) and `pyannote.audio`
+
+## Installation
+
+### Option 1: uv (recommended)
+
+```bash
+uv sync
+```
+
+### Option 2: pip
+
+```bash
+pip install -e .
+```
+
+### Optional speaker diarization dependencies
+
+```bash
+uv sync --extra diarize
+```
+
+or:
+
+```bash
+pip install -e ".[diarize]"
+```
+
+## Configuration
+
+Set your API key in the environment or in a `.env` file:
+
+```bash
+export OPENAI_API_KEY="your_api_key_here"
+export HUGGINGFACE_TOKEN="your_huggingface_token_here"
+```
+
+Or create `.env` in project root:
+
+```env
+OPENAI_API_KEY=your_api_key_here
+HUGGINGFACE_TOKEN=your_huggingface_token_here
+```
+
+## CLI Usage Guide
+
+Basic command:
+
+```bash
+whisper-smith <audio_path>
+```
+
+Show help:
+
+```bash
+whisper-smith --help
+```
+
+### 1) Print transcript to terminal (default `txt`)
+
+```bash
+whisper-smith data/sample.m4a
+```
+
+### 2) Save transcript to a file
+
+```bash
+whisper-smith data/sample.m4a --output data/sample.txt
+```
+
+### 3) Choose output format explicitly
+
+```bash
+whisper-smith data/sample.m4a --format json --output data/sample.json
+```
+
+Supported CLI formats: `txt`, `json`, `srt`, `vtt`
+
+### 4) Let format be inferred from output extension
+
+```bash
+whisper-smith data/sample.m4a --output data/sample.srt
+```
+
+### 5) Overwrite existing file
+
+```bash
+whisper-smith data/sample.m4a --output data/sample.txt --overwrite
+```
+
+### 6) Run speaker diarization
+
+```bash
+whisper-smith data/sample.m4a --diarize --output data/sample.diarization.json
+```
+
+Diarization currently supports JSON output only. Optional speaker hints:
+
+```bash
+whisper-smith data/sample.m4a --diarize --format json --num-speakers 2
+```
+
+### 7) Create speaker-aligned transcript JSON
+
+Run the full pipeline from one audio file:
+
+```bash
+whisper-smith data/sample.m4a --align --output data/sample.aligned.json
+```
+
+This writes the main aligned transcript JSON to `data/sample.aligned.json` and
+also writes intermediate artifacts beside it:
+
+```text
+data/sample.transcript.json
+data/sample.diarization.json
+```
+
+To put the intermediate artifacts in a separate directory:
+
+```bash
+whisper-smith data/sample.m4a --align --output data/sample.aligned.json --artifacts-dir data/artifacts
+```
+
+## Python Usage
+
+```python
+from pathlib import Path
+from whisper_smith.transcribe import transcribe_audio
+from whisper_smith.exporters import export_transcript
+
+result = transcribe_audio(Path("data/sample.m4a"))
+print(result.text)
+
+srt = export_transcript(result, "srt")
+Path("data/sample.srt").write_text(srt, encoding="utf-8")
+```
+
+### Speaker diarization
+
+```python
+from pathlib import Path
+from whisper_smith.diarize import diarize_audio
+
+result = diarize_audio(Path("data/sample.m4a"))
+
+for segment in result.segments:
+    print(segment.start, segment.end, segment.speaker)
+```
+
+`diarize_audio` uses `HUGGINGFACE_TOKEN` from the environment, or accepts
+`hf_token="..."` explicitly.
+
+The default local model is `pyannote/speaker-diarization-3.1`, which is compatible
+with the Intel macOS dependency set. You may pass a different model explicitly
+from Python when running on a newer platform.
+
+## Notes
+
+- If `--output` is omitted, transcript is printed to stdout.
+- If `--format` is omitted, format is inferred from `--output` extension when possible.
+- If an output file already exists, add `--overwrite` to replace it.
+- Transcription uses a timestamp-capable OpenAI model by default so JSON, SRT,
+  and VTT outputs have segment timestamps.
+- For large audio files, `whisper-smith` automatically splits audio into chunks and
+  merges transcript text.
+- If diarization fails with `torchaudio` missing `AudioMetaData`, refresh the
+  optional diarization dependencies with `uv lock --upgrade-package torch
+  --upgrade-package torchaudio` and then `uv sync --extra diarize`.
+
+## Development
+
+Run tests:
+
+```bash
+pytest
+```

whisper_smith-0.1.0/README.md

@@ -0,0 +1,199 @@
+# whisper-smith
+
+[![PyPI version](https://img.shields.io/pypi/v/whisper-smith)](https://pypi.org/project/whisper-smith/)
+[![Python versions](https://img.shields.io/pypi/pyversions/whisper-smith)](https://pypi.org/project/whisper-smith/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/yeiichi/whisper-smith/blob/main/LICENSE)
+[![Docs](https://readthedocs.org/projects/whisper-smith/badge/?version=latest)](https://whisper-smith.readthedocs.io/)
+
+`whisper-smith` is a small Python CLI/app helper for transcribing audio files with OpenAI speech-to-text models.
+
+## Features
+
+- Transcribe local audio files
+- CLI-first workflow for quick terminal use
+- Output as `txt`, `json`, `srt`, or `vtt`
+- Automatically infer output format from output file extension
+- Load environment variables from `.env`
+
+## Requirements
+
+- Python `3.10+`
+- An OpenAI API key (`OPENAI_API_KEY`)
+- For large-file fallback: either system `ffmpeg` in `PATH`, or Python package `imageio-ffmpeg`
+- For optional speaker diarization: a Hugging Face token (`HUGGINGFACE_TOKEN`) and `pyannote.audio`
+
+## Installation
+
+### Option 1: uv (recommended)
+
+```bash
+uv sync
+```
+
+### Option 2: pip
+
+```bash
+pip install -e .
+```
+
+### Optional speaker diarization dependencies
+
+```bash
+uv sync --extra diarize
+```
+
+or:
+
+```bash
+pip install -e ".[diarize]"
+```
+
+## Configuration
+
+Set your API key in the environment or in a `.env` file:
+
+```bash
+export OPENAI_API_KEY="your_api_key_here"
+export HUGGINGFACE_TOKEN="your_huggingface_token_here"
+```
+
+Or create `.env` in project root:
+
+```env
+OPENAI_API_KEY=your_api_key_here
+HUGGINGFACE_TOKEN=your_huggingface_token_here
+```
+
+## CLI Usage Guide
+
+Basic command:
+
+```bash
+whisper-smith <audio_path>
+```
+
+Show help:
+
+```bash
+whisper-smith --help
+```
+
+### 1) Print transcript to terminal (default `txt`)
+
+```bash
+whisper-smith data/sample.m4a
+```
+
+### 2) Save transcript to a file
+
+```bash
+whisper-smith data/sample.m4a --output data/sample.txt
+```
+
+### 3) Choose output format explicitly
+
+```bash
+whisper-smith data/sample.m4a --format json --output data/sample.json
+```
+
+Supported CLI formats: `txt`, `json`, `srt`, `vtt`
+
+### 4) Let format be inferred from output extension
+
+```bash
+whisper-smith data/sample.m4a --output data/sample.srt
+```
+
+### 5) Overwrite existing file
+
+```bash
+whisper-smith data/sample.m4a --output data/sample.txt --overwrite
+```
+
+### 6) Run speaker diarization
+
+```bash
+whisper-smith data/sample.m4a --diarize --output data/sample.diarization.json
+```
+
+Diarization currently supports JSON output only. Optional speaker hints:
+
+```bash
+whisper-smith data/sample.m4a --diarize --format json --num-speakers 2
+```
+
+### 7) Create speaker-aligned transcript JSON
+
+Run the full pipeline from one audio file:
+
+```bash
+whisper-smith data/sample.m4a --align --output data/sample.aligned.json
+```
+
+This writes the main aligned transcript JSON to `data/sample.aligned.json` and
+also writes intermediate artifacts beside it:
+
+```text
+data/sample.transcript.json
+data/sample.diarization.json
+```
+
+To put the intermediate artifacts in a separate directory:
+
+```bash
+whisper-smith data/sample.m4a --align --output data/sample.aligned.json --artifacts-dir data/artifacts
+```
+
+## Python Usage
+
+```python
+from pathlib import Path
+from whisper_smith.transcribe import transcribe_audio
+from whisper_smith.exporters import export_transcript
+
+result = transcribe_audio(Path("data/sample.m4a"))
+print(result.text)
+
+srt = export_transcript(result, "srt")
+Path("data/sample.srt").write_text(srt, encoding="utf-8")
+```
+
+### Speaker diarization
+
+```python
+from pathlib import Path
+from whisper_smith.diarize import diarize_audio
+
+result = diarize_audio(Path("data/sample.m4a"))
+
+for segment in result.segments:
+    print(segment.start, segment.end, segment.speaker)
+```
+
+`diarize_audio` uses `HUGGINGFACE_TOKEN` from the environment, or accepts
+`hf_token="..."` explicitly.
+
+The default local model is `pyannote/speaker-diarization-3.1`, which is compatible
+with the Intel macOS dependency set. You may pass a different model explicitly
+from Python when running on a newer platform.
+
+## Notes
+
+- If `--output` is omitted, transcript is printed to stdout.
+- If `--format` is omitted, format is inferred from `--output` extension when possible.
+- If an output file already exists, add `--overwrite` to replace it.
+- Transcription uses a timestamp-capable OpenAI model by default so JSON, SRT,
+  and VTT outputs have segment timestamps.
+- For large audio files, `whisper-smith` automatically splits audio into chunks and
+  merges transcript text.
+- If diarization fails with `torchaudio` missing `AudioMetaData`, refresh the
+  optional diarization dependencies with `uv lock --upgrade-package torch
+  --upgrade-package torchaudio` and then `uv sync --extra diarize`.
+
+## Development
+
+Run tests:
+
+```bash
+pytest
+```

whisper_smith-0.1.0/docs/Makefile

@@ -0,0 +1,18 @@
+.PHONY: help clean html
+
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = source
+BUILDDIR = build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+clean:
+	@rm -rf "$(BUILDDIR)"
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+%:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

whisper_smith-0.1.0/docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx>=7.4
+furo>=2024.8.6
+myst-parser>=4.0.0

whisper_smith-0.1.0/docs/source/aligned-json.rst

@@ -0,0 +1,47 @@
+Aligned JSON Workflow
+=====================
+
+The aligned JSON workflow is the main product flow for combining transcription
+and diarization.
+
+Run the pipeline
+----------------
+
+.. code-block:: bash
+
+   whisper-smith data/sample.m4a --align --output data/sample.aligned.json
+
+Outputs:
+
+.. code-block:: text
+
+   data/sample.aligned.json
+   data/sample.transcript.json
+   data/sample.diarization.json
+
+Output shape
+------------
+
+Each aligned transcript segment contains timestamps, text, and the assigned
+speaker label:
+
+.. code-block:: json
+
+   {
+     "segments": [
+       {
+         "start": 0.0,
+         "end": 7.08,
+         "text": "Hello world.",
+         "speaker": "SPEAKER_01"
+       }
+     ],
+     "text": "Hello world."
+   }
+
+How speakers are assigned
+-------------------------
+
+``assign_speakers`` compares each transcript segment with diarization segments
+and chooses the speaker with the largest time overlap. If no diarization segment
+overlaps, the transcript segment keeps its existing speaker value.

whisper_smith-0.1.0/docs/source/api/align.rst

@@ -0,0 +1,6 @@
+Alignment
+=========
+
+.. automodule:: whisper_smith.align
+   :members: assign_speakers
+   :undoc-members:

whisper_smith-0.1.0/docs/source/api/diarize.rst

@@ -0,0 +1,6 @@
+Diarization
+===========
+
+.. automodule:: whisper_smith.diarize
+   :members: diarize_audio, diarize_file, from_pyannote_output
+   :undoc-members:

whisper_smith-0.1.0/docs/source/api/exporters.rst

@@ -0,0 +1,6 @@
+Exporters
+=========
+
+.. automodule:: whisper_smith.exporters
+   :members:
+   :undoc-members:

whisper_smith-0.1.0/docs/source/api/index.rst

@@ -0,0 +1,11 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   models
+   transcribe
+   diarize
+   align
+   exporters

whisper_smith-0.1.0/docs/source/api/models.rst

@@ -0,0 +1,6 @@
+Models
+======
+
+.. automodule:: whisper_smith.models
+   :members:
+   :undoc-members:

whisper_smith-0.1.0/docs/source/api/transcribe.rst

@@ -0,0 +1,6 @@
+Transcription
+=============
+
+.. automodule:: whisper_smith.transcribe
+   :members: transcribe_audio, transcribe_file, from_openai_response
+   :undoc-members: