speech-prep 0.1.3__py3-none-any.whl

speech_prep/__init__.py

@@ -0,0 +1,34 @@
+"""
+Speech Prep - Audio preprocessing toolkit for speech-to-text applications.
+
+This package provides tools to prepare audio files for speech-to-text processing,
+including silence detection and removal, speed adjustment, and format conversion.
+"""
+
+from .core import SoundFile
+from .exceptions import (
+    AudioPropertiesError,
+    FFmpegError,
+    FileValidationError,
+    SilenceDetectionError,
+    SpeechPrepError,
+)
+
+# Import version from hatch-vcs
+try:
+    from importlib.metadata import version as get_metadata_version
+
+    __version__ = get_metadata_version("speech-prep")
+except ImportError:
+    # Development or not installed
+    __version__ = "0.0.0"
+
+__all__ = [
+    "SoundFile",
+    "SpeechPrepError",
+    "FFmpegError",
+    "FileValidationError",
+    "AudioPropertiesError",
+    "SilenceDetectionError",
+    "__version__",
+]

speech_prep/core.py

@@ -0,0 +1,203 @@
+"""Core SoundFile class for audio file manipulation."""
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+from .detection import calculate_median_silence, detect_silence
+from .exceptions import SpeechPrepError
+from .processing import adjust_speed, convert_format, strip_silence
+from .utils import format_time, get_audio_properties
+
+# Configure package logger
+logger = logging.getLogger("speech_prep")
+if not logger.hasHandlers():
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter("[%(levelname)s] %(name)s: %(message)s")
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.WARNING)
+
+
+class SoundFile:
+    """Represents an audio file with silence detection and processing capabilities."""
+
+    def __init__(
+        self,
+        path: Path,
+        noise_threshold_db: int = -30,
+        min_silence_duration: float = 0.5,
+    ):
+        """
+        Initialize a SoundFile object.
+
+        Args:
+            path: Path to the audio file
+            noise_threshold_db: Threshold (in dB) for silence detection
+            min_silence_duration: Minimum duration (in seconds) to consider as silence
+        """
+        self.path = Path(path)
+        if not self.path.exists():
+            raise FileNotFoundError(f"Audio file not found: {self.path}")
+
+        try:
+            self.duration, self.file_size, self.format = get_audio_properties(self.path)
+        except Exception as e:
+            raise SpeechPrepError(f"Failed to extract metadata: {e}") from e
+
+        try:
+            self.silence_periods = detect_silence(
+                self.path,
+                noise_threshold_db=noise_threshold_db,
+                min_silence_duration=min_silence_duration,
+            )
+        except Exception:
+            self.silence_periods = []
+
+        if self.silence_periods:
+            self.median_silence = calculate_median_silence(self.silence_periods)
+        else:
+            self.median_silence = 0.0
+
+        self.noise_threshold_db = noise_threshold_db
+        self.min_silence_duration = min_silence_duration
+
+    def __eq__(self, other: object) -> bool:
+        """Two files are equal if they reference the same path."""
+        if not isinstance(other, SoundFile):
+            return False
+        return self.path == other.path
+
+    def __str__(self) -> str:
+        """
+        Return a string representation of the SoundFile object.
+
+        Displays a summary of audio properties and the first/last three silence periods.
+        """
+        # Format basic audio information
+        basic_info = [
+            f"SoundFile: {self.path}",
+            f"  Duration: {self.duration:.2f} seconds ({format_time(self.duration)})",
+            f"  Format: {self.format}",
+            f"  File size: {self.file_size / 1024 / 1024:.2f} MB",
+            f"  Silence periods: {len(self.silence_periods)} detected",
+            f"  Median silence: {self.median_silence:.2f} seconds",
+        ]
+
+        # Format silence periods (first 3, ellipsis, last 3)
+        silence_info = ["  Silence periods:"]
+        if self.silence_periods:
+            # Always show at least the first and last if there are any
+            total_periods = len(self.silence_periods)
+
+            # Determine how many to show at start and end
+            to_show = min(3, total_periods)
+
+            # Add the first 'to_show' periods
+            for i in range(to_show):
+                start, end, duration = self.silence_periods[i]
+                silence_info.append(
+                    f"    {i + 1}: {start:.2f}s - {end:.2f}s ({duration:.2f}s) "
+                    f"[{format_time(start)} - {format_time(end)}]"
+                )
+
+            # Add ellipsis if there are more than 2*to_show periods
+            if total_periods > 2 * to_show:
+                silence_info.append(
+                    f"    ... {total_periods - 2 * to_show} more periods ..."
+                )
+
+            # Add the last 'to_show' periods if there are more than 'to_show' total
+            if total_periods > to_show:
+                for i in range(max(to_show, total_periods - to_show), total_periods):
+                    start, end, duration = self.silence_periods[i]
+                    silence_info.append(
+                        f"    {i + 1}: {start:.2f}s - {end:.2f}s ({duration:.2f}s) "
+                        f"[{format_time(start)} - {format_time(end)}]"
+                    )
+        else:
+            silence_info.append("    None detected")
+
+        # Combine all information
+        return "\n".join(basic_info + silence_info)
+
+    # __new__ removed; all initialization is handled in __init__
+
+    def strip(
+        self, output_path: Path, leading: bool = True, trailing: bool = True
+    ) -> Optional["SoundFile"]:
+        """
+        Create a new audio file with leading and/or trailing silence removed.
+
+        Args:
+            output_path: Path to save the new file.
+            leading: Whether to remove leading silence
+            trailing: Whether to remove trailing silence
+        Returns:
+            A new SoundFile instance for the created file, or None if operation failed
+        """
+        if not self.silence_periods:
+            logger.info(
+                f"No silence periods detected in {self.path}, nothing to strip."
+            )
+            return self
+        try:
+            strip_silence(
+                self.path,
+                output_path,
+                self.silence_periods,
+                self.duration,
+                leading,
+                trailing,
+            )
+            return SoundFile(
+                output_path, self.noise_threshold_db, self.min_silence_duration
+            )
+        except SpeechPrepError as e:
+            logger.error(f"Error during strip: {e}")
+            return None
+
+    def convert(
+        self, output_path: Path, audio_bitrate: Optional[str] = None
+    ) -> Optional["SoundFile"]:
+        """
+        Convert the audio file to a different format.
+
+        Args:
+            output_path: Path to save the converted file
+            audio_bitrate: Optional bitrate for the output file (e.g., '192k', '320k')
+
+        Returns:
+            A new SoundFile instance for the converted file, or None if operation failed
+        """
+        try:
+            convert_format(self.path, output_path, audio_bitrate)
+            return SoundFile(
+                output_path, self.noise_threshold_db, self.min_silence_duration
+            )
+        except SpeechPrepError as e:
+            logger.error(f"Error during convert: {e}")
+            return None
+
+    def speed(self, output_path: Path, speed_factor: float) -> Optional["SoundFile"]:
+        """
+        Create a new audio file with adjusted playback speed.
+
+        Args:
+            output_path: Path to save the new file.
+            speed_factor: Speed multiplier (e.g., 2.0 for 2x speed, 0.5 for half speed)
+
+        Returns:
+            A new SoundFile instance for the created file, or None if operation failed
+        """
+        try:
+            adjust_speed(self.path, output_path, speed_factor)
+            # Adjust silence threshold for the new file
+            adjusted_threshold = self.min_silence_duration / speed_factor
+            logger.info(
+                f"Silence threshold: {adjusted_threshold:.2f}s for sped-up file"
+            )
+            return SoundFile(output_path, self.noise_threshold_db, adjusted_threshold)
+        except SpeechPrepError as e:
+            logger.error(f"Error during speed: {e}")
+            return None

