termview 0.1.0__py3-none-any.whl

termview/__init__.py

@@ -0,0 +1,55 @@
+"""
+termview — view images, animations, and videos in the terminal.
+
+Public API:
+
+    from termview import detect_renderer, get_renderer, fit_image, load_image
+    from termview import stream_video, stream_animation
+
+Most users want the `tv` CLI command rather than the library API.
+"""
+
+from .audio import AudioPlayer, is_available as audio_available
+from .controls import Key, read_key
+from .detect import (
+    ColorDepth,
+    RendererType,
+    detect_color_depth,
+    detect_environment,
+    detect_renderer,
+    terminal_size,
+)
+from .loader import (
+    is_animated,
+    is_image,
+    is_video,
+    iter_frames,
+    load_image,
+)
+from .renderers import get_renderer
+from .resize import fit_image
+from .stream import stream_animation, stream_video
+from .terminal import TerminalState
+
+__all__ = [
+    "AudioPlayer",
+    "ColorDepth",
+    "Key",
+    "RendererType",
+    "TerminalState",
+    "audio_available",
+    "detect_color_depth",
+    "detect_environment",
+    "detect_renderer",
+    "fit_image",
+    "get_renderer",
+    "is_animated",
+    "is_image",
+    "is_video",
+    "iter_frames",
+    "load_image",
+    "read_key",
+    "stream_animation",
+    "stream_video",
+    "terminal_size",
+]

termview/audio.py

@@ -0,0 +1,141 @@
+"""
+Audio playback for video files via an external subprocess.
+
+We do *not* decode or mix audio in-process — that would require either PyAV
+(50 MB+ C extension) or PyAudio + manual A/V sync, both of which are vastly
+more complex than the actual problem.  Instead we shell out to the first
+available audio player on the system:
+
+    ffplay      — cross-platform, ships with ffmpeg, handles every format
+    afplay      — built into macOS, handles mp3/m4a/wav but not raw video
+    paplay      — Linux PulseAudio, handles wav only
+
+ffplay is the only one that decodes audio out of arbitrary video containers,
+so it's the one we actively support.  The others are documented fallbacks for
+when the user has audio files (.mp3 etc.) rather than video.
+
+Sync model
+----------
+We don't try to read the audio process's clock.  Instead:
+  - audio subprocess is started at wall-clock T₀ and paces itself.
+  - the video render loop also derives its target frame time from T₀.
+  - both run off the same origin → drift is bounded by the audio player's
+    internal A/V skew correction (ffplay's is good for hours of playback).
+
+Pause / seek invalidate the audio subprocess and we respawn at the new
+position with `-ss <seconds>`.  Spawn latency is ~250ms, accepted as the
+cost of audio sync.
+"""
+
+import os
+import shutil
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _find_player() -> str | None:
+    """Return the path to ffplay if installed, else None."""
+    return shutil.which("ffplay")
+
+
+def is_available() -> bool:
+    return _find_player() is not None
+
+
+def install_hint() -> str:
+    if sys.platform == "darwin":
+        return "Install with:  brew install ffmpeg"
+    if sys.platform.startswith("linux"):
+        return "Install with:  apt install ffmpeg   (or your distro's equivalent)"
+    return "Install ffmpeg from https://ffmpeg.org/download.html"
+
+
+class AudioPlayer:
+    """
+    Wraps an ffplay subprocess. Each method is best-effort — audio is a
+    nice-to-have; failures must never crash video playback.
+    """
+
+    def __init__(self, path: Path, volume: int = 100) -> None:
+        self.path = path
+        self.volume = max(0, min(100, volume))
+        self.muted = False
+        self._proc: subprocess.Popen | None = None
+        self._start_offset: float = 0.0  # seconds into the file
+        self._player = _find_player()
+
+    @property
+    def available(self) -> bool:
+        return self._player is not None
+
+    # ------------------------------------------------------------------ control
+
+    def start(self, position_sec: float = 0.0) -> None:
+        """Start (or restart) audio at the given position."""
+        if not self.available:
+            return
+        self.stop()
+        self._start_offset = max(0.0, position_sec)
+
+        vol = 0 if self.muted else self.volume
+        cmd = [
+            self._player,
+            "-nodisp",                # no video window
+            "-autoexit",              # die when file ends
+            "-loglevel", "quiet",
+            "-volume", str(vol),
+            "-ss", f"{self._start_offset:.3f}",
+            str(self.path),
+        ]
+        try:
+            self._proc = subprocess.Popen(
+                cmd,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                # New process group so SIGINT to our terminal doesn't reach it
+                # before we get a chance to cleanly SIGTERM.
+                start_new_session=True,
+            )
+        except (OSError, FileNotFoundError):
+            self._proc = None
+
+    def stop(self) -> None:
+        """Terminate the audio subprocess if running.  Idempotent."""
+        if self._proc is None:
+            return
+        try:
+            if self._proc.poll() is None:
+                # SIGTERM gives ffplay a chance to close its audio device cleanly,
+                # which avoids the "audio drop-out into next thing you play"
+                # CoreAudio bug on macOS.
+                os.killpg(os.getpgid(self._proc.pid), signal.SIGTERM)
+                try:
+                    self._proc.wait(timeout=0.5)
+                except subprocess.TimeoutExpired:
+                    os.killpg(os.getpgid(self._proc.pid), signal.SIGKILL)
+        except (ProcessLookupError, PermissionError, OSError):
+            pass
+        finally:
+            self._proc = None
+
+    def toggle_mute(self) -> bool:
+        """Toggle mute. Returns new muted state.  Requires respawn."""
+        self.muted = not self.muted
+        return self.muted
+
+    def set_volume(self, vol: int) -> None:
+        self.volume = max(0, min(100, vol))
+
+    def is_running(self) -> bool:
+        return self._proc is not None and self._proc.poll() is None
+
+    # ------------------------------------------------------------------ context
+
+    def __enter__(self) -> "AudioPlayer":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.stop()

