subtitlemaker 0.1.0__py3-none-any.whl

subtitlemaker/config.py

@@ -0,0 +1,158 @@
+"""Configuration: defaults, config file loading and validation.
+
+Precedence, lowest to highest: built-in defaults, config file, command line.
+"""
+
+import os
+import sys
+from dataclasses import dataclass, fields, replace
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+
+class ConfigError(ValueError):
+    """Raised for an invalid config file or setting."""
+
+
+@dataclass(frozen=True)
+class SubtitleStyle:
+    """How subtitle cues are laid out and timed."""
+
+    max_line_length: int = 42  # Maximum characters per line
+    max_lines: int = 2  # Maximum number of lines
+    max_cps: float = 20.0  # Maximum characters per second
+    min_duration: float = 1.0  # Minimum subtitle duration (seconds)
+    max_duration: float = 7.0  # Maximum subtitle duration (seconds)
+    min_gap: float = 0.05  # Minimum gap between subtitles (seconds)
+
+    def __post_init__(self):
+        if not isinstance(self.max_line_length, int) or self.max_line_length < 1:
+            raise ConfigError("max_line_length must be an integer of at least 1")
+
+        if self.max_lines not in (1, 2):
+            raise ConfigError("max_lines must be 1 or 2")
+
+        for name in ("max_cps", "min_duration", "max_duration"):
+            if getattr(self, name) <= 0:
+                raise ConfigError(f"{name} must be greater than 0")
+
+        if self.min_gap < 0:
+            raise ConfigError("min_gap must not be negative")
+
+        if self.min_duration > self.max_duration:
+            raise ConfigError("min_duration must not be greater than max_duration")
+
+
+DEVICES = ("auto", "cuda", "cpu")
+
+
+@dataclass(frozen=True)
+class ModelConfig:
+    """
+    Which Whisper model to run, and how.
+
+    `name`, `device` and `compute_type` may be "auto", which is resolved
+    at run time from the hardware (see `transcribe.resolve_model_config`).
+    """
+
+    name: str = "auto"  # model size, Hugging Face repo id, or local path
+    device: str = "auto"  # auto, cuda or cpu
+    compute_type: str = "auto"  # e.g. float16, int8, int8_float16
+    vad_filter: bool = True
+    condition_on_previous_text: bool = True
+    word_timestamps: bool = True  # time cues from words, not whole segments
+
+    def __post_init__(self):
+        if self.device not in DEVICES:
+            raise ConfigError(f"device must be one of: {', '.join(DEVICES)}")
+
+        for name in ("name", "compute_type"):
+            if not getattr(self, name).strip():
+                raise ConfigError(f"{name} must not be empty")
+
+
+# Names accepted in each section of the config file.
+_SECTIONS = {
+    "style": SubtitleStyle,
+    "model": ModelConfig,
+}
+
+
+def default_config_path():
+    """Location of the user config file (respects XDG_CONFIG_HOME)."""
+
+    base = os.environ.get("XDG_CONFIG_HOME")
+    root = Path(base) if base else Path.home() / ".config"
+
+    return root / "subtitlemaker" / "config.toml"
+
+
+def load_config(path=None):
+    """
+    Load the config file and return `(SubtitleStyle, ModelConfig)`.
+
+    With `path=None` the default location is used and a missing file is
+    fine. An explicit `path` that does not exist is an error.
+    """
+
+    explicit = path is not None
+    path = Path(path) if explicit else default_config_path()
+
+    if not path.is_file():
+        if explicit:
+            raise ConfigError(f"config file not found: {path}")
+
+        return SubtitleStyle(), ModelConfig()
+
+    try:
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError(f"{path}: invalid TOML: {e}") from e
+
+    unknown_sections = sorted(set(data) - set(_SECTIONS))
+
+    if unknown_sections:
+        raise ConfigError(f"{path}: unknown section(s): {', '.join(unknown_sections)}")
+
+    built = {}
+
+    for section, cls in _SECTIONS.items():
+        values = data.get(section, {})
+        allowed = {f.name: f for f in fields(cls)}
+        unknown = sorted(set(values) - set(allowed))
+
+        if unknown:
+            raise ConfigError(
+                f"{path}: unknown key(s) in [{section}]: {', '.join(unknown)}"
+            )
+
+        defaults = cls()
+
+        for key, value in values.items():
+            expected = type(getattr(defaults, key))
+
+            # TOML integers are fine where a float is expected.
+            if expected is float and isinstance(value, int) and not isinstance(value, bool):
+                values[key] = float(value)
+
+            elif not isinstance(value, expected) or (
+                expected is int and isinstance(value, bool)
+            ):
+                raise ConfigError(
+                    f"{path}: [{section}] {key} must be {expected.__name__}, "
+                    f"got {type(value).__name__}"
+                )
+
+        try:
+            built[section] = replace(defaults, **values)
+
+        except ConfigError as e:
+            raise ConfigError(f"{path}: [{section}] {e}") from e
+
+    return built["style"], built["model"]

