speech-detect 0.1.0__tar.gz

speech_detect-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 [Speech2SRT Team](https://github.com/speech2srt)
+
+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.

speech_detect-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include requirements.txt
+recursive-include src *.py
+

speech_detect-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: speech-detect
+Version: 0.1.0
+Summary: A Python library for detecting speech segments and non-speech gaps in audio/video files using FSMN-VAD-ONNX with streaming processing
+License: MIT
+Project-URL: Homepage, https://github.com/speech2srt/speech-detect
+Project-URL: Repository, https://github.com/speech2srt/speech-detect
+Project-URL: Issues, https://github.com/speech2srt/speech-detect/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: funasr-onnx>=0.4.1
+Requires-Dist: ffmpeg-audio>=0.1.3
+Dynamic: license-file
+
+# speech-detect
+
+A Python library for detecting speech segments and non-speech gaps in audio/video files using FSMN-VAD-ONNX with streaming processing.
+
+## Features
+
+- **Streaming VAD detection**: Process large audio/video files in chunks without loading everything into memory
+- **Speech segment detection**: Detect all speech segments in audio/video files
+- **Non-speech gap derivation**: Compute non-speech gaps from speech segments
+- **Format support**: Supports all audio/video formats that FFmpeg supports (MP3, WAV, FLAC, Opus, MP4, etc.)
+- **Time range support**: Support start time and duration parameters for partial processing
+- **Memory efficient**: Constant memory usage regardless of audio file duration
+
+## Installation
+
+```bash
+pip install speech-detect
+```
+
+**Note**: This package requires:
+
+- FFmpeg to be installed on your system and available in PATH
+- FSMN-VAD-ONNX model files (see Model Setup below)
+
+## Model Setup
+
+This package requires FSMN-VAD-ONNX model files. The model is available on Hugging Face:
+
+**Model Repository**: [funasr/fsmn-vad-onnx](https://huggingface.co/funasr/fsmn-vad-onnx)
+
+### Download the Model
+
+1. Install Git LFS (required for downloading large model files):
+
+   ```bash
+   git lfs install
+   ```
+
+2. Clone the model repository:
+
+   ```bash
+   git clone https://huggingface.co/funasr/fsmn-vad-onnx
+   ```
+
+   This will download the model files including `model_quant.onnx`, `config.yaml`, `am.mvn`, etc.
+
+3. Set the `MODEL_FSMN_VAD_DIR` environment variable to point to the model directory:
+   ```bash
+   export MODEL_FSMN_VAD_DIR=/path/to/fsmn-vad-onnx
+   ```
+
+Alternatively, you can specify the model directory when initializing `SpeechDetector`:
+
+```python
+from speech_detect import SpeechDetector
+
+detector = SpeechDetector(model_dir="/path/to/fsmn-vad-onnx")
+```
+
+## Quick Start
+
+### Detect Speech Segments and Gaps
+
+```python
+from speech_detect import SpeechDetector
+
+# Initialize detector (reads MODEL_FSMN_VAD_DIR from environment)
+detector = SpeechDetector()
+
+# Detect speech segments and non-speech gaps in an audio file
+speech_segments, gaps = detector.detect("audio.mp3")
+
+# speech_segments is a list of dictionaries: [{"start": 0, "end": 500}, ...]
+for segment in speech_segments:
+    start_ms = segment["start"]
+    end_ms = segment["end"]
+    duration = end_ms - start_ms
+    print(f"Speech segment: {start_ms}ms - {end_ms}ms (duration: {duration}ms)")
+
+# gaps is a list of dictionaries: [{"start": 0, "end": 500}, ...]
+for gap in gaps:
+    start_ms = gap["start"]
+    end_ms = gap["end"]
+    duration = end_ms - start_ms
+    print(f"Non-speech gap: {start_ms}ms - {end_ms}ms (duration: {duration}ms)")
+```
+
+### Processing Specific Time Range
+
+```python
+# Process only the first 30 seconds
+speech_segments, gaps = detector.detect(
+    file_path="audio.mp3",
+    start_ms=0,
+    duration_ms=30000,
+)
+
+# Process from 10 seconds, duration 5 seconds
+speech_segments, gaps = detector.detect(
+    file_path="audio.mp3",
+    start_ms=10000,
+    duration_ms=5000,
+)
+```
+
+### Custom Chunk Size
+
+```python
+# Use 1-minute chunks instead of default 20-minute chunks
+speech_segments, gaps = detector.detect(
+    file_path="audio.mp3",
+    chunk_duration_sec=60,
+)
+```
+
+## API Reference
+
+### SpeechDetector
+
+Main class for speech detection. All methods are instance methods.
+
+#### `SpeechDetector.__init__(model_dir=None)`
+
+Initialize speech detector.
+
+**Parameters:**
+
+- `model_dir` (str, optional): Path to the FSMN-VAD model directory. If None, reads from `MODEL_FSMN_VAD_DIR` environment variable.
+
+**Note:** The FSMN-VAD model only has a quantized version, so `quantize=True` is always used internally.
+
+**Raises:**
+
+- `VadModelNotFoundError`: If model directory is not found or not set
+- `VadModelInitializationError`: If model initialization fails
+
+#### `SpeechDetector.detect(file_path, chunk_duration_sec=None, start_ms=None, duration_ms=None)`
+
+Detect speech segments in audio/video file using streaming processing.
+
+**Parameters:**
+
+- `file_path` (str): Path to the audio/video file (supports all FFmpeg formats)
+- `chunk_duration_sec` (int, optional): Duration of each chunk in seconds. Defaults to 1200 (20 minutes). Must be > 0 if provided.
+- `start_ms` (int, optional): Start position in milliseconds. None means from file beginning. If None but `duration_ms` is provided, defaults to 0.
+- `duration_ms` (int, optional): Total duration to process in milliseconds. None means process until end. If specified, processing stops when this duration is reached.
+
+**Returns:**
+
+- `tuple[list[VadSegment], list[VadSegment]]`: Tuple of (speech_segments, gaps)
+  - `speech_segments`: List of speech segments, format: `[{"start": ms, "end": ms}, ...]`
+    - Timestamps are relative to audio start (from 0)
+    - Unit: milliseconds
+  - `gaps`: List of non-speech gaps, format: `[{"start": ms, "end": ms}, ...]`
+    - Timestamps are relative to audio start (from 0)
+    - Unit: milliseconds
+
+**Raises:**
+
+- `VadProcessingError`: If processing fails
+
+## Data Types
+
+### VadSegment
+
+A TypedDict representing a time segment (can be a speech segment or a non-speech gap).
+
+**Fields:**
+
+- `start` (int): Segment start time in milliseconds
+- `end` (int): Segment end time in milliseconds
+
+**Example:**
+
+```python
+segment: VadSegment = {"start": 100, "end": 500}
+```
+
+## Exceptions
+
+### `VadModelNotFoundError`
+
+Raised when VAD model directory is not found or not set.
+
+**Attributes:**
+
+- `message`: Human-readable error message
+
+### `VadModelInitializationError`
+
+Raised when VAD model initialization fails.
+
+**Attributes:**
+
+- `message`: Primary error message
+- `model_dir`: Path to the model directory that caused the error
+
+### `VadProcessingError`
+
+Raised when VAD processing fails.
+
+**Attributes:**
+
+- `message`: Primary error message
+- `file_path`: Path to the file being processed
+- `details`: Additional error details dictionary
+
+## Requirements
+
+- Python >= 3.10
+- FFmpeg (must be installed separately)
+- numpy >= 1.26.4
+- funasr-onnx >= 0.4.1
+- ffmpeg-audio >= 0.1.3
+
+## License
+
+MIT License

speech_detect-0.1.0/README.md

@@ -0,0 +1,218 @@
+# speech-detect
+
+A Python library for detecting speech segments and non-speech gaps in audio/video files using FSMN-VAD-ONNX with streaming processing.
+
+## Features
+
+- **Streaming VAD detection**: Process large audio/video files in chunks without loading everything into memory
+- **Speech segment detection**: Detect all speech segments in audio/video files
+- **Non-speech gap derivation**: Compute non-speech gaps from speech segments
+- **Format support**: Supports all audio/video formats that FFmpeg supports (MP3, WAV, FLAC, Opus, MP4, etc.)
+- **Time range support**: Support start time and duration parameters for partial processing
+- **Memory efficient**: Constant memory usage regardless of audio file duration
+
+## Installation
+
+```bash
+pip install speech-detect
+```
+
+**Note**: This package requires:
+
+- FFmpeg to be installed on your system and available in PATH
+- FSMN-VAD-ONNX model files (see Model Setup below)
+
+## Model Setup
+
+This package requires FSMN-VAD-ONNX model files. The model is available on Hugging Face:
+
+**Model Repository**: [funasr/fsmn-vad-onnx](https://huggingface.co/funasr/fsmn-vad-onnx)
+
+### Download the Model
+
+1. Install Git LFS (required for downloading large model files):
+
+   ```bash
+   git lfs install
+   ```
+
+2. Clone the model repository:
+
+   ```bash
+   git clone https://huggingface.co/funasr/fsmn-vad-onnx
+   ```
+
+   This will download the model files including `model_quant.onnx`, `config.yaml`, `am.mvn`, etc.
+
+3. Set the `MODEL_FSMN_VAD_DIR` environment variable to point to the model directory:
+   ```bash
+   export MODEL_FSMN_VAD_DIR=/path/to/fsmn-vad-onnx
+   ```
+
+Alternatively, you can specify the model directory when initializing `SpeechDetector`:
+
+```python
+from speech_detect import SpeechDetector
+
+detector = SpeechDetector(model_dir="/path/to/fsmn-vad-onnx")
+```
+
+## Quick Start
+
+### Detect Speech Segments and Gaps
+
+```python
+from speech_detect import SpeechDetector
+
+# Initialize detector (reads MODEL_FSMN_VAD_DIR from environment)
+detector = SpeechDetector()
+
+# Detect speech segments and non-speech gaps in an audio file
+speech_segments, gaps = detector.detect("audio.mp3")
+
+# speech_segments is a list of dictionaries: [{"start": 0, "end": 500}, ...]
+for segment in speech_segments:
+    start_ms = segment["start"]
+    end_ms = segment["end"]
+    duration = end_ms - start_ms
+    print(f"Speech segment: {start_ms}ms - {end_ms}ms (duration: {duration}ms)")
+
+# gaps is a list of dictionaries: [{"start": 0, "end": 500}, ...]
+for gap in gaps:
+    start_ms = gap["start"]
+    end_ms = gap["end"]
+    duration = end_ms - start_ms
+    print(f"Non-speech gap: {start_ms}ms - {end_ms}ms (duration: {duration}ms)")
+```
+
+### Processing Specific Time Range
+
+```python
+# Process only the first 30 seconds
+speech_segments, gaps = detector.detect(
+    file_path="audio.mp3",
+    start_ms=0,
+    duration_ms=30000,
+)
+
+# Process from 10 seconds, duration 5 seconds
+speech_segments, gaps = detector.detect(
+    file_path="audio.mp3",
+    start_ms=10000,
+    duration_ms=5000,
+)
+```
+
+### Custom Chunk Size
+
+```python
+# Use 1-minute chunks instead of default 20-minute chunks
+speech_segments, gaps = detector.detect(
+    file_path="audio.mp3",
+    chunk_duration_sec=60,
+)
+```
+
+## API Reference
+
+### SpeechDetector
+
+Main class for speech detection. All methods are instance methods.
+
+#### `SpeechDetector.__init__(model_dir=None)`
+
+Initialize speech detector.
+
+**Parameters:**
+
+- `model_dir` (str, optional): Path to the FSMN-VAD model directory. If None, reads from `MODEL_FSMN_VAD_DIR` environment variable.
+
+**Note:** The FSMN-VAD model only has a quantized version, so `quantize=True` is always used internally.
+
+**Raises:**
+
+- `VadModelNotFoundError`: If model directory is not found or not set
+- `VadModelInitializationError`: If model initialization fails
+
+#### `SpeechDetector.detect(file_path, chunk_duration_sec=None, start_ms=None, duration_ms=None)`
+
+Detect speech segments in audio/video file using streaming processing.
+
+**Parameters:**
+
+- `file_path` (str): Path to the audio/video file (supports all FFmpeg formats)
+- `chunk_duration_sec` (int, optional): Duration of each chunk in seconds. Defaults to 1200 (20 minutes). Must be > 0 if provided.
+- `start_ms` (int, optional): Start position in milliseconds. None means from file beginning. If None but `duration_ms` is provided, defaults to 0.
+- `duration_ms` (int, optional): Total duration to process in milliseconds. None means process until end. If specified, processing stops when this duration is reached.
+
+**Returns:**
+
+- `tuple[list[VadSegment], list[VadSegment]]`: Tuple of (speech_segments, gaps)
+  - `speech_segments`: List of speech segments, format: `[{"start": ms, "end": ms}, ...]`
+    - Timestamps are relative to audio start (from 0)
+    - Unit: milliseconds
+  - `gaps`: List of non-speech gaps, format: `[{"start": ms, "end": ms}, ...]`
+    - Timestamps are relative to audio start (from 0)
+    - Unit: milliseconds
+
+**Raises:**
+
+- `VadProcessingError`: If processing fails
+
+## Data Types
+
+### VadSegment
+
+A TypedDict representing a time segment (can be a speech segment or a non-speech gap).
+
+**Fields:**
+
+- `start` (int): Segment start time in milliseconds
+- `end` (int): Segment end time in milliseconds
+
+**Example:**
+
+```python
+segment: VadSegment = {"start": 100, "end": 500}
+```
+
+## Exceptions
+
+### `VadModelNotFoundError`
+
+Raised when VAD model directory is not found or not set.
+
+**Attributes:**
+
+- `message`: Human-readable error message
+
+### `VadModelInitializationError`
+
+Raised when VAD model initialization fails.
+
+**Attributes:**
+
+- `message`: Primary error message
+- `model_dir`: Path to the model directory that caused the error
+
+### `VadProcessingError`
+
+Raised when VAD processing fails.
+
+**Attributes:**
+
+- `message`: Primary error message
+- `file_path`: Path to the file being processed
+- `details`: Additional error details dictionary
+
+## Requirements
+
+- Python >= 3.10
+- FFmpeg (must be installed separately)
+- numpy >= 1.26.4
+- funasr-onnx >= 0.4.1
+- ffmpeg-audio >= 0.1.3
+
+## License
+
+MIT License

speech_detect-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=80.8.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "speech-detect"
+version = "0.1.0"
+description = "A Python library for detecting speech segments and non-speech gaps in audio/video files using FSMN-VAD-ONNX with streaming processing"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+dependencies = [
+    "numpy>=1.26.4",
+    "funasr-onnx>=0.4.1",
+    "ffmpeg-audio>=0.1.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/speech2srt/speech-detect"
+Repository = "https://github.com/speech2srt/speech-detect"
+Issues = "https://github.com/speech2srt/speech-detect/issues"
+
+[tool.setuptools]
+package-dir = {"speech_detect" = "src"}
+packages = ["speech_detect"]

speech_detect-0.1.0/requirements.txt

@@ -0,0 +1,3 @@
+numpy>=1.26.4
+funasr-onnx>=0.4.1
+ffmpeg-audio>=0.1.2

speech_detect-0.1.0/setup.cfg

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

speech_detect-0.1.0/speech_detect.egg-info/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: speech-detect
+Version: 0.1.0
+Summary: A Python library for detecting speech segments and non-speech gaps in audio/video files using FSMN-VAD-ONNX with streaming processing
+License: MIT
+Project-URL: Homepage, https://github.com/speech2srt/speech-detect
+Project-URL: Repository, https://github.com/speech2srt/speech-detect
+Project-URL: Issues, https://github.com/speech2srt/speech-detect/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: funasr-onnx>=0.4.1
+Requires-Dist: ffmpeg-audio>=0.1.3
+Dynamic: license-file
+
+# speech-detect
+
+A Python library for detecting speech segments and non-speech gaps in audio/video files using FSMN-VAD-ONNX with streaming processing.
+
+## Features
+
+- **Streaming VAD detection**: Process large audio/video files in chunks without loading everything into memory
+- **Speech segment detection**: Detect all speech segments in audio/video files
+- **Non-speech gap derivation**: Compute non-speech gaps from speech segments
+- **Format support**: Supports all audio/video formats that FFmpeg supports (MP3, WAV, FLAC, Opus, MP4, etc.)
+- **Time range support**: Support start time and duration parameters for partial processing
+- **Memory efficient**: Constant memory usage regardless of audio file duration
+
+## Installation
+
+```bash
+pip install speech-detect
+```
+
+**Note**: This package requires:
+
+- FFmpeg to be installed on your system and available in PATH
+- FSMN-VAD-ONNX model files (see Model Setup below)
+
+## Model Setup
+
+This package requires FSMN-VAD-ONNX model files. The model is available on Hugging Face:
+
+**Model Repository**: [funasr/fsmn-vad-onnx](https://huggingface.co/funasr/fsmn-vad-onnx)
+
+### Download the Model
+
+1. Install Git LFS (required for downloading large model files):
+
+   ```bash
+   git lfs install
+   ```
+
+2. Clone the model repository:
+
+   ```bash
+   git clone https://huggingface.co/funasr/fsmn-vad-onnx
+   ```
+
+   This will download the model files including `model_quant.onnx`, `config.yaml`, `am.mvn`, etc.
+
+3. Set the `MODEL_FSMN_VAD_DIR` environment variable to point to the model directory:
+   ```bash
+   export MODEL_FSMN_VAD_DIR=/path/to/fsmn-vad-onnx
+   ```
+
+Alternatively, you can specify the model directory when initializing `SpeechDetector`:
+
+```python
+from speech_detect import SpeechDetector
+
+detector = SpeechDetector(model_dir="/path/to/fsmn-vad-onnx")
+```
+
+## Quick Start
+
+### Detect Speech Segments and Gaps
+
+```python
+from speech_detect import SpeechDetector
+
+# Initialize detector (reads MODEL_FSMN_VAD_DIR from environment)
+detector = SpeechDetector()
+
+# Detect speech segments and non-speech gaps in an audio file
+speech_segments, gaps = detector.detect("audio.mp3")
+
+# speech_segments is a list of dictionaries: [{"start": 0, "end": 500}, ...]
+for segment in speech_segments:
+    start_ms = segment["start"]
+    end_ms = segment["end"]
+    duration = end_ms - start_ms
+    print(f"Speech segment: {start_ms}ms - {end_ms}ms (duration: {duration}ms)")
+
+# gaps is a list of dictionaries: [{"start": 0, "end": 500}, ...]
+for gap in gaps:
+    start_ms = gap["start"]
+    end_ms = gap["end"]
+    duration = end_ms - start_ms
+    print(f"Non-speech gap: {start_ms}ms - {end_ms}ms (duration: {duration}ms)")
+```
+
+### Processing Specific Time Range
+
+```python
+# Process only the first 30 seconds
+speech_segments, gaps = detector.detect(
+    file_path="audio.mp3",
+    start_ms=0,
+    duration_ms=30000,
+)
+
+# Process from 10 seconds, duration 5 seconds
+speech_segments, gaps = detector.detect(
+    file_path="audio.mp3",
+    start_ms=10000,
+    duration_ms=5000,
+)
+```
+
+### Custom Chunk Size
+
+```python
+# Use 1-minute chunks instead of default 20-minute chunks
+speech_segments, gaps = detector.detect(
+    file_path="audio.mp3",
+    chunk_duration_sec=60,
+)
+```
+
+## API Reference
+
+### SpeechDetector
+
+Main class for speech detection. All methods are instance methods.
+
+#### `SpeechDetector.__init__(model_dir=None)`
+
+Initialize speech detector.
+
+**Parameters:**
+
+- `model_dir` (str, optional): Path to the FSMN-VAD model directory. If None, reads from `MODEL_FSMN_VAD_DIR` environment variable.
+
+**Note:** The FSMN-VAD model only has a quantized version, so `quantize=True` is always used internally.
+
+**Raises:**
+
+- `VadModelNotFoundError`: If model directory is not found or not set
+- `VadModelInitializationError`: If model initialization fails
+
+#### `SpeechDetector.detect(file_path, chunk_duration_sec=None, start_ms=None, duration_ms=None)`
+
+Detect speech segments in audio/video file using streaming processing.
+
+**Parameters:**
+
+- `file_path` (str): Path to the audio/video file (supports all FFmpeg formats)
+- `chunk_duration_sec` (int, optional): Duration of each chunk in seconds. Defaults to 1200 (20 minutes). Must be > 0 if provided.
+- `start_ms` (int, optional): Start position in milliseconds. None means from file beginning. If None but `duration_ms` is provided, defaults to 0.
+- `duration_ms` (int, optional): Total duration to process in milliseconds. None means process until end. If specified, processing stops when this duration is reached.
+
+**Returns:**
+
+- `tuple[list[VadSegment], list[VadSegment]]`: Tuple of (speech_segments, gaps)
+  - `speech_segments`: List of speech segments, format: `[{"start": ms, "end": ms}, ...]`
+    - Timestamps are relative to audio start (from 0)
+    - Unit: milliseconds
+  - `gaps`: List of non-speech gaps, format: `[{"start": ms, "end": ms}, ...]`
+    - Timestamps are relative to audio start (from 0)
+    - Unit: milliseconds
+
+**Raises:**
+
+- `VadProcessingError`: If processing fails
+
+## Data Types
+
+### VadSegment
+
+A TypedDict representing a time segment (can be a speech segment or a non-speech gap).
+
+**Fields:**
+
+- `start` (int): Segment start time in milliseconds
+- `end` (int): Segment end time in milliseconds
+
+**Example:**
+
+```python
+segment: VadSegment = {"start": 100, "end": 500}
+```
+
+## Exceptions
+
+### `VadModelNotFoundError`
+
+Raised when VAD model directory is not found or not set.
+
+**Attributes:**
+
+- `message`: Human-readable error message
+
+### `VadModelInitializationError`
+
+Raised when VAD model initialization fails.
+
+**Attributes:**
+
+- `message`: Primary error message
+- `model_dir`: Path to the model directory that caused the error
+
+### `VadProcessingError`
+
+Raised when VAD processing fails.
+
+**Attributes:**
+
+- `message`: Primary error message
+- `file_path`: Path to the file being processed
+- `details`: Additional error details dictionary
+
+## Requirements
+
+- Python >= 3.10
+- FFmpeg (must be installed separately)
+- numpy >= 1.26.4
+- funasr-onnx >= 0.4.1
+- ffmpeg-audio >= 0.1.3
+
+## License
+
+MIT License

speech_detect-0.1.0/speech_detect.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+requirements.txt
+speech_detect.egg-info/PKG-INFO
+speech_detect.egg-info/SOURCES.txt
+speech_detect.egg-info/dependency_links.txt
+speech_detect.egg-info/requires.txt
+speech_detect.egg-info/top_level.txt
+src/__init__.py
+src/exceptions.py
+src/speech_detect.py
+src/vad_parser.py
+src/vad_types.py

speech_detect-0.1.0/speech_detect.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

speech_detect-0.1.0/speech_detect.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy>=1.26.4
+funasr-onnx>=0.4.1
+ffmpeg-audio>=0.1.3

speech_detect-0.1.0/speech_detect.egg-info/top_level.txt

@@ -0,0 +1 @@
+speech_detect

speech_detect-0.1.0/src/__init__.py

@@ -0,0 +1,31 @@
+"""
+Speech Detect - A Python library for detecting speech segments and non-speech gaps in audio/video files.
+
+This package provides utilities for:
+- Streaming VAD detection using FSMN-VAD-ONNX model
+- Speech segment detection
+- Non-speech gap detection
+- Support for all FFmpeg-supported audio/video formats
+"""
+
+import logging
+
+from .exceptions import VadModelInitializationError, VadModelNotFoundError, VadProcessingError
+from .speech_detect import SpeechDetector
+from .vad_types import VadSegment
+
+__version__ = "0.1.0"
+
+# Configure library root logger
+# Use NullHandler to ensure library remains silent when user hasn't configured logging
+# If user configures logging (e.g., logging.basicConfig()), logs will bubble up to root logger for processing
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+__all__ = [
+    "SpeechDetector",
+    "VadSegment",
+    "VadModelNotFoundError",
+    "VadModelInitializationError",
+    "VadProcessingError",
+]

speech_detect-0.1.0/src/exceptions.py

@@ -0,0 +1,69 @@
+"""
+Exception classes for VAD detection errors.
+
+Provides a hierarchy of exceptions for different error conditions,
+enabling precise error handling and debugging.
+"""
+
+
+class VadModelNotFoundError(Exception):
+    """
+    Raised when VAD model directory is not found or not set.
+
+    This exception indicates that the model directory path is either not provided,
+    not set in environment variable MODEL_FSMN_VAD_DIR, or the directory does not exist.
+    """
+
+    def __init__(self, message: str):
+        """
+        Initialize exception.
+
+        Args:
+            message: Human-readable error message describing the issue.
+        """
+        super().__init__(message)
+        self.message = message
+
+
+class VadModelInitializationError(Exception):
+    """
+    Raised when VAD model initialization fails.
+
+    This exception indicates that the Fsmn_vad_online model failed to initialize
+    from the provided model directory, possibly due to missing files or corrupted model.
+    """
+
+    def __init__(self, message: str, model_dir: str = None):
+        """
+        Initialize exception.
+
+        Args:
+            message: Primary error message (required).
+            model_dir: Path to the model directory that caused the error (optional).
+        """
+        super().__init__(message)
+        self.message = message
+        self.model_dir = model_dir
+
+
+class VadProcessingError(Exception):
+    """
+    Raised when VAD processing fails.
+
+    This exception indicates that an error occurred during the VAD detection process,
+    such as audio format issues, streaming errors, or model inference failures.
+    """
+
+    def __init__(self, message: str, file_path: str = None, details: dict = None):
+        """
+        Initialize exception.
+
+        Args:
+            message: Primary error message (required).
+            file_path: Path to the file being processed (optional).
+            details: Additional error details dictionary (optional).
+        """
+        super().__init__(message)
+        self.message = message
+        self.file_path = file_path
+        self.details = details or {}

speech_detect-0.1.0/src/speech_detect.py

@@ -0,0 +1,200 @@
+"""
+Speech Detector
+
+Detects speech segments and non-speech gaps in audio/video files using Fsmn_vad_online model with streaming processing.
+Supports all FFmpeg-compatible formats and processes large files efficiently with constant memory usage.
+"""
+
+import logging
+import os
+
+import numpy as np
+from ffmpeg_audio import FFmpegAudio
+from funasr_onnx import Fsmn_vad_online
+
+from .exceptions import VadModelInitializationError, VadModelNotFoundError, VadProcessingError
+from .vad_parser import VadParser
+from .vad_types import VadSegment
+
+logger = logging.getLogger(__name__)
+
+
+class SpeechDetector:
+    """
+    Speech Detector (streaming only)
+
+    Performs speech activity detection on streaming audio data using FSMN-VAD-ONNX model
+    and derives speech segments and non-speech gaps. Designed for processing large audio/video files
+    with constant memory footprint regardless of file duration.
+    """
+
+    SAMPLE_RATE = 16000  # Fixed sample rate constant (Hz)
+
+    def __init__(self, model_dir: str = None):
+        """
+        Initialize speech detector.
+
+        Args:
+            model_dir: Path to the model directory. If None, reads from MODEL_FSMN_VAD_DIR
+                      environment variable.
+
+        Raises:
+            VadModelNotFoundError: Model directory path is not set or does not exist.
+            VadModelInitializationError: Model initialization failed.
+        """
+        # Determine model directory path
+        if model_dir is None:
+            model_dir = os.getenv("MODEL_FSMN_VAD_DIR")
+            if not model_dir:
+                raise VadModelNotFoundError("MODEL_FSMN_VAD_DIR environment variable not set. " "Please set it to the path of the FSMN-VAD model directory.")
+
+        # Validate directory exists
+        if not os.path.exists(model_dir):
+            raise VadModelNotFoundError(f"Model directory not found: {model_dir}")
+
+        # Initialize model (FSMN VAD model only has quantized version, always use quantize=True)
+        try:
+            self.model = Fsmn_vad_online(model_dir, quantize=True)
+            self.model_dir = model_dir
+        except Exception as e:
+            raise VadModelInitializationError(
+                f"Failed to initialize VAD model from {model_dir}: {str(e)}",
+                model_dir=model_dir,
+            ) from e
+
+    def detect(
+        self,
+        file_path: str,
+        chunk_duration_sec: int = None,
+        start_ms: int = None,
+        duration_ms: int = None,
+    ) -> tuple["list[VadSegment]", "list[VadSegment]"]:
+        """
+        Detect speech segments and non-speech gaps in audio/video file using streaming processing.
+
+        Processes audio file in chunks using ffmpeg-audio package's stream method,
+        suitable for large files. Memory usage is constant and independent of total audio duration.
+
+        Args:
+            file_path: Path to audio/video file (supports all FFmpeg-compatible formats).
+            chunk_duration_sec: Chunk duration in seconds. None uses default (20 minutes).
+            start_ms: Start position in milliseconds. None starts from beginning of file.
+            duration_ms: Total duration to process in milliseconds. None processes to end of file.
+
+        Returns:
+            tuple[list[VadSegment], list[VadSegment]]: Tuple of (speech_segments, gaps).
+                                                     - speech_segments: List of speech segments, format: [{"start": ms, "end": ms}, ...]
+                                                     - gaps: List of non-speech gaps, format: [{"start": ms, "end": ms}, ...]
+                                                     Timestamps are relative to audio start (0-based), in milliseconds.
+
+        Raises:
+            VadProcessingError: Error occurred during processing.
+        """
+        parser = VadParser()
+        param_dict = {"in_cache": []}
+        speech_segments = []
+        total_samples = 0
+
+        # Process each chunk in streaming fashion
+        chunk_count = 0
+        try:
+            for chunk in FFmpegAudio.stream(
+                file_path,
+                chunk_duration_sec=chunk_duration_sec,
+                start_ms=start_ms,
+                duration_ms=duration_ms,
+            ):
+                chunk_count += 1
+                chunk_samples = len(chunk)
+
+                # Validate chunk format
+                if chunk.dtype != np.float32:
+                    raise VadProcessingError(
+                        f"Chunk dtype must be float32, got {chunk.dtype}",
+                        file_path=file_path,
+                        details={"chunk_index": chunk_count, "dtype": str(chunk.dtype)},
+                    )
+
+                # Accumulate total sample count
+                total_samples += chunk_samples
+
+                # param_dict state is automatically maintained across chunks
+                result = self.model(audio_in=chunk, param_dict=param_dict)
+
+                # Parse model output
+                segments = parser.parse(result)
+                speech_segments.extend(segments)
+
+        except VadProcessingError:
+            # Re-raise VadProcessingError
+            raise
+        except Exception as e:
+            raise VadProcessingError(
+                f"Stream processing failed: {str(e)}",
+                file_path=file_path,
+                details={"chunk_index": chunk_count, "exception_type": type(e).__name__},
+            ) from e
+
+        # Final flush to ensure all data is processed
+        try:
+            param_dict["is_final"] = True
+            final_result = self.model(audio_in=[], param_dict=param_dict)
+            final_segments = parser.parse(final_result)
+            speech_segments.extend(final_segments)
+
+            # Handle any unclosed segments
+            parser.flush()
+        except Exception as e:
+            raise VadProcessingError(
+                f"Final flush failed: {str(e)}",
+                file_path=file_path,
+                details={"exception_type": type(e).__name__},
+            ) from e
+
+        # Derive non-speech gaps from speech segments
+        gaps = self._derive_non_speech_gaps(speech_segments, total_samples)
+
+        return speech_segments, gaps
+
+    @staticmethod
+    def _derive_non_speech_gaps(speech_segments: "list[VadSegment]", audio_length_samples: int) -> "list[VadSegment]":
+        """
+        Derive non-speech gaps from speech segments.
+
+        Computes gaps between speech segments and at the beginning/end of audio.
+        Gaps represent periods of silence or non-speech audio.
+
+        Args:
+            speech_segments: List of speech segments, format: [{"start": ms, "end": ms}, ...]
+            audio_length_samples: Total number of audio samples.
+
+        Returns:
+            list[VadSegment]: List of non-speech gaps, format: [{"start": ms, "end": ms}, ...]
+        """
+        # Calculate total audio duration in milliseconds
+        duration_ms = int(audio_length_samples / SpeechDetector.SAMPLE_RATE * 1000)
+
+        # If no speech segments, entire audio is non-speech
+        if not speech_segments:
+            return [{"start": 0, "end": duration_ms}]
+
+        gaps = []
+
+        # Check for gap at the beginning (before first speech segment)
+        first_speech = speech_segments[0]
+        if first_speech["start"] > 0:
+            gaps.append({"start": 0, "end": first_speech["start"]})
+
+        # Check for gaps between speech segments
+        for i in range(len(speech_segments) - 1):
+            prev_end = speech_segments[i]["end"]
+            next_start = speech_segments[i + 1]["start"]
+            if next_start > prev_end:
+                gaps.append({"start": prev_end, "end": next_start})
+
+        # Check for gap at the end (after last speech segment)
+        last_speech = speech_segments[-1]
+        if last_speech["end"] < duration_ms:
+            gaps.append({"start": last_speech["end"], "end": duration_ms})
+
+        return gaps

speech_detect-0.1.0/src/vad_parser.py

@@ -0,0 +1,138 @@
+"""
+VAD State Machine Parser
+
+Parses fragmented output from Fsmn_vad_online model and converts it into
+complete {start, end} segment semantics. Handles partial segments that span
+multiple chunks in streaming processing.
+"""
+
+import logging
+
+from .vad_types import VadSegment
+
+logger = logging.getLogger(__name__)
+
+
+class VadParser:
+    """
+    State machine parser for Fsmn_vad_online fragmented output.
+
+    Converts fragmented VAD model output into complete {start, end} segment semantics.
+    Maintains state across chunks to handle segments that span multiple processing chunks.
+    """
+
+    def __init__(self):
+        """Initialize VAD parser."""
+        self.current_start_ms = -1
+
+    def _process_segment_pair(self, beg_ms: int, end_ms: int, completed_segments: "list[VadSegment]") -> None:
+        """
+        Process a single [start, end] pair, supporting three cases:
+        1. [[beg, -1]] -> Speech start detected but not ended (partial segment)
+        2. [[-1, end]] -> Speech end detected (completes previous start)
+        3. [[beg, end]] -> Complete segment within single chunk
+
+        Args:
+            beg_ms: Start time in milliseconds (int or float).
+            end_ms: End time in milliseconds (int or float).
+            completed_segments: List to store completed segments.
+        """
+        # Convert to integers
+        if not isinstance(beg_ms, (int, float)):
+            beg_ms = -1
+        else:
+            beg_ms = int(beg_ms)
+
+        if not isinstance(end_ms, (int, float)):
+            end_ms = -1
+        else:
+            end_ms = int(end_ms)
+
+        # Case 1: Speech start detected but not ended (partial segment)
+        if beg_ms != -1 and end_ms == -1:
+            # Fsmn_vad_online returns global timestamps, use directly
+            self.current_start_ms = beg_ms
+            # Don't add to completed_segments yet, wait for end
+
+        # Case 2: Speech end detected (completes previous start)
+        elif beg_ms == -1 and end_ms != -1:
+            if self.current_start_ms != -1:
+                completed_segments.append(
+                    {
+                        "start": self.current_start_ms,
+                        "end": end_ms,  # Fsmn_vad_online returns global timestamps
+                    }
+                )
+                self.current_start_ms = -1  # Reset state
+            else:
+                # Edge case: end without start (possibly from previous chunk), log warning
+                logger.warning(f"[VAD Parser] Found end without start: end_ms={end_ms}")
+
+        # Case 3: Complete segment within single chunk
+        elif beg_ms != -1 and end_ms != -1:
+            completed_segments.append(
+                {
+                    "start": beg_ms,  # Fsmn_vad_online returns global timestamps
+                    "end": end_ms,
+                }
+            )
+            # If there was an unclosed start, reset it (new complete segment encountered)
+            self.current_start_ms = -1
+
+    def parse(self, vad_output: list) -> "list[VadSegment]":
+        """
+        Parse VAD model inference output and return completed segments.
+
+        Handles nested list structures and partial segments. Maintains state
+        across calls to handle segments spanning multiple chunks.
+
+        Args:
+            vad_output: VAD model output, format: [[beg, end], ...] or [[beg, -1]], [[-1, end]]
+                       Note: Fsmn_vad_online returns global timestamps (relative to stream start).
+
+        Returns:
+            list[VadSegment]: List of completed speech segments, format: [{"start": ms, "end": ms}, ...]
+        """
+        if not vad_output:
+            return []
+
+        # Unwrap all nested layers
+        # Format: [[[beg, end], ...]] or [[beg, end], ...] -> [[beg, end], ...]
+        while isinstance(vad_output, list) and len(vad_output) == 1:
+            vad_output = vad_output[0]
+            if not isinstance(vad_output, list):
+                break
+
+        completed_segments = []
+
+        # Process normalized output format: [[beg, end], ...]
+        for seg in vad_output:
+            if isinstance(seg, (list, tuple)) and len(seg) >= 2:
+                beg_ms, end_ms = seg[0], seg[1]
+                # Convert to integers (handle possible floats)
+                beg_ms = int(beg_ms) if isinstance(beg_ms, (int, float)) else -1
+                end_ms = int(end_ms) if isinstance(end_ms, (int, float)) else -1
+                # Process segment pair (supports [beg, -1], [-1, end], [beg, end])
+                self._process_segment_pair(beg_ms, end_ms, completed_segments)
+            else:
+                # Skip invalid segment formats
+                logger.warning(f"[VAD Parser] Invalid segment format: {seg}")
+
+        return completed_segments
+
+    def flush(self) -> "list[VadSegment]":
+        """
+        Flush parser state at end of stream.
+
+        Handles any unclosed segments. If a start was detected but not ended,
+        it's discarded (typically treated as silence at end of stream).
+
+        Returns:
+            list[VadSegment]: List of remaining completed segments (usually empty).
+        """
+        # If there's an unclosed start, it typically means audio was cut off mid-speech
+        # Use simple discard logic (treat as silence at end)
+        if self.current_start_ms != -1:
+            logger.warning(f"[VAD Parser] Unclosed segment at end of stream: start_ms={self.current_start_ms}")
+            self.current_start_ms = -1
+        return []

speech_detect-0.1.0/src/vad_types.py

@@ -0,0 +1,27 @@
+"""
+Type definitions for VAD detection.
+
+Defines TypedDict structures for VAD segments used throughout the package.
+"""
+
+from typing import TypedDict
+
+
+class VadSegment(TypedDict):
+    """
+    VAD segment type.
+
+    Represents a time segment (can be speech segment or non-speech gap).
+    Timestamps are relative to the start of the audio stream.
+
+    This type is used for:
+    - Speech segments: Detected speech time periods
+    - Non-speech gaps: Non-speech time periods
+
+    Attributes:
+        start: Segment start time in milliseconds (integer).
+        end: Segment end time in milliseconds (integer).
+    """
+
+    start: int
+    end: int