termview/cli.py

@@ -0,0 +1,215 @@
+"""
+Command-line entry point for `tv`.
+
+Responsibilities:
+  - parse arguments
+  - dispatch to the appropriate playback path (image / animation / video)
+  - handle stdout-not-a-TTY and broken-pipe scenarios cleanly
+  - keep the actual rendering / playback logic out of this file
+"""
+
+import argparse
+import errno
+import sys
+from pathlib import Path
+
+from .detect import (
+    ColorDepth,
+    RendererType,
+    detect_color_depth,
+    detect_environment,
+    detect_renderer,
+    terminal_size,
+)
+from .loader import is_animated, is_image, is_video, load_image
+from .renderers import get_renderer
+from .resize import fit_image
+from .stream import stream_animation, stream_video
+
+_MIN_COLS = 20
+_MIN_ROWS = 8
+
+
+def main() -> None:
+    try:
+        _main()
+    except BrokenPipeError:
+        # Piped output closed before we finished writing (e.g. `tv x.png | head`).
+        # Suppress and exit cleanly so we don't dump a traceback.
+        try:
+            sys.stdout.close()
+        except Exception:
+            pass
+        sys.exit(0)
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+def _main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    path: Path = args.file
+    if not path.exists():
+        parser.error(f"{path}: no such file or directory")
+
+    renderer_type = detect_renderer(args.renderer)
+    color_depth = detect_color_depth(args.depth)
+    cols, rows = terminal_size()
+    if args.width:
+        cols = args.width
+
+    env = detect_environment()
+
+    # Refuse to draw graphics into a non-TTY stdout — we'd corrupt whatever
+    # file or pipe the user redirected to with cursor/clear escapes.  Allow
+    # `--renderer block` + image to still work if user is piping (it's just
+    # text), but disable cursor sequences in that case.
+    if not env["tty_stdout"] and is_video(path):
+        parser.error("video playback requires stdout to be a terminal")
+
+    if args.verbose:
+        _print_diagnostics(renderer_type, color_depth, cols, rows, env)
+
+    # Tiny-terminal guard.
+    if cols < _MIN_COLS or rows < _MIN_ROWS:
+        sys.stderr.write(
+            f"tv: terminal too small ({cols}x{rows}); "
+            f"need at least {_MIN_COLS}x{_MIN_ROWS}.\n"
+        )
+        sys.exit(2)
+
+    if is_image(path):
+        img = load_image(path)
+        if is_animated(img):
+            stream_animation(
+                img,
+                renderer_type,
+                color_depth=color_depth,
+                enable_controls=not args.no_controls,
+                loop=args.loop,
+            )
+        else:
+            _display_image(img, renderer_type, color_depth, cols, rows, args)
+    elif is_video(path):
+        stream_video(
+            path,
+            renderer_type,
+            color_depth=color_depth,
+            fps_limit=args.fps,
+            enable_audio=not args.no_audio,
+            enable_controls=not args.no_controls,
+            verbose=args.verbose,
+        )
+    else:
+        parser.error(f"{path}: unsupported file type")
+
+
+def _display_image(img, renderer_type, color_depth, cols, rows, args) -> None:
+    original_size = img.size
+    fitted = fit_image(img, cols, rows, renderer_type, crop=not args.no_crop)
+    if args.verbose:
+        print(
+            f"[tv] image {original_size[0]}x{original_size[1]} "
+            f"-> render {fitted.size[0]}x{fitted.size[1]}",
+            file=sys.stderr,
+        )
+    renderer = get_renderer(renderer_type, color_depth=color_depth)
+    renderer.display(fitted)
+
+
+def _print_diagnostics(renderer_type, color_depth, cols, rows, env) -> None:
+    parts = [
+        f"renderer={renderer_type.value}",
+        f"color={color_depth.value}",
+        f"terminal={cols}x{rows}",
+    ]
+    if env["tmux"]:
+        parts.append("tmux=yes")
+    if env["ssh"]:
+        parts.append("ssh=yes")
+    print(f"[tv] {' '.join(parts)}", file=sys.stderr)
+
+
+# ---------------------------------------------------------------------- argparse
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="tv",
+        description="View images, animations, and videos in the terminal.",
+        epilog=_CONTROLS_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("file", type=Path, help="Image, animated GIF, or video file")
+
+    g_render = p.add_argument_group("rendering")
+    g_render.add_argument(
+        "--renderer",
+        choices=[r.value for r in RendererType],
+        metavar="NAME",
+        help="Force renderer: kitty | iterm2 | sixel | block (default: auto)",
+    )
+    g_render.add_argument(
+        "--depth",
+        choices=["truecolor", "256"],
+        metavar="DEPTH",
+        help="Force color depth (default: auto)",
+    )
+    g_render.add_argument(
+        "--width",
+        type=int,
+        metavar="COLS",
+        help="Override terminal width in columns",
+    )
+    g_render.add_argument(
+        "--no-crop",
+        action="store_true",
+        help="Disable automatic border cropping (still images only)",
+    )
+
+    g_video = p.add_argument_group("video / animation")
+    g_video.add_argument(
+        "--fps",
+        type=float,
+        metavar="N",
+        help="Limit playback frame rate (default: auto; 12 on 256-color)",
+    )
+    g_video.add_argument(
+        "--no-audio",
+        action="store_true",
+        help="Disable audio playback (video only)",
+    )
+    g_video.add_argument(
+        "--no-controls",
+        action="store_true",
+        help="Disable keyboard controls (no pause/seek; for scripts/recording)",
+    )
+    g_video.add_argument(
+        "--loop",
+        action="store_true",
+        help="Loop animated images (GIF/WebP/APNG). Default: loop forever.",
+        default=True,
+    )
+
+    p.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Print detection results and per-frame info to stderr",
+    )
+    return p
+
+
+_CONTROLS_HELP = """\
+Playback controls (video):
+  space         play / pause
+  ← / →         seek -5s / +5s
+  ↓ / ↑         seek -30s / +30s
+  , / .         previous / next frame (while paused)
+  m             mute / unmute
+  + / -         volume up / down
+  0             restart from beginning
+  q / esc       quit
+
+Requires ffmpeg for audio. Without it, video plays silently.
+"""