subtitlemaker/formats/__init__.py

@@ -0,0 +1,80 @@
+"""Subtitle output formats.
+
+A format is a name, a file extension and a function
+`write(cues, path)`, where each cue is a dict with `start` and `end` in
+seconds and `text` (lines separated by newlines).
+
+To add a format: write a module like `vtt.py` and register it below.
+"""
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from .srt import write_srt
+from .txt import write_txt
+from .vtt import write_vtt
+
+DEFAULT_FORMAT = "srt"
+
+
+@dataclass(frozen=True)
+class OutputFormat:
+    name: str
+    extension: str
+    write: Callable
+
+
+FORMATS = {
+    f.name: f
+    for f in (
+        OutputFormat("srt", "srt", write_srt),
+        OutputFormat("vtt", "vtt", write_vtt),
+        OutputFormat("txt", "txt", write_txt),
+    )
+}
+
+
+def parse_formats(value):
+    """
+    Parse a comma or space separated list of format names.
+
+    Returns the names in order without duplicates; an empty value gives the
+    default format. Raises ValueError for unknown names.
+    """
+
+    names = []
+
+    for name in re.split(r"[,\s]+", (value or "").strip().lower()):
+
+        if name and name not in names:
+            names.append(name)
+
+    unknown = [name for name in names if name not in FORMATS]
+
+    if unknown:
+        raise ValueError(
+            f"unknown output format(s): {', '.join(unknown)} "
+            f"(choose from: {', '.join(FORMATS)})"
+        )
+
+    return names or [DEFAULT_FORMAT]
+
+
+def output_path(base, name):
+    """
+    The file to write format `name` to, derived from `base`.
+
+    A known format extension on `base` is replaced; anything else (such as
+    the dots in `show.s01e01`) is kept and the extension is appended.
+    """
+
+    base = Path(base)
+    known = {"." + f.extension for f in FORMATS.values()}
+    extension = "." + FORMATS[name].extension
+
+    if base.suffix.lower() in known:
+        return base.with_suffix(extension)
+
+    return base.with_name(base.name + extension)

subtitlemaker/formats/_timestamp.py

@@ -0,0 +1,18 @@
+"""Timestamp formatting shared by the subtitle formats."""
+
+
+def format_timestamp(seconds, decimal):
+    """
+    Format seconds as `HH:MM:SS<decimal>mmm`.
+
+    SubRip uses a comma as the decimal separator and WebVTT a dot. Hours
+    are not capped at 23.
+    """
+
+    milliseconds = int(round(seconds * 1000))
+
+    hours, milliseconds = divmod(milliseconds, 3_600_000)
+    minutes, milliseconds = divmod(milliseconds, 60_000)
+    secs, milliseconds = divmod(milliseconds, 1000)
+
+    return f"{hours:02d}:{minutes:02d}:{secs:02d}{decimal}{milliseconds:03d}"

subtitlemaker/formats/srt.py

@@ -0,0 +1,27 @@
+"""SubRip (.srt) output."""
+
+from ._timestamp import format_timestamp
+
+
+def format_srt_time(seconds):
+    """Convert seconds to an SRT timestamp (`HH:MM:SS,mmm`)."""
+
+    return format_timestamp(seconds, ",")
+
+
+def write_srt(subtitles, path):
+    """Write subtitle cues to `path` as SRT."""
+
+    with open(path, "w", encoding="utf-8") as f:
+
+        for index, subtitle in enumerate(subtitles, start=1):
+
+            f.write(f"{index}\n")
+
+            f.write(
+                f"{format_srt_time(subtitle['start'])} "
+                f"--> "
+                f"{format_srt_time(subtitle['end'])}\n"
+            )
+
+            f.write(f"{subtitle['text']}\n\n")

