speech-mine 0.1.0__tar.gz

speech_mine-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

speech_mine-0.1.0/.gitignore

@@ -0,0 +1,210 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# macOS files
+.DS_Storesite/

speech_mine-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

speech_mine-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: speech-mine
+Version: 0.1.0
+Summary: A powerful tool for extracting and analyzing speech data from audio files with known speaker counts and contents.
+Project-URL: Homepage, https://github.com/your-org/speech-mine
+Project-URL: Repository, https://github.com/your-org/speech-mine
+Project-URL: Issues, https://github.com/your-org/speech-mine/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: faster-whisper>=1.2.0
+Requires-Dist: pandas>=2.3.2
+Requires-Dist: pyannote-audio>=3.3.2
+Requires-Dist: pydub>=0.25.1
+Requires-Dist: pytest>=8.4.2
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rapidfuzz>=3.14.1
+Requires-Dist: tqdm>=4.67.1
+Description-Content-Type: text/markdown
+
+
+# speech-mine
+
+Speech diarization and transcript analysis toolkit. Extract speaker-labeled transcripts from audio, format them into readable scripts, search them with fuzzy matching, and pre-process audio with chunking.
+
+## Modules
+
+| Module | Description | Docs |
+|--------|-------------|------|
+| `extract` | Transcribe audio with speaker diarization | [→](docs/extract.md) |
+| `format` | Format CSV transcripts into readable scripts | [→](docs/format.md) |
+| `chunk` | Split audio into segments via YAML config | [→](docs/chunk.md) |
+| `search` | Fuzzy search transcripts by word or phrase | [→](docs/search.md) |
+
+## Installation
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+git clone <repository-url>
+cd speech-mine
+uv sync
+```
+
+See [docs/installation.md](docs/installation.md) for library dependency setup and HuggingFace token configuration.
+
+## Quick Start
+
+```bash
+# 1. Extract a transcript
+uv run speech-mine extract interview.mp3 output.csv \
+  --hf-token YOUR_TOKEN \
+  --num-speakers 2 \
+  --compute-type float32
+
+# 2. Format into a readable script
+uv run speech-mine format output.csv script.txt
+
+# 3. Search it
+uv run speech-mine search "topic of interest" output.csv --pretty
+```
+
+## Documentation
+
+```bash
+# Serve docs locally
+uv run mkdocs serve
+```
+
+Or browse the `docs/` folder directly.
+
+## License
+
+TBD

speech_mine-0.1.0/README.md

@@ -0,0 +1,53 @@
+
+# speech-mine
+
+Speech diarization and transcript analysis toolkit. Extract speaker-labeled transcripts from audio, format them into readable scripts, search them with fuzzy matching, and pre-process audio with chunking.
+
+## Modules
+
+| Module | Description | Docs |
+|--------|-------------|------|
+| `extract` | Transcribe audio with speaker diarization | [→](docs/extract.md) |
+| `format` | Format CSV transcripts into readable scripts | [→](docs/format.md) |
+| `chunk` | Split audio into segments via YAML config | [→](docs/chunk.md) |
+| `search` | Fuzzy search transcripts by word or phrase | [→](docs/search.md) |
+
+## Installation
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+git clone <repository-url>
+cd speech-mine
+uv sync
+```
+
+See [docs/installation.md](docs/installation.md) for library dependency setup and HuggingFace token configuration.
+
+## Quick Start
+
+```bash
+# 1. Extract a transcript
+uv run speech-mine extract interview.mp3 output.csv \
+  --hf-token YOUR_TOKEN \
+  --num-speakers 2 \
+  --compute-type float32
+
+# 2. Format into a readable script
+uv run speech-mine format output.csv script.txt
+
+# 3. Search it
+uv run speech-mine search "topic of interest" output.csv --pretty
+```
+
+## Documentation
+
+```bash
+# Serve docs locally
+uv run mkdocs serve
+```
+
+Or browse the `docs/` folder directly.
+
+## License
+
+TBD

speech_mine-0.1.0/docs/chunk.md

