termview 0.1.0__tar.gz

termview-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Build artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+.eggs/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+*.swp

termview-0.1.0/LICENSE

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

termview-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: termview
+Version: 0.1.0
+Summary: View images, animated GIFs, and videos in the terminal — with audio and keyboard controls
+Project-URL: Homepage, https://github.com/yourusername/termview
+Project-URL: Repository, https://github.com/yourusername/termview
+Project-URL: Issues, https://github.com/yourusername/termview/issues
+Author: Zain ul Wahaj
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ansi,image,iterm2,kitty,sixel,terminal,video,viewer
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+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: Topic :: Multimedia :: Graphics :: Viewers
+Classifier: Topic :: Multimedia :: Video :: Display
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=10.0
+Provides-Extra: video
+Requires-Dist: opencv-python-headless>=4.8; extra == 'video'
+Description-Content-Type: text/markdown
+
+# termview
+
+View images, animated GIFs, and videos in your terminal. Audio + keyboard controls included.
+
+```bash
+tv photo.jpg
+tv animation.gif
+tv movie.mp4
+```
+
+## Install
+
+```bash
+pip install -e ".[video]"
+```
+
+Video playback also wants `ffmpeg` for audio. Without it, video plays silently:
+
+```bash
+brew install ffmpeg              # macOS
+apt install ffmpeg               # Debian/Ubuntu
+```
+
+## How it picks a renderer
+
+`tv` auto-detects the best graphics protocol your terminal supports and falls
+back gracefully. The four paths, in quality order:
+
+| Renderer | Used when | Quality |
+|---|---|---|
+| **kitty** | Kitty, WezTerm, Ghostty (sets `$KITTY_WINDOW_ID` or `$TERM_PROGRAM`) | pixel-perfect |
+| **iterm2** | iTerm2, Warp (sets `$TERM_PROGRAM=iTerm.app`) | pixel-perfect |
+| **sixel** | xterm, foot, Windows Terminal, mlterm (queried via DA1) | pixel-perfect |
+| **block** | everywhere else (universal fallback) | ANSI background fills, one image pixel per cell |
+
+The **block** renderer auto-switches between truecolor (`\033[48;2;R;G;Bm`) and
+xterm 256-color with Floyd-Steinberg dithering depending on what your terminal
+actually supports — macOS Terminal.app gets dithered output, everything else
+gets full 24-bit.
+
+Force a renderer:
+
+```bash
+tv photo.jpg --renderer kitty
+tv photo.jpg --renderer block --depth 256
+```
+
+## Video playback
+
+```bash
+tv movie.mp4               # plays with audio (if ffmpeg installed)
+tv movie.mp4 --no-audio    # silent
+tv movie.mp4 --fps 8       # throttle frame rate
+```
+
+### Keyboard controls
+
+| Key | Action |
+|---|---|
+| `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 |
+
+Add `--no-controls` to disable for scripting / asciinema recording.
+
+## Cross-terminal notes
+
+| Environment | Behavior |
+|---|---|
+| **tmux** | Forces the block renderer. Pixel-protocol passthrough is fragile across tmux versions; `--renderer kitty` etc. can still be forced if you've enabled `allow-passthrough on` (tmux 3.4+). |
+| **SSH** | Forces the block renderer. Inline-image protocols don't survive most SSH chains. |
+| **macOS Terminal.app** | Auto-detected as 256-color. Floyd-Steinberg dithering kicks in for stills; video uses no-dither for stability and an automatic 12fps cap. |
+| **Windows Terminal** | Auto-detected via `$WT_SESSION`, uses sixel. |
+| **non-TTY stdout** (`tv x.png > out`) | Video playback refuses. Images write a renderable stream that's only meaningful when re-played to a terminal. |
+
+## CLI reference
+
+```text
+usage: tv [-h] [--renderer NAME] [--depth DEPTH] [--width COLS] [--no-crop]
+          [--fps N] [--no-audio] [--no-controls] [--loop] [-v]
+          file
+
+rendering:
+  --renderer NAME    kitty | iterm2 | sixel | block  (default: auto)
+  --depth DEPTH      truecolor | 256                 (default: auto)
+  --width COLS       override terminal width
+  --no-crop          disable automatic border cropping
+
+video / animation:
+  --fps N            limit playback frame rate
+  --no-audio         disable audio
+  --no-controls      disable keyboard controls
+  --loop             loop animated images (default: on)
+
+  -v, --verbose      print detection diagnostics
+```
+
+## Library use
+
+```python
+from termview import load_image, fit_image, get_renderer, detect_renderer, terminal_size
+
+img = load_image("photo.jpg")
+cols, rows = terminal_size()
+renderer_type = detect_renderer()
+fitted = fit_image(img, cols, rows, renderer_type)
+get_renderer(renderer_type).display(fitted)
+```
+
+Video and animation playback have higher-level entry points
+(`stream_video`, `stream_animation`) that bundle the playback loop, audio
+process management, keyboard input, and terminal state restoration.

termview-0.1.0/README.md

@@ -0,0 +1,117 @@
+# termview
+
+View images, animated GIFs, and videos in your terminal. Audio + keyboard controls included.
+
+```bash
+tv photo.jpg
+tv animation.gif
+tv movie.mp4
+```
+
+## Install
+
+```bash
+pip install -e ".[video]"
+```
+
+Video playback also wants `ffmpeg` for audio. Without it, video plays silently:
+
+```bash
+brew install ffmpeg              # macOS
+apt install ffmpeg               # Debian/Ubuntu
+```
+
+## How it picks a renderer
+
+`tv` auto-detects the best graphics protocol your terminal supports and falls
+back gracefully. The four paths, in quality order:
+
+| Renderer | Used when | Quality |
+|---|---|---|
+| **kitty** | Kitty, WezTerm, Ghostty (sets `$KITTY_WINDOW_ID` or `$TERM_PROGRAM`) | pixel-perfect |
+| **iterm2** | iTerm2, Warp (sets `$TERM_PROGRAM=iTerm.app`) | pixel-perfect |
+| **sixel** | xterm, foot, Windows Terminal, mlterm (queried via DA1) | pixel-perfect |
+| **block** | everywhere else (universal fallback) | ANSI background fills, one image pixel per cell |
+
+The **block** renderer auto-switches between truecolor (`\033[48;2;R;G;Bm`) and
+xterm 256-color with Floyd-Steinberg dithering depending on what your terminal
+actually supports — macOS Terminal.app gets dithered output, everything else
+gets full 24-bit.
+
+Force a renderer:
+
+```bash
+tv photo.jpg --renderer kitty
+tv photo.jpg --renderer block --depth 256
+```
+
+## Video playback
+
+```bash
+tv movie.mp4               # plays with audio (if ffmpeg installed)
+tv movie.mp4 --no-audio    # silent
+tv movie.mp4 --fps 8       # throttle frame rate
+```
+
+### Keyboard controls
+
+| Key | Action |
+|---|---|
+| `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 |
+
+Add `--no-controls` to disable for scripting / asciinema recording.
+
+## Cross-terminal notes
+
+| Environment | Behavior |
+|---|---|
+| **tmux** | Forces the block renderer. Pixel-protocol passthrough is fragile across tmux versions; `--renderer kitty` etc. can still be forced if you've enabled `allow-passthrough on` (tmux 3.4+). |
+| **SSH** | Forces the block renderer. Inline-image protocols don't survive most SSH chains. |
+| **macOS Terminal.app** | Auto-detected as 256-color. Floyd-Steinberg dithering kicks in for stills; video uses no-dither for stability and an automatic 12fps cap. |
+| **Windows Terminal** | Auto-detected via `$WT_SESSION`, uses sixel. |
+| **non-TTY stdout** (`tv x.png > out`) | Video playback refuses. Images write a renderable stream that's only meaningful when re-played to a terminal. |
+
+## CLI reference
+
+```text
+usage: tv [-h] [--renderer NAME] [--depth DEPTH] [--width COLS] [--no-crop]
+          [--fps N] [--no-audio] [--no-controls] [--loop] [-v]
+          file
+
+rendering:
+  --renderer NAME    kitty | iterm2 | sixel | block  (default: auto)
+  --depth DEPTH      truecolor | 256                 (default: auto)
+  --width COLS       override terminal width
+  --no-crop          disable automatic border cropping
+
+video / animation:
+  --fps N            limit playback frame rate
+  --no-audio         disable audio
+  --no-controls      disable keyboard controls
+  --loop             loop animated images (default: on)
+
+  -v, --verbose      print detection diagnostics
+```
+
+## Library use
+
+```python
+from termview import load_image, fit_image, get_renderer, detect_renderer, terminal_size
+
+img = load_image("photo.jpg")
+cols, rows = terminal_size()
+renderer_type = detect_renderer()
+fitted = fit_image(img, cols, rows, renderer_type)
+get_renderer(renderer_type).display(fitted)
+```
+
+Video and animation playback have higher-level entry points
+(`stream_video`, `stream_animation`) that bundle the playback loop, audio
+process management, keyboard input, and terminal state restoration.

termview-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "termview"
+version = "0.1.0"
+description = "View images, animated GIFs, and videos in the terminal — with audio and keyboard controls"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Zain ul Wahaj" },
+]
+keywords = ["terminal", "image", "video", "viewer", "ansi", "sixel", "kitty", "iterm2"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Graphics :: Viewers",
+    "Topic :: Multimedia :: Video :: Display",
+    "Topic :: Terminals",
+]
+dependencies = [
+    "pillow>=10.0",
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+video = ["opencv-python-headless>=4.8"]
+
+[project.urls]
+Homepage = "https://github.com/yourusername/termview"
+Repository = "https://github.com/yourusername/termview"
+Issues = "https://github.com/yourusername/termview/issues"
+
+[project.scripts]
+tv = "termview.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["termview"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "termview",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]

termview-0.1.0/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-0.1.0/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()