speech_prep/detection.py

@@ -0,0 +1,116 @@
+"""Silence detection functionality for audio files."""
+
+from pathlib import Path
+import re
+import subprocess
+from typing import Optional
+
+from .exceptions import SilenceDetectionError
+
+
+def detect_silence(
+    file_path: Path, noise_threshold_db: int, min_silence_duration: float
+) -> list[tuple[float, float, float]]:
+    """
+    Detect silence periods using ffmpeg silencedetect filter.
+
+    Args:
+        file_path: Path to the audio file
+        noise_threshold_db: Threshold (in dB) for silence detection
+        min_silence_duration: Minimum duration (in seconds) to consider as silence
+
+    Returns:
+        List of silence periods as (start, end, duration) tuples
+
+    Raises:
+        SilenceDetectionError: If silence detection fails
+    """
+    silence_cmd = [
+        "ffmpeg",
+        "-i",
+        str(file_path),
+        "-af",
+        f"silencedetect=noise={noise_threshold_db}dB:d={min_silence_duration}",
+        "-f",
+        "null",
+        "-",
+    ]
+
+    try:
+        silence_proc = subprocess.run(
+            silence_cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except subprocess.CalledProcessError as e:
+        raise SilenceDetectionError(
+            f"Error detecting silence in file {file_path}: {e.stderr}"
+        ) from e
+    except FileNotFoundError as e:
+        raise SilenceDetectionError(
+            "ffmpeg not found. Please ensure ffmpeg is installed and accessible."
+        ) from e
+
+    return parse_silence_output(silence_proc.stderr)
+
+
+def parse_silence_output(silence_output: str) -> list[tuple[float, float, float]]:
+    """
+    Parse the ffmpeg silence detection output to extract silence periods.
+
+    Args:
+        silence_output: stderr output from ffmpeg silence detection
+
+    Returns:
+        List of silence periods as (start, end, duration) tuples
+    """
+    silence_periods = []
+    start_time: Optional[float] = None
+
+    for line in silence_output.splitlines():
+        if "silence_start" in line:
+            # Extract the start time
+            match = re.search(r"silence_start: (\d+(?:\.\d+)?)", line)
+            if match:
+                start_time = float(match.group(1))
+        elif "silence_end" in line and start_time is not None:
+            # Extract the end time and duration
+            match = re.search(
+                r"silence_end: (\d+(?:\.\d+)?) \| silence_duration: (\d+(?:\.\d+)?)",
+                line,
+            )
+            if match:
+                end_time = float(match.group(1))
+                silence_duration = float(match.group(2))
+                silence_periods.append((start_time, end_time, silence_duration))
+                start_time = None
+
+    return silence_periods
+
+
+def calculate_median_silence(
+    silence_periods: list[tuple[float, float, float]],
+) -> float:
+    """
+    Calculate the median duration of silence periods.
+
+    Args:
+        silence_periods: List of silence periods as (start, end, duration) tuples
+
+    Returns:
+        Median silence duration in seconds
+    """
+    if not silence_periods:
+        return 0.0
+
+    silence_durations = [duration for _, _, duration in silence_periods]
+    silence_durations.sort()
+
+    n = len(silence_durations)
+    if n % 2 == 0:
+        # Even number of elements - take average of middle two
+        return (silence_durations[n // 2 - 1] + silence_durations[n // 2]) / 2
+    else:
+        # Odd number of elements - take middle element
+        return silence_durations[n // 2]

speech_prep/exceptions.py

@@ -0,0 +1,49 @@
+"""Custom exceptions for the speech-prep package."""
+
+from typing import Optional
+
+
+class SpeechPrepError(Exception):
+    """Base exception for all speech-prep related errors."""
+
+    pass
+
+
+class FFmpegError(SpeechPrepError):
+    """Raised when ffmpeg command fails or returns an error."""
+
+    def __init__(
+        self,
+        message: str,
+        stderr: Optional[str] = None,
+        returncode: Optional[int] = None,
+    ):
+        """
+        Initialize FFmpegError with error details.
+
+        Args:
+            message: Error message
+            stderr: Standard error output from ffmpeg
+            returncode: Return code from ffmpeg process
+        """
+        self.stderr = stderr
+        self.returncode = returncode
+        super().__init__(message)
+
+
+class FileValidationError(SpeechPrepError):
+    """Raised when file validation fails."""
+
+    pass
+
+
+class AudioPropertiesError(SpeechPrepError):
+    """Raised when audio properties cannot be extracted."""
+
+    pass
+
+
+class SilenceDetectionError(SpeechPrepError):
+    """Raised when silence detection fails."""
+
+    pass

speech_prep/processing.py

@@ -0,0 +1,185 @@
+"""Audio processing operations for speech preparation."""
+
+from pathlib import Path
+import subprocess
+from typing import Optional
+
+from .exceptions import FFmpegError
+
+
+def strip_silence(
+    input_path: Path,
+    output_path: Path,
+    silence_periods: list[tuple[float, float, float]],
+    total_duration: float,
+    leading: bool = True,
+    trailing: bool = True,
+) -> None:
+    """
+    Create a new audio file with leading and/or trailing silence removed.
+
+    Args:
+        input_path: Path to the input audio file
+        output_path: Path to save the new file
+        silence_periods: List of silence periods as (start, end, duration) tuples
+        total_duration: Total duration of the audio file
+        leading: Whether to remove leading silence
+        trailing: Whether to remove trailing silence
+
+    Raises:
+        FFmpegError: If the ffmpeg operation fails
+    """
+    if not silence_periods:
+        raise FFmpegError("No silence periods detected, nothing to strip")
+
+    # Determine start and end times based on silence periods
+    start_time = 0.0
+    end_time = total_duration
+
+    if leading and silence_periods[0][0] == 0:
+        # First silence period starts at 0, so it's leading silence
+        start_time = silence_periods[0][1]
+
+    if trailing:
+        last_silence = silence_periods[-1]
+        # Check if the last silence extends to the end of the file
+        # Allow a small buffer (0.1s) for rounding errors
+        if abs(last_silence[1] - total_duration) < 0.1:
+            end_time = last_silence[0]
+
+    # Use ffmpeg to cut the file
+    cmd = [
+        "ffmpeg",
+        "-y",  # Overwrite output file if it exists
+        "-i",
+        str(input_path),
+        "-ss",
+        str(start_time),  # Start time
+        "-to",
+        str(end_time),  # End time
+        "-c",
+        "copy",  # Copy streams without re-encoding
+        str(output_path),
+    ]
+
+    print(f"Stripping silence: {start_time:.2f}s to {end_time:.2f}s")
+    _run_ffmpeg_command(cmd, "stripping silence")
+
+
+def convert_format(
+    input_path: Path, output_path: Path, audio_bitrate: Optional[str] = None
+) -> None:
+    """
+    Convert the audio file to a different format.
+
+    Args:
+        input_path: Path to the input audio file
+        output_path: Path to save the converted file
+        audio_bitrate: Optional bitrate for the output file (e.g., '192k', '320k')
+
+    Raises:
+        FFmpegError: If the ffmpeg operation fails
+    """
+    # Build ffmpeg command
+    cmd = ["ffmpeg", "-y", "-i", str(input_path)]
+
+    # Add bitrate if specified
+    if audio_bitrate:
+        cmd.extend(["-b:a", audio_bitrate])
+
+    # Add output file
+    cmd.append(str(output_path))
+
+    input_format = input_path.suffix.lower().lstrip(".")
+    output_format = output_path.suffix.lower().lstrip(".")
+    print(f"Converting {input_path.name} from {input_format} to {output_format}")
+
+    _run_ffmpeg_command(cmd, "converting format")
+
+
+def adjust_speed(input_path: Path, output_path: Path, speed_factor: float) -> None:
+    """
+    Create a new audio file with adjusted playback speed.
+
+    Args:
+        input_path: Path to the input audio file
+        output_path: Path to save the speed-adjusted file
+        speed_factor: Speed multiplier (e.g., 2.0 for 2x speed, 0.5 for half speed)
+
+    Raises:
+        FFmpegError: If the ffmpeg operation fails or speed_factor is invalid
+    """
+    if speed_factor <= 0:
+        raise FFmpegError("Speed factor must be positive")
+
+    # Use ffmpeg's atempo filter for speed adjustment
+    # Note: atempo filter is limited to 0.5x to 2.0x range
+    # For factors outside this range, we need to chain multiple atempo filters
+
+    atempo_filters = []
+    remaining_factor = speed_factor
+
+    # Split into multiple atempo filters if needed
+    while remaining_factor > 2.0:
+        atempo_filters.append("atempo=2.0")
+        remaining_factor /= 2.0
+
+    while remaining_factor < 0.5:
+        atempo_filters.append("atempo=0.5")
+        remaining_factor /= 0.5
+
+    # Add the final adjustment
+    if abs(remaining_factor - 1.0) > 0.01:  # If not very close to 1.0
+        atempo_filters.append(f"atempo={remaining_factor}")
+
+    # Build the filter string
+    filter_str = ",".join(atempo_filters) if atempo_filters else "atempo=1.0"
+
+    # Determine appropriate codec based on output format
+    output_format = output_path.suffix.lower()
+    if output_format == ".mp3":
+        codec = "libmp3lame"
+    elif output_format == ".wav":
+        codec = "pcm_s16le"
+    else:
+        codec = "libmp3lame"  # Default to mp3 codec
+
+    # Build ffmpeg command
+    cmd = [
+        "ffmpeg",
+        "-y",
+        "-i",
+        str(input_path),
+        "-filter:a",
+        filter_str,
+        "-c:a",
+        codec,
+        str(output_path),
+    ]
+
+    print(f"Adjusting speed by factor {speed_factor}x using filter: {filter_str}")
+    _run_ffmpeg_command(cmd, "adjusting speed")
+
+
+def _run_ffmpeg_command(cmd: list[str], operation_name: str) -> None:
+    """
+    Run an ffmpeg command with error handling.
+
+    Args:
+        cmd: List of command arguments
+        operation_name: Description of the operation for error messages
+
+    Raises:
+        FFmpegError: If ffmpeg command fails
+    """
+    try:
+        subprocess.run(cmd, capture_output=True, text=True, check=True)
+    except subprocess.CalledProcessError as e:
+        raise FFmpegError(
+            f"Error during {operation_name}", stderr=e.stderr, returncode=e.returncode
+        ) from e
+    except FileNotFoundError as e:
+        raise FFmpegError(
+            f"ffmpeg not found during {operation_name}. "
+            "Please ensure ffmpeg is installed and accessible."
+        ) from e

speech_prep/utils.py

@@ -0,0 +1,130 @@
+"""Utility functions for audio file operations."""
+
+import json
+from pathlib import Path
+import subprocess
+
+from .exceptions import AudioPropertiesError, FileValidationError
+
+
+def validate_file(file_path: Path) -> bool:
+    """
+    Validate that the file exists and is a regular file.
+
+    Args:
+        file_path: Path to the file to validate
+
+    Returns:
+        True if file is valid
+
+    Raises:
+        FileValidationError: If file doesn't exist or is not a regular file
+    """
+    if not file_path.exists():
+        raise FileValidationError(f"File {file_path} does not exist")
+
+    if not file_path.is_file():
+        raise FileValidationError(f"Path {file_path} is not a regular file")
+
+    return True
+
+
+def get_audio_properties(file_path: Path) -> tuple[float, int, str]:
+    """
+    Extract audio properties (duration, file size, format) using ffprobe.
+
+    Args:
+        file_path: Path to the audio file
+
+    Returns:
+        Tuple of (duration, file_size, audio_format)
+
+    Raises:
+        AudioPropertiesError: If properties cannot be extracted
+    """
+    probe_cmd = [
+        "ffprobe",
+        "-v",
+        "error",
+        "-show_entries",
+        "format=duration,size,format_name",
+        "-of",
+        "json",
+        str(file_path),
+    ]
+
+    try:
+        probe_result = subprocess.run(
+            probe_cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except subprocess.CalledProcessError as e:
+        raise AudioPropertiesError(f"Error probing file {file_path}: {e.stderr}") from e
+    except FileNotFoundError as e:
+        raise AudioPropertiesError(
+            "ffprobe not found. Please ensure ffmpeg is installed and accessible."
+        ) from e
+
+    try:
+        probe_data = json.loads(probe_result.stdout)["format"]
+        duration = float(probe_data["duration"])
+        file_size = int(probe_data["size"])
+        audio_format = probe_data["format_name"].split(",")[
+            0
+        ]  # Get the first format name
+
+        if duration <= 0 or file_size <= 0:
+            raise AudioPropertiesError(
+                f"Invalid duration or file size for {file_path}. "
+                f"Duration: {duration}, Size: {file_size}"
+            )
+
+        return duration, file_size, audio_format
+
+    except (KeyError, ValueError, json.JSONDecodeError) as e:
+        raise AudioPropertiesError(f"Error parsing probe data: {e}") from e
+
+
+def format_time(seconds: float) -> str:
+    """
+    Format seconds as HH:MM:SS.
+
+    Args:
+        seconds: Time in seconds
+
+    Returns:
+        Formatted time string
+    """
+    hours, remainder = divmod(int(seconds), 3600)
+    minutes, seconds_int = divmod(remainder, 60)
+    return f"{hours:02}:{minutes:02}:{seconds_int:02}"
+
+
+def run_ffmpeg_command(
+    cmd: list[str], operation_name: str
+) -> subprocess.CompletedProcess[str]:
+    """
+    Run an ffmpeg command with error handling.
+
+    Args:
+        cmd: List of command arguments
+        operation_name: Description of the operation for error messages
+
+    Returns:
+        CompletedProcess result
+
+    Raises:
+        AudioPropertiesError: If ffmpeg command fails
+    """
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+        return result
+
+    except subprocess.CalledProcessError as e:
+        raise AudioPropertiesError(f"Error during {operation_name}: {e.stderr}") from e
+    except FileNotFoundError as e:
+        raise AudioPropertiesError(
+            "ffmpeg not found. Please ensure ffmpeg is installed and accessible."
+        ) from e

speech_prep-0.1.3.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: speech-prep
+Version: 0.1.3
+Summary: Audio preprocessing toolkit for speech-to-text applications using ffmpeg
+Project-URL: Homepage, https://github.com/dimdasci/speech-prep
+Project-URL: Repository, https://github.com/dimdasci/speech-prep
+Project-URL: Issues, https://github.com/dimdasci/speech-prep/issues
+Author-email: Dim Kharitonov <dimds@fastmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: audio,ffmpeg,preprocessing,silence-detection,speech-to-text
+Classifier: Development Status :: 3 - Alpha
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# Speech Prep
+
+Audio preprocessing toolkit for speech-to-text applications using FFmpeg.
+
+## Overview
+
+Speech Prep is a Python package designed to prepare audio files for speech-to-text processing. It provides tools for silence detection and removal, speed adjustment, and format conversion - all essential steps for optimizing audio before transcription.
+
+## Features
+
+- **Silence Detection**: Automatically detect silence periods in audio files
+- **Silence Removal**: Remove leading/trailing silence to clean up recordings
+- **Speed Adjustment**: Change playback speed while maintaining audio quality
+- **Format Conversion**: Convert between different audio formats (MP3, WAV, FLAC, etc.)
+- **Clean API**: Simple, intuitive interface with method chaining support
+- **FFmpeg Integration**: Leverages the power and reliability of FFmpeg
+
+## Requirements
+
+- Python 3.9+
+- FFmpeg (must be installed and accessible via PATH)
+
+## Installation
+
+```bash
+# Install from PyPI (when published)
+pip install speech-prep
+
+# Or install from source
+git clone https://github.com/dimdasci/speech-prep.git
+cd speech-prep
+uv sync  # or pip install -e .
+```
+
+## Quick Start
+
+```python
+from speech_prep import SoundFile
+from pathlib import Path
+
+# Load an audio file
+audio = SoundFile(Path("recording.wav"))
+
+if audio:
+    print(f"Duration: {audio.duration:.2f} seconds")
+    print(f"Format: {audio.format}")
+    print(f"Silence periods detected: {len(audio.silence_periods)}")
+
+    # Clean up the audio for speech-to-text
+    cleaned = audio.strip(output_path=Path("recording_stripped.wav"))
+    faster = cleaned.speed(output_path=Path("recording_stripped_fast.wav"), speed_factor=1.2)
+    final = faster.convert(output_path=Path("clean.mp3"))
+
+    print(f"Processed file saved: {final.path}")
+```
+
+## Usage Examples
+
+### Basic Operations
+
+```python
+from speech_prep import SoundFile
+from pathlib import Path
+
+# Load audio file
+audio = SoundFile(Path("interview.wav"))
+
+# View audio information
+print(audio)  # Shows duration, format, file size, and silence periods
+
+# Remove silence from beginning and end
+cleaned = audio.strip(output_path=Path("interview_stripped.wav"))
+
+# Remove only leading silence
+cleaned = audio.strip(output_path=Path("interview_leading.wav"), trailing=False)
+
+# Speed up audio by 50%
+faster = audio.speed(output_path=Path("interview_fast.wav"), speed_factor=1.5)
+
+# Convert format
+mp3_file = audio.convert(output_path=Path("output.mp3"))
+```
+
+### Processing Pipeline
+
+```python
+from speech_prep import SoundFile
+from pathlib import Path
+
+def prepare_for_transcription(input_file: Path, output_file: Path):
+    """Prepare audio file for speech-to-text processing."""
+    # Load the original file
+    audio = SoundFile(input_file)
+    if not audio:
+        return None
+    # Processing pipeline
+    stripped = audio.strip(output_path=input_file.with_stem(input_file.stem + "_stripped"))
+    faster = stripped.speed(output_path=input_file.with_stem(input_file.stem + "_stripped_fast"), speed_factor=1.1)
+    processed = faster.convert(output_path=output_file)
+    if processed:
+        print(f"Original duration: {audio.duration:.2f}s")
+        print(f"Processed duration: {processed.duration:.2f}s")
+        print(f"Time saved: {audio.duration - processed.duration:.2f}s")
+    return processed
+
+# Use the pipeline
+result = prepare_for_transcription(
+    Path("long_meeting.wav"),
+    Path("ready_for_stt.mp3")
+)
+```
+
+### Error Handling
+
+```python
+from speech_prep import SoundFile, SpeechPrepError, FFmpegError
+from pathlib import Path
+
+try:
+    audio = SoundFile(Path("audio.wav"))
+    if audio:
+        result = audio.strip().speed(2.0)
+        print(f"Success: {result.path}")
+    else:
+        print("Failed to load audio file")
+
+except FFmpegError as e:
+    print(f"FFmpeg error: {e}")
+    if e.stderr:
+        print(f"Details: {e.stderr}")
+
+except SpeechPrepError as e:
+    print(f"Processing error: {e}")
+```
+
+### Custom Parameters
+
+```python
+from speech_prep import SoundFile
+from pathlib import Path
+
+# Custom silence detection settings
+audio = SoundFile(
+    Path("audio.wav"),
+    noise_threshold_db=-40,    # More sensitive silence detection
+    min_silence_duration=0.3   # Shorter minimum silence periods
+)
+
+# Custom output paths
+cleaned = audio.strip(output_path=Path("custom_output.wav"))
+
+# Custom conversion settings
+mp3 = audio.convert(
+    output_path=Path("output.mp3"),
+    audio_bitrate="192k"  # Custom bitrate
+)
+```
+
+## API Reference
+
+### SoundFile Class
+
+#### Constructor
+```python
+SoundFile(file_path, noise_threshold_db=-30, min_silence_duration=0.5)
+```
+
+#### Methods
+- **`strip(output_path, leading=True, trailing=True)`**: Remove silence
+- **`speed(output_path, speed_factor)`**: Adjust playback speed
+- **`convert(output_path, audio_bitrate=None)`**: Convert format
+
+#### Properties
+- **`path`**: Path to the audio file
+- **`duration`**: Duration in seconds
+- **`format`**: Audio format
+- **`file_size`**: File size in bytes
+- **`silence_periods`**: List of detected silence periods
+- **`median_silence`**: Median silence duration
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Acknowledgments
+
+- Built on top of the powerful [FFmpeg](https://ffmpeg.org/) multimedia framework

speech_prep-0.1.3.dist-info/RECORD

@@ -0,0 +1,10 @@
+speech_prep/__init__.py,sha256=0Eu8vjSjvG3sOQbN9dsjtQkKcVBPcLthK4Eit0UrtAQ,839
+speech_prep/core.py,sha256=pe4djUP1wQF4TJiaw1lg7xIvBzVHOMWP7dHgar3unt4,7567
+speech_prep/detection.py,sha256=D5_WkTYoFDUIYA2u6cfWK6E_Rd5R6g1Lng0Hh1UGgBs,3495
+speech_prep/exceptions.py,sha256=qZcIzM-IPltgJNtfmj5K4D8OJsL1zButmLnshas9m4M,1091
+speech_prep/processing.py,sha256=421IqfAcRUqMtXBsiTypSp_4H0X3uh5UjQ8Af-nPaX0,5684
+speech_prep/utils.py,sha256=_yjn1hoVVHfLc3nGAhD2n6bsevgweqNOt1rsDyahQnY,3585
+speech_prep-0.1.3.dist-info/METADATA,sha256=8wP2R43DbY7JH9S8r1_DJlWKPsYMgi9CIIl8HpZMLsI,6616
+speech_prep-0.1.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+speech_prep-0.1.3.dist-info/licenses/LICENSE,sha256=-M8NcLlGaRvQqThXHq5g0D9CUR05KMhdswCB9s_0Sds,1066
+speech_prep-0.1.3.dist-info/RECORD,,

speech_prep-0.1.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

speech_prep-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dim Kharitonov
+
+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 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.