termview/controls.py

@@ -0,0 +1,114 @@
+"""
+Non-blocking keystroke reading for interactive video playback.
+
+Reads stdin one byte at a time and decodes:
+  - printable ASCII (space, q, m, f, comma, period, plus, minus, etc.)
+  - escape sequences for arrow keys + shift-arrows
+  - bare ESC (also returned for "quit")
+
+Designed to be called once per frame with the frame-budget as timeout, so it
+gives keystrokes near-immediate response while never blocking the render loop.
+Assumes stdin is already in cbreak mode (see TerminalState).
+"""
+
+import select
+import sys
+from enum import Enum
+
+
+class Key(Enum):
+    NONE = "none"
+    QUIT = "quit"
+    PAUSE = "pause"            # space
+    SEEK_BACK = "seek_back"    # left arrow
+    SEEK_FWD = "seek_fwd"      # right arrow
+    SEEK_BACK_BIG = "seek_back_big"   # shift+left or down
+    SEEK_FWD_BIG = "seek_fwd_big"     # shift+right or up
+    FRAME_PREV = "frame_prev"  # ,
+    FRAME_NEXT = "frame_next"  # .
+    MUTE = "mute"              # m
+    VOL_UP = "vol_up"          # + or =
+    VOL_DOWN = "vol_down"      # -
+    RESTART = "restart"        # 0 or home
+
+
+def read_key(timeout: float) -> Key:
+    """
+    Read at most one key event from stdin, waiting up to *timeout* seconds.
+    Returns Key.NONE if nothing arrived in that window.
+
+    Caller must ensure stdin is in cbreak (or raw) mode and is a TTY.
+    """
+    if not sys.stdin.isatty():
+        return Key.NONE
+
+    ready, _, _ = select.select([sys.stdin], [], [], timeout)
+    if not ready:
+        return Key.NONE
+
+    ch = sys.stdin.read(1)
+    if not ch:
+        return Key.NONE
+
+    # Single-character bindings.
+    simple = {
+        " ": Key.PAUSE,
+        "q": Key.QUIT,
+        "Q": Key.QUIT,
+        ",": Key.FRAME_PREV,
+        "<": Key.FRAME_PREV,
+        ".": Key.FRAME_NEXT,
+        ">": Key.FRAME_NEXT,
+        "m": Key.MUTE,
+        "M": Key.MUTE,
+        "+": Key.VOL_UP,
+        "=": Key.VOL_UP,
+        "-": Key.VOL_DOWN,
+        "_": Key.VOL_DOWN,
+        "0": Key.RESTART,
+    }
+    if ch in simple:
+        return simple[ch]
+
+    # ESC starts either a bare escape (= quit) or a CSI sequence.
+    if ch != "\033":
+        return Key.NONE
+
+    # Peek for a follow-up byte; if none arrives in 50ms it was a bare ESC.
+    ready, _, _ = select.select([sys.stdin], [], [], 0.05)
+    if not ready:
+        return Key.QUIT
+
+    if sys.stdin.read(1) != "[":
+        return Key.NONE  # unrecognized ESC-anything
+
+    # CSI sequence.  Read the final byte (and the optional modifier digits).
+    seq = ""
+    while True:
+        ready, _, _ = select.select([sys.stdin], [], [], 0.05)
+        if not ready:
+            break
+        b = sys.stdin.read(1)
+        seq += b
+        # Final bytes of a CSI sequence are in the 0x40-0x7E range.
+        if "@" <= b <= "~":
+            break
+
+    # Common arrow keys
+    if seq == "A":
+        return Key.SEEK_FWD_BIG     # up: +30s
+    if seq == "B":
+        return Key.SEEK_BACK_BIG    # down: -30s
+    if seq == "C":
+        return Key.SEEK_FWD         # right: +5s
+    if seq == "D":
+        return Key.SEEK_BACK        # left: -5s
+    # Shift-arrows arrive as CSI 1;2A / 1;2B / 1;2C / 1;2D in xterm-style.
+    if seq.endswith("C") and "2" in seq:
+        return Key.SEEK_FWD_BIG
+    if seq.endswith("D") and "2" in seq:
+        return Key.SEEK_BACK_BIG
+    if seq == "H":
+        return Key.RESTART          # Home
+
+    return Key.NONE