subtitlemaker 0.1.0__tar.gz

subtitlemaker-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  # Keeps the pinned versions of the actions used by the workflows current.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      actions:
+        patterns: ["*"]

subtitlemaker-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --locked
+      - name: Lint
+        run: uv run ruff check src tests
+      - name: Test
+        run: uv run pytest
+
+  # The lowest versions the package claims to support still have to work.
+  lowest-versions:
+    name: Lowest supported dependencies
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          python-version: "3.10"
+          enable-cache: true
+      - run: uv run --resolution lowest-direct pytest
+
+  # Runs a real (tiny) Whisper model on the CPU.
+  integration:
+    name: Integration (tiny model)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - uses: actions/cache@v6
+        with:
+          path: ~/.cache/huggingface
+          key: huggingface-whisper-tiny-v1
+      - run: uv sync --locked
+      - run: uv run pytest -m integration
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - name: Check the package metadata
+        run: uvx twine check --strict dist/*

subtitlemaker-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: Publish
+
+# Pushing a tag like v0.1.0 builds the package and publishes it to PyPI.
+# "Run workflow" on the Actions tab builds and checks it without publishing.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          python-version: "3.12"
+      - name: The tag must match the package version
+        if: github.ref_type == 'tag'
+        run: |
+          version=$(uv run --no-project python -c "import re; print(re.search(r'__version__ = \"(.+?)\"', open('src/subtitlemaker/__init__.py').read()).group(1))")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match version $version in src/subtitlemaker/__init__.py"
+            exit 1
+          fi
+      - run: uv sync --locked
+      - run: uv run ruff check src tests
+      - run: uv run pytest
+      - run: uv build
+      - name: Check the package metadata
+        run: uvx twine check --strict dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/subtitlemaker
+    permissions:
+      id-token: write # trusted publishing: PyPI trusts this workflow, no token needed
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

subtitlemaker-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Local test media and generated subtitles
+*.srt
+*.vtt
+*.mp4
+*.mkv
+*.mp3
+*.wav
+*.m4a
+!tests/fixtures/**
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

subtitlemaker-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

subtitlemaker-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-07
+
+First public release. It grew out of a single prototype script.
+
+### Added
+- Subtitle output as SRT, WebVTT and plain text (`-f srt,vtt,txt`).
+- Batch mode: several files and folders (`-r` to recurse), `--output-dir`, `--skip-existing`. The model is loaded once, and a file that fails does not stop the others.
+- CPU support. `--device auto|cuda|cpu` falls back to the CPU when no usable GPU is found, with a warning.
+- `--model` to choose the Whisper model (size, Hugging Face repo id or local path) and `--compute-type`. The default is `large-v3` on a GPU and `small` on the CPU.
+- Word timestamps (`--word-timestamps`, on by default): subtitles start at the first word and end at the last, and long sentences are split at sentence ends and real word times.
+- Subtitle style options (`--max-line-length`, `--max-lines`, `--max-cps`, `--min-duration`, `--max-duration`, `--min-gap`) and a TOML config file.
+- `--quiet` and `--verbose`, `--version`, and a progress bar. Messages go to stderr.
+- Optional `cuda` extra that installs the CUDA 12 libraries from PyPI.
+
+### Changed
+- The default task is `transcribe` (subtitles in the spoken language). The prototype translated to English by default; use `-t translate` for that.
+- Subtitles are no longer shifted later to make room for readability padding. Padding only extends a subtitle into free time.
+- `--max-lines` accepts 1 or 2.
+
+### Fixed
+- A line could be one character longer than the maximum.
+- The first subtitle was delayed by the minimum gap.
+- The GPU libraries are loaded without re-launching the Python process, so `python -m subtitlemaker` works.
+- A GPU without the CUDA 12 libraries no longer ends in a traceback in the middle of a run.
+
+[Unreleased]: https://github.com/CodeByVibes/subtitlemaker/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/CodeByVibes/subtitlemaker/releases/tag/v0.1.0

subtitlemaker-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing
+
+Thanks for wanting to help. Bug reports, ideas and pull requests are all welcome.
+
+## Reporting a problem
+
+Please include:
+
+- what you ran (the full command) and what you expected,
+- the output, ideally with `-v` for debug messages,
+- your OS, Python version and `subtitlemaker --version`,
+- whether it was on the GPU or the CPU.
+
+If a particular file triggers the problem and it is short and shareable, attach it. Otherwise a description of it (length, languages, container) helps.
+
+## Setting up
+
+You need Python 3.10 or newer and [uv](https://docs.astral.sh/uv/).
+
+```console
+git clone https://github.com/CodeByVibes/subtitlemaker.git
+cd subtitlemaker
+uv sync                 # add --extra cuda for NVIDIA GPU support
+uv run subtitlemaker --help
+```
+
+## Checks
+
+```console
+uv run ruff check src tests     # lint
+uv run pytest                   # unit, snapshot and pipeline tests: fast, no GPU or model needed
+uv run pytest -m integration    # runs the real "tiny" model on a short clip (downloads 73 MB once)
+```
+
+CI runs the lint and the fast tests on Python 3.10 to 3.13, and the integration tests once. Please make sure these pass before opening a pull request.
+
+The code style is plain and spacious. Run `ruff check`, but do not run `ruff format` over `src/`, it would rewrite the whole code base.
+
+## How the code is organised
+
+| Module             | Responsibility                                                    |
+| ------------------ | ----------------------------------------------------------------- |
+| `cli.py`           | Arguments, batch handling, the per-file steps.                    |
+| `config.py`        | `SubtitleStyle` and `ModelConfig`, config file loading, validation. |
+| `transcribe.py`    | Choosing and loading the model, GPU/CPU fallback, languages.      |
+| `_cuda.py`         | Loading the pip-installed CUDA libraries.                         |
+| `segmenter.py`     | Whisper segments to subtitle cues. **Pure logic**: no printing, files or model. |
+| `formats/`         | Output writers (`srt`, `vtt`, `txt`) and the registry.            |
+| `media.py`         | Reading durations, finding media files in folders.                |
+| `progress.py`, `log.py` | The progress bar and logging.                                |
+
+Keep `segmenter.py` free of I/O. That is what makes the subtitle behaviour testable without a model.
+
+### Adding an output format
+
+1. Write `formats/yourformat.py` with a `write_yourformat(cues, path)` function. A cue is a dict with `start` and `end` (seconds) and `text` (lines separated by `\n`).
+2. Register it in `formats/__init__.py`.
+3. Add tests next to the ones in `tests/test_output_formats.py`. If the format has an external specification, check a generated file with an independent tool (we use `ffmpeg` for SRT and VTT).
+
+### Changing subtitle behaviour
+
+Timing and splitting changes show up in the snapshot tests. If a change is intended, regenerate the stored files, read the diff, and explain it in the pull request:
+
+```console
+UPDATE_SNAPSHOTS=1 uv run pytest tests/test_snapshot.py
+git diff tests/fixtures
+```
+
+## Tests
+
+- Test behaviour, not implementation. The existing tests build "segments" by hand (`tests/conftest.py`) and run them through the real code.
+- `tests/conftest.py` has a fake Whisper model (`fake_model`) and a `run(...)` helper so the whole command line can be tested without a GPU.
+- A test that has never failed is a test you don't know works. When you fix a bug, write the test first and watch it fail.
+
+## Commits and pull requests
+
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `build:`, `chore:`. Keep each commit to one logical change, and add a line to `CHANGELOG.md` under "Unreleased" for anything a user would notice.
+
+## Releasing (maintainers)
+
+1. Move the "Unreleased" entries in `CHANGELOG.md` under a new version heading with the date.
+2. Set the version in `src/subtitlemaker/__init__.py` (it is the single source for the package version).
+3. Commit, then tag: `git tag v0.2.0 && git push origin main v0.2.0`.
+4. The `Publish` workflow builds the package, checks the tag matches the version, runs the tests and uploads to PyPI with trusted publishing. No tokens are stored anywhere.

subtitlemaker-0.1.0/LICENSE

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

subtitlemaker-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.5
+Name: subtitlemaker
+Version: 0.1.0
+Summary: Generate subtitles from audio and video files using faster-whisper.
+Project-URL: Homepage, https://github.com/CodeByVibes/subtitlemaker
+Project-URL: Issues, https://github.com/CodeByVibes/subtitlemaker/issues
+Project-URL: Changelog, https://github.com/CodeByVibes/subtitlemaker/blob/main/CHANGELOG.md
+Author-email: Johan Isevind <codebyvibes@isevind.se>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: faster-whisper,speech-to-text,srt,subtitles,transcription,vtt,whisper
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Requires-Dist: av<17,>=13
+Requires-Dist: faster-whisper>=1.2.1
+Requires-Dist: rich>=13
+Requires-Dist: tomli>=2; python_version < '3.11'
+Provides-Extra: cuda
+Requires-Dist: nvidia-cublas-cu12; extra == 'cuda'
+Requires-Dist: nvidia-cudnn-cu12==9.*; extra == 'cuda'
+Description-Content-Type: text/markdown
+
+# SubtitleMaker
+
+[![CI](https://github.com/CodeByVibes/subtitlemaker/actions/workflows/ci.yml/badge.svg)](https://github.com/CodeByVibes/subtitlemaker/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Generate subtitles from audio and video files with [faster-whisper](https://github.com/SYSTRAN/faster-whisper).
+It runs locally, on a GPU if you have one and on the CPU if you don't.
+
+```console
+$ subtitlemaker interview.mkv
+$ ls
+interview.mkv  interview.srt
+```
+
+- **SRT, WebVTT and plain text** output, any combination in one run.
+- **Subtitles that follow the speech.** Cues start at the first word and end at the last, using word timestamps, and long sentences are split at sentence ends where possible.
+- **Readable by default:** at most two lines of 42 characters, 20 characters per second, 1 to 7 seconds on screen. All of it is configurable.
+- **Batch mode:** pass many files or whole folders; the model is loaded once and one bad file doesn't stop the rest.
+- **GPU or CPU.** `--device auto` uses an NVIDIA GPU when there is one and falls back to the CPU when there isn't.
+- **Mixed-language audio** (`-l en,sv`), and optional translation to English (`-t translate`).
+
+## Install
+
+You need Python 3.10 to 3.13. FFmpeg is **not** required.
+
+SubtitleMaker is a command line tool, so [pipx](https://pipx.pypa.io/) or [uv](https://docs.astral.sh/uv/) is the easiest way to install it:
+
+```console
+# CPU only
+pipx install subtitlemaker
+
+# NVIDIA GPU (also installs the CUDA 12 libraries, see below)
+pipx install "subtitlemaker[cuda]"
+```
+
+With uv: `uv tool install subtitlemaker` or `uv tool install "subtitlemaker[cuda]"`. Plain `pip install` works too, ideally inside a virtual environment.
+
+> **Platforms:** developed and tested on Linux. It should work on macOS and Windows on the CPU, but that has not been tested yet. GPU support is only set up for Linux.
+
+### The first run downloads a model
+
+Whisper models are downloaded from Hugging Face the first time you use them and cached afterwards (`~/.cache/huggingface`, or wherever `HF_HOME` points). Sizes of the model files:
+
+| `--model`    | Download | Notes                                          |
+| ------------ | -------- | ---------------------------------------------- |
+| `tiny`       | 73 MB    | Fast, rough. Good for trying things out.       |
+| `small`      | 462 MB   | **Default on CPU.**                            |
+| `turbo`      | 1.6 GB   | Close to `large-v3` quality, much faster.      |
+| `large-v3`   | 2.9 GB   | **Default on GPU.** Most accurate.             |
+
+`base`, `medium`, the `.en` variants, `distil-*` models, any Hugging Face repo id such as `user/model`, and local paths to converted models also work.
+
+## Usage
+
+```console
+# Subtitles next to the file, in the spoken language
+subtitlemaker talk.mp4
+
+# Several formats at once: talk.srt, talk.vtt and talk.txt
+subtitlemaker talk.mp4 -f srt,vtt,txt
+
+# English subtitles for foreign-language audio
+subtitlemaker film.mkv -t translate
+
+# Tell it the language instead of detecting it
+subtitlemaker film.mkv -l sv
+
+# A whole folder (add -r for sub folders), skipping files that are already done
+subtitlemaker ~/Videos --skip-existing -r
+
+# Put all the results in one place
+subtitlemaker ~/Videos/*.mp4 -d ~/subtitles -f srt,vtt
+
+# Smaller and faster, CPU only
+subtitlemaker talk.mp4 --device cpu --model tiny
+```
+
+Run `subtitlemaker --help` for every option.
+
+### Output
+
+| Format | Contents                                                                         |
+| ------ | -------------------------------------------------------------------------------- |
+| `srt`  | SubRip, the most widely supported. This is the default.                          |
+| `vtt`  | WebVTT, for web players. Markup characters in the text are escaped.              |
+| `txt`  | The text only, one subtitle per line, no timing.                                 |
+
+Files are written next to each input and named after it (`talk.mp4` becomes `talk.srt`). Existing files are overwritten unless you pass `--skip-existing`.
+
+- `-o FILE` names the output for a single input. With several formats it is a base name and the extension is replaced for each one.
+- `-d DIR` writes all outputs into one folder (created if needed). Two inputs that would write the same file are refused before anything runs.
+
+The exit code is `0` when everything succeeded, `1` if any file failed (the others are still processed), and `2` for invalid options.
+
+### Languages
+
+By default Whisper detects the language from the start of each file. If it guesses wrong, or the start is music, name the language with `-l`.
+
+For audio that switches language, list the languages (`-l en,sv`) or add `-m`. The language is then re-detected for every segment. Be aware that `-t translate` turns every segment into English.
+
+### Subtitle style
+
+| Option              | Default | Meaning                                              |
+| ------------------- | ------- | ---------------------------------------------------- |
+| `--max-line-length` | 42      | Maximum characters per line.                         |
+| `--max-lines`       | 2       | Lines per subtitle, 1 or 2.                          |
+| `--max-cps`         | 20      | Reading speed: characters per second.                |
+| `--min-duration`    | 1.0     | Shortest time a subtitle stays on screen (seconds).  |
+| `--max-duration`    | 7.0     | Longest time a subtitle stays on screen (seconds).   |
+| `--min-gap`         | 0.05    | Smallest gap between two subtitles (seconds).        |
+
+Timing follows the speech. A subtitle appears when its first word is spoken. If it would be too short or too quick to read, it is held longer, but only into free time: it never delays or overlaps the next subtitle. If two lines are spoken too close together, the first one is allowed to be shorter than `--min-duration`.
+
+### Config file
+
+Options you always use can go in `~/.config/subtitlemaker/config.toml` (or `$XDG_CONFIG_HOME/subtitlemaker/config.toml`), or in a file given with `--config`. Command line options override the file, and the file overrides the defaults.
+
+```toml
+[style]
+max_line_length = 38
+max_lines = 2
+max_cps = 17
+min_duration = 1.0
+max_duration = 6.0
+min_gap = 0.05
+
+[model]
+name = "turbo"            # auto, a size, a Hugging Face repo id or a path
+device = "auto"           # auto, cuda or cpu
+compute_type = "auto"     # auto, float16, int8_float16, int8, float32, ...
+word_timestamps = true
+vad_filter = true
+condition_on_previous_text = true
+```
+
+Unknown keys and wrong types are reported with the file name, so typos don't pass silently.
+
+## GPU and CPU
+
+`--device auto` (the default) picks the GPU when CTranslate2 can see one and warns and uses the CPU otherwise.
+
+| Where | Default model | Precision | Notes                                               |
+| ----- | ------------- | --------- | --------------------------------------------------- |
+| GPU   | `large-v3`    | `float16` | Needs an NVIDIA GPU, a current driver and CUDA 12 libraries. |
+| CPU   | `small`       | `int8`    | Works everywhere, much slower than a GPU.           |
+
+For a rough idea, on one machine (RTX 4070 Laptop GPU, 24 CPU cores) a two minute clip took about 7 seconds with `large-v3` on the GPU and about 9 seconds with `small` on the CPU. Your results will differ.
+
+### CUDA libraries
+
+CTranslate2 needs the CUDA 12 versions of cuBLAS and cuDNN 9. Install SubtitleMaker with the `cuda` extra and they come from PyPI (`nvidia-cublas-cu12`, `nvidia-cudnn-cu12`) and are loaded automatically, so a different system-wide CUDA version doesn't matter. These packages are licensed by NVIDIA, not under this project's license, and they are large.
+
+If the GPU can't be used, `--device auto` falls back to the CPU and tells you why. With an explicit `--device cuda` it stops with an error that says what is missing.
+
+## How it works
+
+1. faster-whisper transcribes the audio with word timestamps (voice activity detection is on, so stretches without speech are skipped).
+2. Words are grouped into subtitles that fit the line limits, preferably breaking at the end of a sentence.
+3. Timing is adjusted for readability without moving speech, as described above.
+4. The result is written in each requested format.
+
+## Limitations
+
+- At most two lines per subtitle.
+- Lines are wrapped at spaces, so languages written without spaces (Chinese, Japanese, Thai) are not wrapped well. This is untested.
+- Speakers are not identified, and no sound descriptions like `[music]` are added.
+- A long pause in the middle of a sentence does not split the subtitle yet.
+
+## Contributing
+
+Bug reports and pull requests are welcome, see [CONTRIBUTING.md](CONTRIBUTING.md). Changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE). SubtitleMaker builds on [faster-whisper](https://github.com/SYSTRAN/faster-whisper) (MIT), [CTranslate2](https://github.com/OpenNMT/CTranslate2) (MIT) and OpenAI's [Whisper](https://github.com/openai/whisper) models (MIT).