subtitlemaker/formats/txt.py

@@ -0,0 +1,10 @@
+"""Plain text transcript output: one cue per line, no timing."""
+
+
+def write_txt(subtitles, path):
+    """Write the text of each cue to `path`, one cue per line."""
+
+    with open(path, "w", encoding="utf-8") as f:
+
+        for subtitle in subtitles:
+            f.write(subtitle["text"].replace("\n", " ") + "\n")

subtitlemaker/formats/vtt.py

@@ -0,0 +1,33 @@
+"""WebVTT (.vtt) output."""
+
+from ._timestamp import format_timestamp
+
+
+def format_vtt_time(seconds):
+    """Convert seconds to a WebVTT timestamp (`HH:MM:SS.mmm`)."""
+
+    return format_timestamp(seconds, ".")
+
+
+def _escape(text):
+    # In WebVTT cue text, & < > are markup. Escaping > also keeps a literal
+    # "-->" from being read as the start of a timing line.
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def write_vtt(subtitles, path):
+    """Write subtitle cues to `path` as WebVTT."""
+
+    with open(path, "w", encoding="utf-8") as f:
+
+        f.write("WEBVTT\n\n")
+
+        for subtitle in subtitles:
+
+            f.write(
+                f"{format_vtt_time(subtitle['start'])} "
+                f"--> "
+                f"{format_vtt_time(subtitle['end'])}\n"
+            )
+
+            f.write(f"{_escape(subtitle['text'])}\n\n")

subtitlemaker/log.py

@@ -0,0 +1,88 @@
+"""Logging setup: messages and progress share one stderr console."""
+
+import logging
+
+from rich.console import Console
+
+LOGGER_NAME = "subtitlemaker"
+
+
+class _Formatter(logging.Formatter):
+    """Plain messages, with a prefix for warnings and errors."""
+
+    def format(self, record):
+        message = record.getMessage()
+
+        # Other libraries often write their own "Warning:" prefix.
+        if message.lower().startswith(("warning:", "error:")):
+            return message
+
+        if record.levelno >= logging.ERROR:
+            return f"Error: {message}"
+
+        if record.levelno >= logging.WARNING:
+            return f"Warning: {message}"
+
+        return message
+
+
+class _ConsoleHandler(logging.Handler):
+    """
+    Print records through a `rich` console.
+
+    Going through the console keeps log lines and the live progress bar
+    from overwriting each other. Markup, highlighting and emoji codes are
+    off because file names may contain [brackets] or :colons:.
+    """
+
+    def __init__(self, console):
+        super().__init__()
+        self.console = console
+
+    def emit(self, record):
+        try:
+            self.console.print(
+                self.format(record),
+                markup=False,
+                highlight=False,
+                emoji=False,
+                soft_wrap=True,
+            )
+
+        except Exception:
+            self.handleError(record)
+
+
+def setup_logging(quiet=False, verbose=False):
+    """
+    Configure logging and return the shared `rich` console.
+
+    Normal runs show INFO and above, `quiet` shows only warnings and
+    errors, `verbose` adds DEBUG (including faster-whisper's own log).
+    """
+
+    console = Console(stderr=True)
+
+    handler = _ConsoleHandler(console)
+
+    handler.setFormatter(_Formatter())
+
+    root = logging.getLogger()
+    # Replace only our own handler from an earlier call, never other people's.
+    root.handlers[:] = [h for h in root.handlers if not isinstance(h, _ConsoleHandler)]
+    root.addHandler(handler)
+    root.setLevel(logging.WARNING)
+
+    if quiet:
+        level = logging.WARNING
+
+    elif verbose:
+        level = logging.DEBUG
+        logging.getLogger("faster_whisper").setLevel(logging.DEBUG)
+
+    else:
+        level = logging.INFO
+
+    logging.getLogger(LOGGER_NAME).setLevel(level)
+
+    return console

subtitlemaker/media.py

