easyaligner 0.1.0__tar.gz

easyaligner-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: easyaligner
+Version: 0.1.0
+Summary: Forced alignment pipeline designed for efficiency and ease of use.
+Author: Faton Rekathati
+Project-URL: Repository, https://github.com/kb-labb/easyaligner
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: transformers>=4.45.0
+Requires-Dist: torch!=2.9.*,>=2.7.0
+Requires-Dist: torchaudio!=2.9.*,>=2.7.0
+Requires-Dist: tqdm>=4.66.1
+Requires-Dist: soundfile>=0.12.1
+Requires-Dist: nltk>=3.8.2
+Requires-Dist: pyannote-audio>=3.3.1
+Requires-Dist: silero-vad~=6.0
+Requires-Dist: msgspec
+
+# Easier forced alignment with `easyaligner`
+
+`easyaligner` is a fast and memory efficient forced alignment pipeline for aligning speech and text. It is designed with ease of use in mind, supporting alignment both from ground-truth transcripts, as well as from ASR-generated transcripts. `easyaligner` acts as the backend that powers alignment in [`easywhisper`](https://github.com/kb-labb/easywhisper). Some notable features of `easyaligner` include:
+
+* Uses [Pytorch's forced alignment API](https://docs.pytorch.org/audio/main/tutorials/ctc_forced_alignment_api_tutorial.html) with support for efficient GPU accelerated forced alignment. Enables aligning long audio segments fast and memory-efficiently ([Pratap et al., 2024](https://jmlr.org/papers/volume25/23-1318/23-1318.pdf)). 
+* Supports **custom regex-based text normalization** functionality to preprocess transcripts before alignment, in order to improve alignment quality. Maintains a mapping from original to normalized text, meaning the **normalizations and transformations are non-destructive** and reversible after alignment.  
+* Separates VAD, emission extraction (emissions are written to disk), and alignment into modular pipeline stages. Allows users to run everything end-to-end, or to run the separate stages individually (better flexibility for parallelization).
+
+## Installation
+
+### With GPU support (recommended)
+
+```bash
+pip install easyaligner --extra-index-url https://download.pytorch.org/whl/cu128
+```
+
+> [!TIP]  
+> Remove `--extra-index-url` if you want CPU-only installation.
+
+### Using uv
+
+When installing with [uv](https://docs.astral.sh/uv/), it will select the appropriate PyTorch version automatically (CPU for macOS, CUDA for Linux/Windows/ARM):
+
+```bash
+uv pip install easyaligner
+```
+
+### For development
+
+```bash
+git clone https://github.com/kb-labb/easyaligner.git
+cd easyaligner
+
+pip install -e . --extra-index-url https://download.pytorch.org/whl/cu128
+```
+
+## Logging and Error Handling
+
+### Enabling Logging
+
+To see progress and error messages one can add the following logging configuration at the start of a script:
+
+```python
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s | %(name)s | %(levelname)s | %(message)s'
+    # handlers=[
+    #     logging.FileHandler('easyalign.log'), # Log to a file
+    #     logging.StreamHandler()  # Also print to console
+    # ]
+)
+```
+
+### Error Handling
+
+`easyaligner` pipelines use PyTorch DataLoaders for efficient parallel processing and prefetching of data. During processing, the library silently skips files that fail to load (corrupted audio, missing file, etc.). The errors are logged with full traceback, the pipeline however continues processing the remaining files. 
+
+`easyaligner` leaves it up the user to decide how to handle failed files (retry, validate inputs, etc.).
+
+> [!TIP]  
+> Track which files failed after processing completes by comparing output:
+
+```python
+from pathlib import Path
+
+# After pipeline completes, check which files produced output
+output_files = list(Path("output/vad").rglob("*.json"))
+output_stems = {f.stem for f in output_files}
+
+# Find files that failed (no output produced)
+failed = [p for p in audio_paths if Path(p).stem not in output_stems]
+```
+

easyaligner-0.1.0/README.md

@@ -0,0 +1,75 @@
+# Easier forced alignment with `easyaligner`
+
+`easyaligner` is a fast and memory efficient forced alignment pipeline for aligning speech and text. It is designed with ease of use in mind, supporting alignment both from ground-truth transcripts, as well as from ASR-generated transcripts. `easyaligner` acts as the backend that powers alignment in [`easywhisper`](https://github.com/kb-labb/easywhisper). Some notable features of `easyaligner` include:
+
+* Uses [Pytorch's forced alignment API](https://docs.pytorch.org/audio/main/tutorials/ctc_forced_alignment_api_tutorial.html) with support for efficient GPU accelerated forced alignment. Enables aligning long audio segments fast and memory-efficiently ([Pratap et al., 2024](https://jmlr.org/papers/volume25/23-1318/23-1318.pdf)). 
+* Supports **custom regex-based text normalization** functionality to preprocess transcripts before alignment, in order to improve alignment quality. Maintains a mapping from original to normalized text, meaning the **normalizations and transformations are non-destructive** and reversible after alignment.  
+* Separates VAD, emission extraction (emissions are written to disk), and alignment into modular pipeline stages. Allows users to run everything end-to-end, or to run the separate stages individually (better flexibility for parallelization).
+
+## Installation
+
+### With GPU support (recommended)
+
+```bash
+pip install easyaligner --extra-index-url https://download.pytorch.org/whl/cu128
+```
+
+> [!TIP]  
+> Remove `--extra-index-url` if you want CPU-only installation.
+
+### Using uv
+
+When installing with [uv](https://docs.astral.sh/uv/), it will select the appropriate PyTorch version automatically (CPU for macOS, CUDA for Linux/Windows/ARM):
+
+```bash
+uv pip install easyaligner
+```
+
+### For development
+
+```bash
+git clone https://github.com/kb-labb/easyaligner.git
+cd easyaligner
+
+pip install -e . --extra-index-url https://download.pytorch.org/whl/cu128
+```
+
+## Logging and Error Handling
+
+### Enabling Logging
+
+To see progress and error messages one can add the following logging configuration at the start of a script:
+
+```python
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s | %(name)s | %(levelname)s | %(message)s'
+    # handlers=[
+    #     logging.FileHandler('easyalign.log'), # Log to a file
+    #     logging.StreamHandler()  # Also print to console
+    # ]
+)
+```
+
+### Error Handling
+
+`easyaligner` pipelines use PyTorch DataLoaders for efficient parallel processing and prefetching of data. During processing, the library silently skips files that fail to load (corrupted audio, missing file, etc.). The errors are logged with full traceback, the pipeline however continues processing the remaining files. 
+
+`easyaligner` leaves it up the user to decide how to handle failed files (retry, validate inputs, etc.).
+
+> [!TIP]  
+> Track which files failed after processing completes by comparing output:
+
+```python
+from pathlib import Path
+
+# After pipeline completes, check which files produced output
+output_files = list(Path("output/vad").rglob("*.json"))
+output_stems = {f.stem for f in output_files}
+
+# Find files that failed (no output produced)
+failed = [p for p in audio_paths if Path(p).stem not in output_stems]
+```
+

easyaligner-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=67.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+version = "0.1.0"
+name = "easyaligner"
+requires-python = ">= 3.10"
+description = "Forced alignment pipeline designed for efficiency and ease of use."
+readme = "README.md"
+authors = [{ name = "Faton Rekathati" }]
+
+dependencies = [
+  "transformers>=4.45.0",
+  "torch>=2.7.0,!=2.9.*",
+  "torchaudio>=2.7.0,!=2.9.*",
+  "tqdm>=4.66.1",
+  "soundfile>=0.12.1",
+  "nltk>=3.8.2",
+  "pyannote-audio>=3.3.1",
+  "silero-vad~=6.0",
+  "msgspec"
+]
+
+[project.urls]
+Repository = "https://github.com/kb-labb/easyaligner"
+
+[tool.uv.sources]
+torch = [
+  { index = "pytorch-cpu", marker = "sys_platform == 'darwin'" },
+  { index = "pytorch-cuda", marker = "sys_platform != 'darwin'" },
+]
+torchaudio = [
+  { index = "pytorch-cpu", marker = "sys_platform == 'darwin'" },
+  { index = "pytorch-cuda", marker = "sys_platform != 'darwin'" },
+]
+
+[[tool.uv.index]]
+name = "pytorch-cuda"
+url = "https://download.pytorch.org/whl/cu128"
+explicit = true
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+#### Linting ####
+[tool.ruff]
+line-length = 99
+indent-width = 4
+target-version = "py310"
+
+[tool.ruff.lint]
+# Disable fix for unused imports (`F401`).
+unfixable = ["F401"]

easyaligner-0.1.0/setup.cfg

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