@@ -0,0 +1,81 @@
+# chunk — Audio Chunking
+
+Splits a `.wav` file into smaller segments based on a YAML configuration defining time boundaries. Useful for pre-processing long recordings before running `extract`.
+
+!!! note
+    Only `.wav` input files are supported. Output chunks are also `.wav`.
+
+## CLI
+
+```bash
+uv run speech-mine chunk <audio.wav> <config.yaml> <output_dir/> [options]
+```
+
+### Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--fade-in MS` | `0` | Fade in duration in milliseconds |
+| `--fade-out MS` | `0` | Fade out duration in milliseconds |
+| `--padding MS` | `0` | Silence padding added to both ends (ms) |
+| `--verbose` | — | Print file sizes for each chunk |
+
+### Examples
+
+```bash
+# Basic chunking
+uv run speech-mine chunk recording.wav config.yaml chunks/
+
+# With fade effects and padding
+uv run speech-mine chunk recording.wav config.yaml chunks/ \
+  --fade-in 500 \
+  --fade-out 500 \
+  --padding 100 \
+  --verbose
+```
+
+## Library
+
+```python
+from speech_mine.pickaxe.chunk import chunk_audio_file, AudioChunker
+
+# Convenience function
+output_files = chunk_audio_file(
+    audio_path="recording.wav",
+    config_path="config.yaml",
+    output_dir="chunks/",
+    fade_in=500,
+    fade_out=500,
+    silence_padding=100,
+)
+
+# Or use the class directly
+chunker = AudioChunker(fade_in_duration=500, fade_out_duration=500, silence_padding=100)
+output_files = chunker.process_audio_file("recording.wav", "config.yaml", "chunks/")
+```
+
+## YAML config format
+
+See [examples/example_chunk_config.yaml](https://github.com/your-org/speech-mine/blob/main/examples/example_chunk_config.yaml) for a full example.
+
+```yaml
+chunks:
+  - start: 0.0
+    end: 30.0
+    name: "intro"        # optional — included in output filename
+  - start: 30.0
+    end: 120.0
+    name: "discussion"
+  - start: 120.0
+    end: 300.0
+    # no name — output will be "2.wav"
+```
+
+Output filenames follow the pattern `{index}.{name}.wav` or `{index}.wav` if no name is set. Chunks are sorted by start time before indexing.
+
+Validation rules:
+
+- `start` and `end` are required for every chunk
+- `end` must be greater than `start`
+- `end` cannot exceed the audio file duration
+- Start times must be unique across chunks

speech_mine-0.1.0/docs/extract.md

@@ -0,0 +1,109 @@
+# extract — Transcription + Speaker Diarization
+
+Transcribes audio and labels each segment with the speaker who said it. Uses [faster-whisper](https://github.com/SYSTRAN/faster-whisper) for transcription and [pyannote](https://github.com/pyannote/pyannote-audio) for speaker diarization.
+
+**Supported audio formats:** `.wav`, `.mp3`, `.ogg`, `.flac`
+
+## CLI
+
+```bash
+uv run speech-mine extract <audio> <output.csv> --hf-token TOKEN [options]
+```
+
+### Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--hf-token TOKEN` | *(required)* | HuggingFace access token |
+| `--model SIZE` | `large-v3` | Whisper model size |
+| `--device` | `auto` | `auto`, `cpu`, or `cuda` |
+| `--compute-type` | `float16` | `float16` (GPU), `float32` (CPU), `int8` |
+| `--num-speakers N` | — | Exact speaker count (best accuracy when known) |
+| `--min-speakers N` | `1` | Minimum expected speakers |
+| `--max-speakers N` | — | Maximum expected speakers |
+| `--verbose` | — | Enable verbose logging |
+
+### Examples
+
+```bash
+# Basic (CPU)
+uv run speech-mine extract interview.mp3 output.csv \
+  --hf-token YOUR_TOKEN \
+  --compute-type float32
+
+# 2-person interview with known speaker count
+uv run speech-mine extract interview.wav output.csv \
+  --hf-token YOUR_TOKEN \
+  --num-speakers 2 \
+  --compute-type float32
+
+# GPU with best accuracy model
+uv run speech-mine extract meeting.wav output.csv \
+  --hf-token YOUR_TOKEN \
+  --model large-v3 \
+  --device cuda \
+  --compute-type float16 \
+  --num-speakers 4
+
+# Speaker range when count is unknown
+uv run speech-mine extract conference.wav output.csv \
+  --hf-token YOUR_TOKEN \
+  --min-speakers 2 \
+  --max-speakers 8 \
+  --compute-type float32
+```
+
+!!! warning
+    Always use `--compute-type float32` when running on CPU. The default (`float16`) requires a GPU and will raise an error on CPU.
+
+## Library
+
+```python
+from speech_mine.diarizer.processor import SpeechDiarizationProcessor
+
+processor = SpeechDiarizationProcessor(
+    hf_token="YOUR_TOKEN",
+    num_speakers=2,
+    whisper_model_size="large-v3",
+)
+
+# Full pipeline in one call
+processor.process_audio_file("interview.mp3", "output.csv")
+```
+
+### Individual pipeline steps
+
+```python
+# Step 1: Transcribe
+segments, info = processor.transcribe_audio("interview.mp3")
+
+# Step 2: Diarize
+diarization = processor.perform_speaker_diarization("interview.mp3")
+
+# Step 3: Align
+aligned = processor.align_transcription_with_speakers(segments, diarization)
+
+# Step 4: Save
+processor.save_to_csv(aligned, "output.csv", info)
+```
+
+## Output
+
+Two files are written:
+
+- `output.csv` — segment and word-level transcript data ([see example](https://github.com/your-org/speech-mine/blob/main/examples/example_extract_output.csv))
+- `output_metadata.json` — language, duration, speaker list, processing info ([see example](https://github.com/your-org/speech-mine/blob/main/examples/example_extract_metadata.json))
+
+See [Output Format](output-format.md) for full column/field reference.
+
+## Speaker Count Tips
+
+Specifying `--num-speakers` when you know the exact count improves diarization accuracy by 15–30%.
+
+| Parameter | When to use |
+|-----------|-------------|
+| `--num-speakers N` | You know exactly how many people speak |
+| `--min-speakers N` | You know there are at least N speakers |
+| `--max-speakers N` | You want to cap false speaker detection |
+
+See [Model Options](models.md) for whisper model and compute type guidance.

speech_mine-0.1.0/docs/format.md

@@ -0,0 +1,100 @@
+# format — Script Formatting
+
+Converts the CSV output from `extract` into a human-readable, movie-style script.
+
+## CLI
+
+```bash
+uv run speech-mine format <input.csv> <output.txt> [options]
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--speakers FILE` | JSON file mapping `SPEAKER_00` → custom name |
+| `--create-template` | Generate a speaker names template JSON from the CSV |
+
+### Examples
+
+```bash
+# Basic formatting
+uv run speech-mine format output.csv script.txt
+
+# Generate a speaker names template
+uv run speech-mine format output.csv script.txt --create-template
+
+# Format with custom speaker names
+uv run speech-mine format output.csv script.txt --speakers output_speaker_names.json
+```
+
+### Custom speaker names workflow
+
+```bash
+# 1. Generate template — creates output_speaker_names.json
+uv run speech-mine format output.csv script.txt --create-template
+
+# 2. Edit the template
+# {"SPEAKER_00": "Alice", "SPEAKER_01": "Bob"}
+
+# 3. Format with names applied
+uv run speech-mine format output.csv final_script.txt --speakers output_speaker_names.json
+```
+
+## Library
+
+```python
+from speech_mine.diarizer.formatter import ScriptFormatter
+
+# Basic formatting
+formatter = ScriptFormatter()
+formatter.format_script("output.csv", "script.txt")
+
+# With custom speaker names
+formatter = ScriptFormatter(custom_speakers={"SPEAKER_00": "Alice", "SPEAKER_01": "Bob"})
+formatter.format_script("output.csv", "script.txt")
+
+# Generate a speaker names template from a CSV
+template_path = ScriptFormatter.create_custom_speakers_template("output.csv")
+
+# Load speaker names from a JSON file
+speakers = ScriptFormatter.load_custom_speakers("names.json")
+formatter = ScriptFormatter(custom_speakers=speakers)
+```
+
+## Output format
+
+See [examples/example_format_output.txt](https://github.com/your-org/speech-mine/blob/main/examples/example_format_output.txt) for a full sample.
+
+```
+================================================================================
+TRANSCRIPT
+================================================================================
+
+RECORDING DETAILS:
+----------------------------------------
+File: interview.mp3
+Duration: 08:47
+Language: EN (confidence: 99.0%)
+Speakers: 2
+Processed: 2026-03-05 22:00:00
+
+CAST:
+----------------------------------------
+SPEAKER A
+SPEAKER B
+
+TRANSCRIPT:
+----------------------------------------
+
+[00:00 - 00:05] SPEAKER A:
+    So tell me about your background.
+
+[00:06 - 00:12] SPEAKER B:
+    Sure, I started out in radio back in the eighties.
+
+    [...5:30 pause...]
+
+[05:42 - 05:50] SPEAKER A:
+    And how did that shape your career?
+```

speech_mine-0.1.0/docs/index.md

@@ -0,0 +1,30 @@
+# speech-mine
+
+Speech diarization and transcript analysis toolkit. Extract speaker-labeled transcripts from audio, format them into readable scripts, search them with fuzzy matching, and pre-process audio with chunking.
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| [`extract`](extract.md) | Transcribe audio with speaker diarization |
+| [`format`](format.md) | Format CSV transcripts into readable scripts |
+| [`chunk`](chunk.md) | Split audio into segments via YAML config |
+| [`search`](search.md) | Fuzzy search transcripts by word or phrase |
+
+## Quick Start
+
+```bash
+# 1. Extract a transcript
+uv run speech-mine extract interview.mp3 output.csv \
+  --hf-token YOUR_TOKEN \
+  --num-speakers 2 \
+  --compute-type float32
+
+# 2. Format it into a readable script
+uv run speech-mine format output.csv script.txt
+
+# 3. Search it
+uv run speech-mine search "topic of interest" output.csv --pretty
+```
+
+See [Installation](installation.md) to get started.