@@ -0,0 +1,55 @@
+"""Media file inspection."""
+
+import av
+
+
+def get_duration(filename):
+    """Get media duration using PyAV."""
+
+    container = av.open(filename)
+
+    try:
+
+        if container.duration is not None:
+            return container.duration / av.time_base
+
+        # Fallback
+        for stream in container.streams:
+
+            if (
+                stream.duration is not None
+                and stream.time_base is not None
+            ):
+                return float(
+                    stream.duration
+                    * stream.time_base
+                )
+
+        return 0.0
+
+    finally:
+        container.close()
+
+
+# Containers and codecs people commonly want subtitles for. Anything else
+# can still be given explicitly as a file; this only limits what is picked
+# up when a folder is scanned.
+MEDIA_EXTENSIONS = frozenset(
+    {
+        ".mp4", ".mkv", ".mov", ".avi", ".webm", ".m4v", ".ts", ".flv", ".wmv",
+        ".mpg", ".mpeg", ".3gp", ".mp3", ".m4a", ".aac", ".wav", ".flac", ".ogg",
+        ".oga", ".opus", ".wma", ".mka",
+    }
+)  # fmt: skip
+
+
+def find_media(directory, recursive=False):
+    """The media files in `directory`, sorted by path."""
+
+    candidates = directory.rglob("*") if recursive else directory.iterdir()
+
+    return sorted(
+        path
+        for path in candidates
+        if path.suffix.lower() in MEDIA_EXTENSIONS and path.is_file()
+    )

subtitlemaker/progress.py

@@ -0,0 +1,97 @@
+"""Time formatting and the live transcription progress display."""
+
+from rich.progress import BarColumn, Progress, ProgressColumn, TaskProgressColumn, TextColumn
+from rich.text import Text
+
+
+def format_time(seconds):
+    """Format seconds as HH:MM:SS."""
+
+    seconds = max(0, int(seconds))
+
+    hours = seconds // 3600
+    minutes = (seconds % 3600) // 60
+    secs = seconds % 60
+
+    return f"{hours:02d}:{minutes:02d}:{secs:02d}"
+
+
+class _PositionColumn(ProgressColumn):
+    """Media position, e.g. `00:00:06 / 00:01:00`."""
+
+    def render(self, task):
+        return Text(f"{format_time(task.completed)} / {format_time(task.total)}")
+
+
+class _SpeedColumn(ProgressColumn):
+    """Media seconds processed per real second, e.g. ` 7.4x`."""
+
+    def render(self, task):
+        elapsed = task.elapsed or 0
+
+        speed = task.completed / elapsed if elapsed > 0 else 0.0
+
+        return Text(f"{speed:4.1f}x")
+
+
+class _EtaColumn(ProgressColumn):
+    """Estimated real time remaining, based on the average speed so far."""
+
+    def render(self, task):
+        elapsed = task.elapsed or 0
+
+        speed = task.completed / elapsed if elapsed > 0 else 0.0
+
+        if speed > 0 and task.total > task.completed:
+            eta = (task.total - task.completed) / speed
+
+        else:
+            eta = 0
+
+        return Text(f"ETA {format_time(eta)}")
+
+
+class TranscriptionProgress:
+    """
+    Context manager showing transcription progress.
+
+        with TranscriptionProgress(duration, console) as progress:
+            progress.update(seconds_processed)
+
+    With `enabled=False` (or an unknown duration) it does nothing.
+    """
+
+    def __init__(self, total, console, enabled=True):
+        self._total = float(total)
+        self._enabled = bool(enabled and total)
+
+        self._progress = Progress(
+            TextColumn("Transcribing"),
+            BarColumn(bar_width=30),
+            TaskProgressColumn(),
+            _PositionColumn(),
+            _SpeedColumn(),
+            _EtaColumn(),
+            console=console,
+            disable=not self._enabled,
+        )
+
+        self._task = None
+
+    def __enter__(self):
+        self._progress.start()
+        self._task = self._progress.add_task("", total=self._total)
+
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self._progress.stop()
+
+    def update(self, processed):
+        """Report that `processed` seconds of media are done."""
+
+        if self._enabled:
+            self._progress.update(
+                self._task,
+                completed=min(float(processed), self._total),
+            )