subgapfix 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

subgapfix/subgapfix.py

@@ -1,51 +1,163 @@
-import argparse
-import srt
-from datetime import timedelta
-
-def extend_subs(input_file, output_file, extend_sub_start=0.5, extend_sub_end=2.0, min_gap=1.0):
-    
-    if min_gap > extend_sub_start:
-
-        with open(input_file, "r", encoding="utf-8") as f:
-            subs = list(srt.parse(f.read()))
-
-        for i in range(len(subs) - 1):
-            first, second = subs[i], subs[i + 1]
-            gap = (second.start - first.end).total_seconds()
-            
-            if gap < min_gap:
-                first.end += timedelta(seconds=gap/2)
-                second.start -= timedelta(seconds=gap/2)
-
-            if gap >= min_gap:
-                extendable = gap - extend_sub_start
-                if extendable > 0:
-                    extension = min(extendable, extend_sub_end)
-                    first.end += timedelta(seconds=extension)
-                    second.start -= timedelta(seconds=extend_sub_start)
-
-            # Make sure subs don't overlap each other
-            if second.start <= first.end:
-                second.start = first.end + timedelta(milliseconds=10)
-
-        with open(output_file, "w", encoding="utf-8") as f:
-            f.write(srt.compose(subs))
-
-    else:
-        print("Hold up! The value of min_gap should be greater than that of extended_sub_start.")
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Extend subtitle durations when there is a gap before the next subtitle."
-    )
-    parser.add_argument("input", help="Input SRT file")
-    parser.add_argument("-o", "--output", default="subgapfix.srt", help="Output SRT file")
-    parser.add_argument("--extend-sub-start", "-ess", type=float, default=0.5, help="Seconds to add to start of subtitle. Default is: -ess 0.5")
-    parser.add_argument("--extend-sub-end", "-ese", type=float, default=2.0, help="Seconds to add to end of subtitle. Default is: -ese 2.0")
-    parser.add_argument("--min-gap", "-mg", type=float, default=1.0, help="Minimum gap (in seconds) required to apply extension. Default is: -mg 1.0")
-    args = parser.parse_args()
-
-    extend_subs(args.input, args.output, args.extend_sub_start, args.extend_sub_end, args.min_gap)
-
-if __name__ == "__main__":
-    main()
+from pathlib import Path
+import srt
+from datetime import timedelta
+import typer
+
+
+app = typer.Typer(
+    help="Extend subtitle display durations in gaps (better readability without overlaps).",
+    add_completion=True,
+)
+
+
+def validate_input_file(input_file: Path) -> None:
+    """Check if the input is a valid .srt file."""
+    if input_file.suffix.lower() != ".srt":
+        typer.secho(
+            f"Error: Input file must have .srt extension (got: {input_file.name})",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+
+
+def prepare_output_path(input_file: Path, output: Path | None) -> Path:
+    """Determine output path — use default if not provided."""
+    if output is None:
+        return input_file.with_stem(input_file.stem + "_fixed")
+    return output
+
+
+def validate_parameters(extend_start: float, min_gap: float, extend_final_sub: float) -> None:
+    """Ensure logical parameter constraints."""
+    if min_gap <= extend_start:
+        typer.secho(
+            f"Error: --min-gap ({min_gap}) must be > --extend-start ({extend_start})",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+    
+    if extend_final_sub < 0:
+        typer.secho(
+            f"Error: --extend-final-sub must be greater than or equal to 0",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+
+
+def load_subtitles(input_file: Path) -> list[srt.Subtitle]:
+    """Read and parse the SRT file."""
+    try:
+        content = input_file.read_text(encoding="utf-8")
+        return list(srt.parse(content))
+    except Exception as e:
+        typer.secho(f"Cannot parse SRT: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+
+def extend_gaps(
+    subs: list[srt.Subtitle],
+    extend_start: float,
+    extend_end_max: float,
+    min_gap: float,
+    extend_final_sub: float
+) -> int:
+    """Apply gap extension logic. Returns number of changed pairs."""
+    changes = 0
+
+    for i in range(len(subs) - 1):
+        a, b = subs[i], subs[i + 1]
+        gap = (b.start - a.end).total_seconds()
+
+        old_a_end = a.end
+        old_b_start = b.start
+
+        if gap < min_gap:
+            delta = gap / 2
+            a.end += timedelta(seconds=delta)
+            b.start -= timedelta(seconds=delta)
+        elif gap >= min_gap:
+            extendable = gap - extend_start
+            if extendable > 0:
+                extension = min(extendable, extend_end_max)
+                a.end += timedelta(seconds=extension)
+                b.start -= timedelta(seconds=extend_start)
+
+        # Prevent overlap / negative duration
+        if b.start <= a.end:
+            b.start = a.end + timedelta(milliseconds=10)
+
+        if a.end != old_a_end or b.start != old_b_start:
+            changes += 1
+
+    # Finally give the very last subtitle +1 second
+    if subs and extend_final_sub > 0:
+        last = subs[-1]
+        last.end += timedelta(seconds=extend_final_sub)
+        changes += 1
+
+    return changes
+
+
+@app.command()
+def main(
+    
+    input_file: Path = typer.Argument(..., exists=True, dir_okay=False),
+    
+    output: Path = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output file. Default: <input>_fixed.srt in same folder",
+    ),
+    
+    extend_start: float = typer.Option(
+        0.5, "--extend-sub-start", "-ess", help="Seconds to pull next sub backward"
+    ),
+    
+    extend_end_max: float = typer.Option(
+        2.0, "--extend-sub-end", "-ese", help="Max seconds to extend current sub forward"
+    ),
+    
+    min_gap: float = typer.Option(
+        1.0, "--min-gap", "-mg", help="Only extend when gap ≥ this value"
+    ),
+    
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show amount changes without writing"),
+    
+    extend_final_sub: float = typer.Option(
+        1.0,
+        "--extend-final-sub",
+        "-efs",
+        help="Seconds to add to the very last subtitle"
+    )
+):
+    
+    validate_input_file(input_file)
+
+    output_path = prepare_output_path(input_file, output)
+
+    if not dry_run:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    validate_parameters(extend_start, min_gap, extend_final_sub)
+
+    subs = load_subtitles(input_file)
+
+    changes = extend_gaps(subs, extend_start, extend_end_max, min_gap, extend_final_sub)
+
+    if dry_run:
+        typer.echo(f"The dry run ran succesfully and detected {changes} changes to subtitle pairs.")
+        return
+
+    output_path.write_text(srt.compose(subs), encoding="utf-8")
+    typer.secho(
+        f"Done. Wrote {len(subs)} subtitles → {output_path}",
+        fg=typer.colors.GREEN,
+    )
+
+
+if __name__ == "__main__":
+    app()

subgapfix-0.0.3.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: subgapfix
+Version: 0.0.3
+Summary: A small CLI tool to extend subtitle durations in SRT files to make them more readable on a screen.
+Author-email: Reinder Sinnema <reinder@w3bunker.com>
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: srt>=3.5.3
+Requires-Dist: typer>=0.21.1
+
+# SubGapFix
+
+[![PyPI version](https://img.shields.io/pypi/v/subgapfix.svg)](https://pypi.org/project/subgapfix/)
+[![Python versions](https://img.shields.io/pypi/pyversions/subgapfix.svg)](https://pypi.org/project/subgapfix/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**SubGapFix** is a lightweight CLI tool that makes subtitles easier and more comfortable to read by **intelligently extending their display duration** — especially useful for auto-generated subtitles.
+
+It works great with transcriptions from **[WhisperX](https://github.com/m-bain/whisperX)**.
+
+## ✨ Features
+
+- Extends subtitle display time when there is a **gap** before the next line
+- Safely prevents overlaps and negative durations
+- Dry-run mode to preview changes without writing files
+- Creates output folders automatically if needed
+- Only processes valid `.srt` files
+
+## 📦 Installation
+
+```bash
+pip install subgapfix
+```
+
+Requires Python 3.8+.
+
+Dependencies:
+- `typer` — beautiful CLI interface
+- `srt` — reliable SRT parsing
+
+## 🚀 Quick Start
+
+```bash
+# Basic usage — creates episode_fixed.srt in the same folder
+subgapfix episode.srt
+
+# Custom output file (creates folders if needed)
+subgapfix podcast/episode.srt -o podcast/enhanced/episode_subtitles.srt
+
+# Preview changes without modifying anything
+subgapfix input.srt --dry-run
+
+# Customize timings
+subgapfix input.srt --extend-sub-start 0.8 --extend-sub-end 3.0 --min-gap 1.5 --extend-final-sub 4.5
+```
+
+## ⚙️ All Options
+
+| Flag / Short | Default | Description |
+|--------------|---------|-------------|
+| `input_file` (positional) | — | Path to the input `.srt` file (must exist) |
+| `-o, --output` | `<input>_fixed.srt` | Output file path (folders auto-created) |
+| `--extend-sub-start`, `-ess` | `0.5` | Seconds to pull the **next** subtitle backward (tries to borrow from gap) |
+| `--extend-sub-end`, `-ese` | `2.0` | Maximum seconds to extend current subtitle forward into the gap |
+| `--min-gap`, `-mg` | `1.0` | Only apply extension if gap is at least this long (seconds) |
+| `--dry-run` | `false` | Show how many pairs would change — no file written |
+| `--extend-final-sub`, `-efs` | `1.0` | Number of seconds to add to the last subtitle |
+| `--help` | — | Show full help and exit |
+
+## How It Works
+
+1. Reads and validates the `.srt` file
+2. For each pair of consecutive subtitles:
+   - If gap < `--min-gap` → splits the gap evenly (closes small gaps)
+   - If gap ≥ `--min-gap` → extends current subtitle up to `--extend-end-max`, pulls next one back by `--extend-start`
+3. Prevents any overlap by enforcing a tiny 10 ms safety gap
+4. Add `--extend-final-sub` to the last subtitle for a precise ending
+5. Writes the result (or just reports changes in dry-run)
+
+**Before** (typical WhisperX-style tight timings):
+
+```
+1
+00:00:01,837 --> 00:00:02,502
+SubGapFix makes our lives
+
+2
+00:00:03,147 --> 00:00:03,571
+much easier.
+
+3
+00:00:04,176 --> 00:00:04,518
+Yes, I agree.
+```
+
+**After** (with defaults):
+
+```
+1
+00:00:01,837 --> 00:00:02,824
+SubGapFix makes our lives
+
+2
+00:00:02,834 --> 00:00:03,873
+much easier.
+
+3
+00:00:03,883 --> 00:00:04,679
+Yes, I agree.
+```
+
+## 💡 Why SubGapFix?
+
+Modern speech-to-text tools often prioritize transcription accuracy over comfortable reading speed.  
+Subtitles flash by too quickly → viewers miss text or feel rushed.
+
+SubGapFix **does not shift timings** or re-sync — it only **lengthens display time** using existing gaps.  
+This keeps perfect sync with the video while making subtitles far more readable.
+
+Perfect for lectures, interviews, conversations, podcasts.

subgapfix-0.0.3.dist-info/RECORD

@@ -0,0 +1,7 @@
+subgapfix/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+subgapfix/subgapfix.py,sha256=6Teg69GW88Y2MeegJA-YIm5pSiylGI1dFsULzgTE_EU,4709
+subgapfix-0.0.3.dist-info/METADATA,sha256=zK7agcIXqb6GYWUHPoIBJgOG6L3aveXCq4CaRxfYYGU,3999
+subgapfix-0.0.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+subgapfix-0.0.3.dist-info/entry_points.txt,sha256=JhP4WR6kiSkl8dE77M5WpByoX8deTaHUiTC-xdwl8t8,54
+subgapfix-0.0.3.dist-info/top_level.txt,sha256=1Kmf1LI51trmbRihayDZRnKSCfEQDR7jSyBELfkwTa8,10
+subgapfix-0.0.3.dist-info/RECORD,,

{subgapfix-0.0.2.dist-info → subgapfix-0.0.3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

subgapfix-0.0.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+subgapfix = subgapfix.subgapfix:app

subgapfix-0.0.2.dist-info/METADATA

@@ -1,91 +0,0 @@
-Metadata-Version: 2.4
-Name: subgapfix
-Version: 0.0.2
-Summary: A small CLI tool to extend subtitle durations in SRT files by redefining gaps between subtitles.
-Author-email: Reinder Sinnema <reinder@w3bunker.com>
-License: MIT
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-Requires-Dist: srt>=3.5.3
-
-# SubGapFix
-
-A small Python CLI tool to **extend subtitle durations** in `.srt` files so they stay on screen longer and feel more natural to read.  
-Designed especially for subtitles generated by [WhisperX](https://github.com/m-bain/whisperX), which often have very tight timings.
-
-## ✨ Features
-
-- Automatically extends subtitles when there’s a gap before the next subtitle.  
-- Prevents overlaps by adjusting start/end times safely.  
-- Configurable via CLI arguments.
-
-## 📦 Installation
-
-Install from PyPI:
-
-```bash
-pip install subgapfix
-````
-
-Dependencies used:
-
-* [`srt`](https://pypi.org/project/srt/)
-
-## 🔧 Usage
-
-Basic usage:
-
-```bash
-subgapfix input.srt -o easyreading.srt
-```
-
-### Options
-
-| Option                     | Default         | Description                                                               |
-|----------------------------|-----------------|---------------------------------------------------------------------------|
-| `-o, --output`             | `subgapfix.srt` | Output SRT file                                                           |
-| `--extend-sub-start, -ess` | `0.5`           | Seconds to add to start of subtitle. Default is `0.5`                     |
-| `--extend-sub-end, -ese`   | `2.0`           | Maximum seconds to add to end of subtitle. Default is `2.0`               |
-| `--min-gap, -mg`           | `1.0`           | Minimum gap (in seconds) required to apply extension. Default is `1.0`    |
-
-
-### How It Works
-
-The script reads your `.srt` file, loops through each pair of consecutive subtitles, and lengthens their timings (if applicable) to make them easier to read.  
-
-### Example
-
-Input:
-
-```
-1
-00:00:01,000 --> 00:00:03,000
-Hello there.
-
-2
-00:00:06,000 --> 00:00:08,000
-How are you?
-```
-
-Run:
-
-```bash
-subgapfix input.srt -o easyreading.srt
-```
-
-Output:
-
-```
-1
-00:00:01,000 --> 00:00:05,000
-Hello there.
-
-2
-00:00:05,500 --> 00:00:08,000
-How are you?
-```
-
-## 💡 Why?
-
-Tools like WhisperX produce accurate subtitles, but their timings are often too **tight** for comfortable reading.
-`subgapfix` helps subtitles stay visible longer while keeping synchronization intact.

subgapfix-0.0.2.dist-info/RECORD

@@ -1,7 +0,0 @@
-subgapfix/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-subgapfix/subgapfix.py,sha256=tDDn4cqL-jw9KfPK4tkVaxBLVh_ZZ53xWCwi6PWTbDo,2254
-subgapfix-0.0.2.dist-info/METADATA,sha256=C0B7C_vEXjkdh8-dP5kYqCCI9Y_XEEzS6k56HdU1Wyg,2459
-subgapfix-0.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-subgapfix-0.0.2.dist-info/entry_points.txt,sha256=2ln9RkMCsMtg0kFARJgoY7JKxBR4cEzxj4s-bKGCVUw,55
-subgapfix-0.0.2.dist-info/top_level.txt,sha256=1Kmf1LI51trmbRihayDZRnKSCfEQDR7jSyBELfkwTa8,10
-subgapfix-0.0.2.dist-info/RECORD,,

subgapfix-0.0.2.dist-info/entry_points.txt

@@ -1,2 +0,0 @@
-[console_scripts]
-subgapfix = subgapfix.subgapfix:main