aisrt 0.1.0__tar.gz

aisrt-0.1.0/LICENSE

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

aisrt-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: aisrt
+Version: 0.1.0
+Summary: Hardware-aware, concurrent pipeline for subtitle generation.
+License-File: LICENSE
+Author: Arvind
+Author-email: arvind@example.com
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: aiosqlite (>=0.19.0,<0.20.0)
+Requires-Dist: faster-whisper (>=1.0.0,<2.0.0)
+Requires-Dist: loguru (>=0.7.2,<0.8.0)
+Requires-Dist: psutil (>=5.9.8,<6.0.0)
+Requires-Dist: pydantic (>=2.5.3,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.1.0,<3.0.0)
+Requires-Dist: pynvml (>=11.5.0,<12.0.0)
+Requires-Dist: rich (>=13.7.0,<14.0.0)
+Requires-Dist: typer[all] (>=0.9.0,<0.10.0)
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <h1>🎬 Ultimate SRT Generator</h1>
+  <p><strong>Hardware-aware, zero-disk, highly concurrent AI pipeline for mass-generating broadcast-quality subtitles.</strong></p>
+
+  [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+  [![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+  [![Checked with mypy](https://img.shields.io/badge/mypy-strict-blue)](https://mypy-lang.org/)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+</div>
+
+---
+
+## 🌟 Overview
+
+The **Ultimate SRT Generator** is a production-grade daemon built for power users, NAS hoarders, and sysadmins. It autonomously crawls massive network-attached media libraries, detects videos missing English subtitles, performs **zero-disk** audio extraction directly into RAM, and infers broadcast-quality `.srt` files using state-of-the-art [faster-whisper](https://github.com/SYSTRAN/faster-whisper) AI models.
+
+### 🛠️ Key Architectural Features
+
+*   **Zero-Disk Audio Extraction:** Stops SSD wear-and-tear by bypassing `/tmp/` files completely. Audio streams are asynchronously ripped via FFmpeg and piped directly into RAM (NumPy arrays) for AI ingestion.
+*   **Bounded Asynchronous Concurrency:** Eliminates Python GIL starvation via an `asyncio.TaskGroup` producer-consumer pipeline. It extracts audio streams exactly as fast as the GPU can transcribe them, strictly capping memory usage.
+*   **Intelligent Hardware Routing Matrix:** Auto-detects NVIDIA GPUs (VRAM), Apple Silicon, or pure CPU environments to intelligently route to the most optimal `large-v3-turbo`, `small`, or quantized `int8` model.
+*   **NAS-Safe & Deduplicating:** Backed by an asynchronous local SQLite database (WAL mode) tracking `inode` and `size`. It avoids parsing active downloads, seamlessly skips duplicate hardlinks, and performs strict POSIX Atomic `os.replace` operations with original MKV metadata inheritance.
+*   **Broadcast Formatting:** Implements a strict chunking algorithm on top of Whisper's word-level timestamps. No more "walls of text"—subtitles are limited to ~42 chars and 2 lines, naturally breaking on terminal punctuation.
+
+---
+
+## 🚀 Installation & Deployment
+
+### 🐳 Docker (Recommended for TrueNAS / Unraid)
+
+For maximum stability and ease-of-use with NVIDIA hardware, use the provided Docker stack.
+
+1.  Clone the repository:
+    ```bash
+    git clone https://github.com/arvarik/srt-generator.git
+    cd srt-generator
+    ```
+2.  Review and modify the `docker-compose.yml` to point to your media directory:
+    ```yaml
+    volumes:
+      - /mnt/user/media/movies:/media:rw
+      - ./aisrt_data:/root/.config/aisrt:rw
+    ```
+3.  Deploy:
+    ```bash
+    docker compose up --build -d
+    ```
+
+### 💻 Native Python (Ubuntu Desktop / Server / macOS)
+
+**Prerequisites:** Python 3.11+ and `ffmpeg` must be installed on your system.
+
+```bash
+# 1. Clone repository
+git clone https://github.com/arvarik/srt-generator.git
+cd srt-generator
+
+# 2. Create virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 3. Install the application
+pip install -e .
+
+# 4. (Optional) Install development dependencies
+pip install -e ".[dev]"
+```
+
+---
+
+## 🎮 Usage
+
+The application features a beautifully formatted CLI built on `Typer` and `Rich`.
+
+### Dry-Run (Scan)
+Safely scan a directory to see exactly what hardware will be loaded and what files will be processed, without actually running the AI model.
+
+```bash
+aisrt scan /path/to/movies --min-age-mins 60 --verbose
+```
+
+### Live Run
+Execute the extraction and inference pipeline.
+
+```bash
+aisrt run /path/to/movies
+```
+
+### CLI Overrides & Environment Variables
+You can manually override the hardware auto-detector and execution options.
+
+**Via CLI:**
+```bash
+aisrt run /path/to/movies --force-device cuda --force-model large-v3-turbo --translate --watch --watch-interval 60
+```
+
+**Via Docker Environment Variables:**
+Since `AppConfig` utilizes `pydantic-settings`, you can configure the daemon entirely through your `docker-compose.yml`:
+*   `AISRT_TRANSLATE=True` (Auto-dub foreign audio into English)
+*   `AISRT_WATCH=True` (Run 24/7 as a daemon)
+*   `AISRT_WATCH_INTERVAL_MINS=60` (Time between library scans)
+*   `AISRT_FILTERS__MIN_AGE_MINS=30` (Skip active torrent/usenet downloads)
+*   `AISRT_HARDWARE__FORCE_MODEL=large-v3-turbo`
+
+---
+
+## 🏗️ Open Source Development
+
+We welcome contributions! The codebase strictly adheres to enterprise-level typing and styling.
+
+**Development Setup:**
+```bash
+poetry install   # Or pip install -e ".[dev]"
+```
+
+**Running Tests & Linters:**
+```bash
+ruff check .           # Linter
+ruff format .          # Formatter
+mypy src/aisrt tests  # Strict Type Checking
+pytest tests           # Asynchronous Unit Tests
+```
+
+---
+
+## 📜 License
+Distributed under the MIT License. See `LICENSE` for more information.
+

aisrt-0.1.0/README.md

@@ -0,0 +1,127 @@
+<div align="center">
+  <h1>🎬 Ultimate SRT Generator</h1>
+  <p><strong>Hardware-aware, zero-disk, highly concurrent AI pipeline for mass-generating broadcast-quality subtitles.</strong></p>
+
+  [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+  [![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+  [![Checked with mypy](https://img.shields.io/badge/mypy-strict-blue)](https://mypy-lang.org/)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+</div>
+
+---
+
+## 🌟 Overview
+
+The **Ultimate SRT Generator** is a production-grade daemon built for power users, NAS hoarders, and sysadmins. It autonomously crawls massive network-attached media libraries, detects videos missing English subtitles, performs **zero-disk** audio extraction directly into RAM, and infers broadcast-quality `.srt` files using state-of-the-art [faster-whisper](https://github.com/SYSTRAN/faster-whisper) AI models.
+
+### 🛠️ Key Architectural Features
+
+*   **Zero-Disk Audio Extraction:** Stops SSD wear-and-tear by bypassing `/tmp/` files completely. Audio streams are asynchronously ripped via FFmpeg and piped directly into RAM (NumPy arrays) for AI ingestion.
+*   **Bounded Asynchronous Concurrency:** Eliminates Python GIL starvation via an `asyncio.TaskGroup` producer-consumer pipeline. It extracts audio streams exactly as fast as the GPU can transcribe them, strictly capping memory usage.
+*   **Intelligent Hardware Routing Matrix:** Auto-detects NVIDIA GPUs (VRAM), Apple Silicon, or pure CPU environments to intelligently route to the most optimal `large-v3-turbo`, `small`, or quantized `int8` model.
+*   **NAS-Safe & Deduplicating:** Backed by an asynchronous local SQLite database (WAL mode) tracking `inode` and `size`. It avoids parsing active downloads, seamlessly skips duplicate hardlinks, and performs strict POSIX Atomic `os.replace` operations with original MKV metadata inheritance.
+*   **Broadcast Formatting:** Implements a strict chunking algorithm on top of Whisper's word-level timestamps. No more "walls of text"—subtitles are limited to ~42 chars and 2 lines, naturally breaking on terminal punctuation.
+
+---
+
+## 🚀 Installation & Deployment
+
+### 🐳 Docker (Recommended for TrueNAS / Unraid)
+
+For maximum stability and ease-of-use with NVIDIA hardware, use the provided Docker stack.
+
+1.  Clone the repository:
+    ```bash
+    git clone https://github.com/arvarik/srt-generator.git
+    cd srt-generator
+    ```
+2.  Review and modify the `docker-compose.yml` to point to your media directory:
+    ```yaml
+    volumes:
+      - /mnt/user/media/movies:/media:rw
+      - ./aisrt_data:/root/.config/aisrt:rw
+    ```
+3.  Deploy:
+    ```bash
+    docker compose up --build -d
+    ```
+
+### 💻 Native Python (Ubuntu Desktop / Server / macOS)
+
+**Prerequisites:** Python 3.11+ and `ffmpeg` must be installed on your system.
+
+```bash
+# 1. Clone repository
+git clone https://github.com/arvarik/srt-generator.git
+cd srt-generator
+
+# 2. Create virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 3. Install the application
+pip install -e .
+
+# 4. (Optional) Install development dependencies
+pip install -e ".[dev]"
+```
+
+---
+
+## 🎮 Usage
+
+The application features a beautifully formatted CLI built on `Typer` and `Rich`.
+
+### Dry-Run (Scan)
+Safely scan a directory to see exactly what hardware will be loaded and what files will be processed, without actually running the AI model.
+
+```bash
+aisrt scan /path/to/movies --min-age-mins 60 --verbose
+```
+
+### Live Run
+Execute the extraction and inference pipeline.
+
+```bash
+aisrt run /path/to/movies
+```
+
+### CLI Overrides & Environment Variables
+You can manually override the hardware auto-detector and execution options.
+
+**Via CLI:**
+```bash
+aisrt run /path/to/movies --force-device cuda --force-model large-v3-turbo --translate --watch --watch-interval 60
+```
+
+**Via Docker Environment Variables:**
+Since `AppConfig` utilizes `pydantic-settings`, you can configure the daemon entirely through your `docker-compose.yml`:
+*   `AISRT_TRANSLATE=True` (Auto-dub foreign audio into English)
+*   `AISRT_WATCH=True` (Run 24/7 as a daemon)
+*   `AISRT_WATCH_INTERVAL_MINS=60` (Time between library scans)
+*   `AISRT_FILTERS__MIN_AGE_MINS=30` (Skip active torrent/usenet downloads)
+*   `AISRT_HARDWARE__FORCE_MODEL=large-v3-turbo`
+
+---
+
+## 🏗️ Open Source Development
+
+We welcome contributions! The codebase strictly adheres to enterprise-level typing and styling.
+
+**Development Setup:**
+```bash
+poetry install   # Or pip install -e ".[dev]"
+```
+
+**Running Tests & Linters:**
+```bash
+ruff check .           # Linter
+ruff format .          # Formatter
+mypy src/aisrt tests  # Strict Type Checking
+pytest tests           # Asynchronous Unit Tests
+```
+
+---
+
+## 📜 License
+Distributed under the MIT License. See `LICENSE` for more information.

aisrt-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "aisrt"
+version = "0.1.0"
+description = "Hardware-aware, concurrent pipeline for subtitle generation."
+authors = ["Arvind <arvind@example.com>"]
+readme = "README.md"
+packages = [{include = "aisrt", from = "src"}]
+
+[tool.poetry.scripts]
+aisrt = "aisrt.cli:app"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+typer = {extras = ["all"], version = "^0.9.0"}
+rich = "^13.7.0"
+loguru = "^0.7.2"
+pydantic = "^2.5.3"
+pydantic-settings = "^2.1.0"
+aiosqlite = "^0.19.0"
+psutil = "^5.9.8"
+pynvml = "^11.5.0"
+faster-whisper = "^1.0.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pytest-asyncio = "^0.23.5"
+ruff = "^0.2.0"
+mypy = "^1.8.0"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "C",  # flake8-comprehensions
+    "B",  # flake8-bugbear
+    "UP", # pyupgrade
+]
+ignore = []
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true

aisrt-0.1.0/src/aisrt/__init__.py

@@ -0,0 +1,3 @@
+"""Ultimate SRT Generator."""
+
+__version__ = "0.1.0"

aisrt-0.1.0/src/aisrt/assembly.py

@@ -0,0 +1,192 @@
+"""Broadcast-quality SubRip (SRT) formatting and Atomic File I/O."""
+
+import os
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+
+def _format_timestamp(seconds: float) -> str:
+    """Format a timestamp (in float seconds) to SRT standard: HH:MM:SS,mmm."""
+    hours = int(seconds // 3600)
+    minutes = int((seconds % 3600) // 60)
+    secs = int(seconds % 60)
+    millis = int(round((seconds - int(seconds)) * 1000))
+
+    if millis == 1000:
+        secs += 1
+        millis = 0
+        if secs == 60:
+            secs = 0
+            minutes += 1
+            if minutes == 60:
+                minutes = 0
+                hours += 1
+
+    return f"{hours:02d}:{minutes:02d}:{secs:02d},{millis:03d}"
+
+
+class SRTFormatter:
+    """Chunks Whisper words into broadcast-standard SRT format."""
+
+    def __init__(self, max_chars_per_line: int = 42, max_lines: int = 2) -> None:
+        """Initialize the SRT chunker.
+
+        Args:
+            max_chars_per_line: Maximum characters before wrapping a line.
+            max_lines: Maximum lines per subtitle block.
+        """
+        self.max_chars_per_line = max_chars_per_line
+        self.max_lines = max_lines
+        self.terminal_punctuation = {".", "?", "!", "。", "？", "！"}
+
+    def format_segments(self, segments: Any) -> str:
+        """Iterate over faster-whisper Segment/Word objects and yield SRT blocks.
+
+        Requires word_timestamps=True in the Whisper model transcribe() call.
+
+        Args:
+            segments: A generator of faster-whisper Segment objects.
+
+        Returns:
+            The complete SRT file content as a string.
+        """
+        self._srt_blocks: list[str] = []
+        self._block_idx = 1
+
+        for segment in segments:
+            if not getattr(segment, "words", None):
+                self._format_raw_segment(segment)
+            else:
+                self._format_word_segment(segment)
+
+        return "\n".join(self._srt_blocks)
+
+    def _format_raw_segment(self, segment: Any) -> None:
+        """Fallback formatter for segments without word timestamps."""
+        text = segment.text.strip()
+        if text:
+            start = _format_timestamp(segment.start)
+            end = _format_timestamp(segment.end)
+            self._srt_blocks.append(f"{self._block_idx}\n{start} --> {end}\n{text}\n")
+            self._block_idx += 1
+
+    def _format_word_segment(self, segment: Any) -> None:
+        """Advanced formatter that chunks based on character count and punctuation."""
+        current_words: list[str] = []
+        current_start: float | None = None
+        current_end: float = 0.0
+        char_count = 0
+        line_count = 1
+
+        for word_obj in segment.words:
+            word = word_obj.word.strip()
+            if not word:
+                continue
+
+            # Temporal gap check: flush if silence > 1.5s
+            if current_end > 0.0 and (word_obj.start - current_end) > 1.5:
+                if current_words and current_start is not None:
+                    self._flush_words(current_words, current_start, current_end)
+                    current_words = []
+                    current_start = None
+                    char_count = 0
+                    line_count = 1
+
+            if current_start is None:
+                current_start = word_obj.start
+
+            current_words.append(word_obj.word)
+            current_end = word_obj.end
+            char_count += len(word)
+
+            is_terminal = any(word.endswith(p) for p in self.terminal_punctuation)
+
+            # If appending this word exceeds the line length, wrap BEFORE adding it
+            if char_count > self.max_chars_per_line and line_count < self.max_lines:
+                # Insert newline before the current word
+                current_words.pop()  # Remove the word we just added
+                current_words.append("\n")
+                current_words.append(word_obj.word.lstrip())
+                char_count = len(word)
+                line_count += 1
+
+            is_too_long = char_count >= self.max_chars_per_line
+
+            if is_terminal or (is_too_long and line_count >= self.max_lines):
+                self._flush_words(current_words, current_start, current_end)
+                current_words = []
+                current_start = None
+                char_count = 0
+                line_count = 1
+
+        if current_words and current_start is not None:
+            self._flush_words(current_words, current_start, current_end)
+
+    def _flush_words(self, words: list[str], start_time: float, end_time: float) -> None:
+        """Write the aggregated words to the block list."""
+        text = "".join(words).strip()
+        if text:
+            start_str = _format_timestamp(start_time)
+            end_str = _format_timestamp(end_time)
+            self._srt_blocks.append(f"{self._block_idx}\n{start_str} --> {end_str}\n{text}\n")
+            self._block_idx += 1
+
+
+class AtomicWriter:
+    """Handles cross-device POSIX atomic file writing and metadata inheritance."""
+
+    @staticmethod
+    def write_srt(source_video: Path, srt_content: str, language_code: str = "en") -> Path:
+        """Write the SRT securely, inheriting the permissions of the source video.
+
+        Args:
+            source_video: The original MKV/MP4 file.
+            srt_content: The fully formatted SRT text block.
+            language_code: The locale suffix for the subtitle (e.g., 'en', 'eng').
+
+        Returns:
+            The Path to the finalized, atomically committed SRT file.
+        """
+        final_srt_path = source_video.with_suffix(f".{language_code}.srt")
+        temp_srt_path = source_video.with_name(f".{source_video.stem}.srt.tmp")
+
+        logger.debug(f"Assembling atomic SRT chunks in {temp_srt_path}")
+
+        try:
+            # 1. Write to hidden temp file in the same directory
+            temp_srt_path.write_text(srt_content, encoding="utf-8")
+
+            # 2. Inherit metadata from the source video
+            stat = source_video.stat()
+
+            try:
+                os.chown(temp_srt_path, stat.st_uid, stat.st_gid)
+            except PermissionError:
+                # Running as non-root over SMB/NFS might restrict chown
+                logger.debug(
+                    f"Insufficient permissions to chown {temp_srt_path} to "
+                    f"UID:{stat.st_uid}/GID:{stat.st_gid}. Proceeding anyway."
+                )
+
+            try:
+                os.chmod(temp_srt_path, stat.st_mode)
+            except PermissionError:
+                logger.debug(f"Insufficient permissions to chmod {temp_srt_path}")
+
+            # 3. Cross-device safe Atomic Rename
+            # os.replace is atomic on POSIX if both files are on the same filesystem.
+            # We write the temp file in the same folder to guarantee this and prevent EXDEV errors.
+            os.replace(temp_srt_path, final_srt_path)
+            logger.info(f"Successfully generated and committed {final_srt_path.name}")
+            return final_srt_path
+
+        except Exception as e:
+            # Clean up the temp file if the atomic commit fails
+            if temp_srt_path.exists():
+                try:
+                    temp_srt_path.unlink()
+                except OSError:
+                    pass
+            raise RuntimeError(f"Atomic subtitle write failed for {source_video.name}: {e}") from e