pycvr 0.1.0__py3-none-any.whl

cvr/__init__.py

@@ -0,0 +1,34 @@
+"""CVR: turn source code into a typewriter video in your real VS Code theme.
+
+    import cvr
+    cvr.render("script.py", "script.mp4", theme="Dark Modern", duration=20)
+
+The GUI lives in `cvr.gui` and is only imported when you ask for it, so the
+library works on machines without Tk.
+"""
+
+__version__ = "0.1.0"
+
+from .palette import DEFAULT_PALETTE, Palette
+from .renderer import (ANIMATION_STYLES, CodeTypewriterVideoRenderer,
+                       RenderCancelled, Renderer, RenderError, render)
+from .themes import (ThemeInfo, active_vscode_theme_label, default_theme,
+                     find_theme, list_themes, load_theme)
+
+__all__ = [
+    "ANIMATION_STYLES",
+    "CodeTypewriterVideoRenderer",
+    "DEFAULT_PALETTE",
+    "Palette",
+    "RenderCancelled",
+    "RenderError",
+    "Renderer",
+    "ThemeInfo",
+    "active_vscode_theme_label",
+    "default_theme",
+    "find_theme",
+    "list_themes",
+    "load_theme",
+    "render",
+    "__version__",
+]

cvr/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m cvr`: same as the `cvr` command."""
+
+from .cli import main
+
+raise SystemExit(main())

cvr/cli.py

@@ -0,0 +1,189 @@
+"""Command line: `cvr render`, `cvr themes`, and `cvr` alone for the GUI."""
+
+import argparse
+import logging
+import sys
+from typing import List, Optional, Tuple
+
+from . import __version__
+from .palette import DEFAULT_PALETTE
+from .renderer import ANIMATION_STYLES, RenderError, render
+from .themes import default_theme, list_themes
+
+
+def _resolution(text: str) -> Tuple[int, int]:
+    try:
+        w, h = (int(v) for v in text.lower().split("x"))
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"expected WIDTHxHEIGHT, got {text!r}")
+    if w <= 0 or h <= 0:
+        raise argparse.ArgumentTypeError("width and height must be positive")
+    return w, h
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cvr",
+        description="Turn source code into a typewriter video in your VS Code "
+                    "theme. Run with no command to open the app.")
+    parser.add_argument("--version", action="version",
+                        version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    sub.add_parser("gui", help="open the app (the default)")
+
+    r = sub.add_parser("render", help="render a source file to a video",
+                       description="Render a source file to a typewriter video.")
+    r.add_argument("file", help="source file to type out")
+    r.add_argument("-o", "--output", metavar="PATH",
+                   help="video to write (default: FILE_typewriter.mp4 here)")
+    r.add_argument("-t", "--theme", metavar="NAME",
+                   help="installed VS Code theme or a theme json path "
+                        "(default: the theme VS Code is set to)")
+    r.add_argument("-d", "--duration", type=float, metavar="SECONDS",
+                   help="fixed length in seconds; without it the delays decide")
+    r.add_argument("-r", "--resolution", type=_resolution, default=(1280, 720),
+                   metavar="WxH", help="frame size (default: 1280x720)")
+    r.add_argument("--fps", type=int, default=30,
+                   help="frames per second (default: 30)")
+    r.add_argument("--font", metavar="PATH", help="TrueType font file")
+    r.add_argument("--font-size", type=int, default=18, metavar="PX",
+                   help="font size in pixels (default: 18)")
+    r.add_argument("--style", choices=ANIMATION_STYLES, default="smooth",
+                   help="animation style (default: smooth)")
+    r.add_argument("--char-delay", type=float, default=0.05, metavar="SECONDS",
+                   help="pause after each character (default: 0.05)")
+    r.add_argument("--line-delay", type=float, default=0.30, metavar="SECONDS",
+                   help="pause after each line (default: 0.30)")
+    r.add_argument("--language", metavar="NAME",
+                   help="Pygments lexer name, when the file extension is not enough")
+    r.add_argument("--no-line-numbers", action="store_true",
+                   help="hide the line number gutter")
+    r.add_argument("--no-tab", action="store_true",
+                   help="hide the file name tab")
+    r.add_argument("--no-cursor", action="store_true", help="hide the cursor")
+    r.add_argument("--no-blink", action="store_true",
+                   help="keep the cursor solid")
+    r.add_argument("--no-follow", action="store_true",
+                   help="do not scroll to follow the cursor")
+    r.add_argument("--no-smooth-scroll", action="store_true",
+                   help="jump instead of gliding when scrolling")
+    r.add_argument("--no-highlight", action="store_true",
+                   help="plain text, no syntax colours")
+    r.add_argument("--type-indent", action="store_true",
+                   help="type leading spaces instead of indenting instantly")
+    r.add_argument("--compatible", action="store_true",
+                   help="4:2:0 video that Windows Media Player can open "
+                        "(about one level off on dark tones)")
+    r.add_argument("--open", action="store_true",
+                   help="open the video when it is done")
+    r.add_argument("-q", "--quiet", action="store_true",
+                   help="no progress bar")
+    r.add_argument("-v", "--verbose", action="store_true",
+                   help="print timing details")
+
+    t = sub.add_parser("themes", help="list installed VS Code themes",
+                       description="List the colour themes VS Code has "
+                                   "installed. * marks the default.")
+    t.add_argument("filter", nargs="?", default="",
+                   help="only show themes whose name contains this")
+    t.add_argument("--paths", action="store_true",
+                   help="show each theme's json file")
+    return parser
+
+
+def _progress_printer(stream):
+    def show(pct: float, _total: float, status: str, eta: float):
+        width  = 28
+        filled = int(width * pct / 100)
+        bar    = "#" * filled + "-" * (width - filled)
+        eta_s  = f"  ETA {eta:.0f}s" if eta > 0 else ""
+        stream.write(f"\r[{bar}] {pct:5.1f}%  {status}{eta_s}".ljust(79))
+        stream.flush()
+    return show
+
+
+def _cmd_render(args) -> int:
+    show_progress = not args.quiet and sys.stderr.isatty()
+    try:
+        path = render(
+            args.file, args.output,
+            theme             = args.theme,
+            duration          = args.duration,
+            language          = args.language,
+            progress          = _progress_printer(sys.stderr) if show_progress else None,
+            resolution        = args.resolution,
+            fps               = args.fps,
+            font_path         = args.font,
+            font_size         = args.font_size,
+            animation_type    = args.style,
+            char_delay        = args.char_delay,
+            line_delay        = args.line_delay,
+            show_line_numbers = not args.no_line_numbers,
+            show_filename_bar = not args.no_tab,
+            show_cursor       = not args.no_cursor,
+            cursor_blink      = not args.no_blink,
+            follow_cursor     = not args.no_follow,
+            smooth_scroll     = not args.no_smooth_scroll,
+            syntax_highlighting = not args.no_highlight,
+            instant_indent    = not args.type_indent,
+            exact_colour      = not args.compatible,
+        )
+    except KeyboardInterrupt:
+        if show_progress:
+            sys.stderr.write("\n")
+        print("cvr: cancelled", file=sys.stderr)
+        return 130
+    except (RenderError, LookupError, OSError, ValueError) as exc:
+        if show_progress:
+            sys.stderr.write("\n")
+        print(f"cvr: {exc}", file=sys.stderr)
+        return 1
+
+    if show_progress:
+        sys.stderr.write("\n")
+    print(path)
+    if args.open:
+        from .players import Player
+        try:
+            Player("System default", "default").launch(path)
+        except OSError as exc:
+            print(f"cvr: could not open the video: {exc}", file=sys.stderr)
+    return 0
+
+
+def _cmd_themes(args) -> int:
+    themes  = list_themes()
+    default = default_theme(themes)
+    wanted  = args.filter.lower()
+    rows = [(t.label, t.path) for t in themes] + [(DEFAULT_PALETTE.name, "(built in)")]
+    for label, path in rows:
+        if wanted and wanted not in label.lower():
+            continue
+        mark = "*" if default and label == default.label else " "
+        print(f"{mark} {label}" + (f"\n      {path}" if args.paths else ""))
+    if not themes:
+        print("No VS Code themes found; only the built-in palette is available.",
+              file=sys.stderr)
+    return 0
+
+
+def _cmd_gui(_args) -> int:
+    try:
+        from .gui import main as gui_main
+    except ImportError as exc:
+        print(f"cvr: the app needs Tkinter, which this Python lacks ({exc}).\n"
+              "On Debian or Ubuntu: sudo apt install python3-tk", file=sys.stderr)
+        return 1
+    gui_main()
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    logging.basicConfig(
+        format="cvr: %(message)s",
+        level=logging.INFO if getattr(args, "verbose", False) else logging.WARNING)
+    command = args.command or "gui"
+    return {"render": _cmd_render, "themes": _cmd_themes,
+            "gui": _cmd_gui}[command](args)

cvr/encoders.py

@@ -0,0 +1,130 @@
+"""Video writers. Frames go in as RGB uint8 arrays of shape (height, width, 3)."""
+
+import logging
+import shutil
+import subprocess
+from typing import Optional, Tuple
+
+import numpy as np
+
+log = logging.getLogger(__name__)
+
+
+def ffmpeg_exe() -> Optional[str]:
+    """ffmpeg on PATH, else the copy bundled with the imageio-ffmpeg package."""
+    exe = shutil.which("ffmpeg")
+    if exe:
+        return exe
+    try:
+        import imageio_ffmpeg
+        return imageio_ffmpeg.get_ffmpeg_exe()
+    except Exception:
+        return None
+
+
+class OpenCVWriter:
+    """Fallback encoder. Goes through YUV, so dark colours shift slightly."""
+
+    def __init__(self, writer, cv2_module):
+        self._writer = writer
+        self._cv2 = cv2_module
+        self.exact_colour = False
+
+    @classmethod
+    def open(cls, path: str, fps: int, size: Tuple[int, int]):
+        try:
+            import cv2
+        except ImportError:
+            return None
+        fourcc_of = getattr(cv2, "VideoWriter_fourcc", None) or cv2.VideoWriter.fourcc
+        for fourcc_str in ("avc1", "mp4v"):
+            w = cv2.VideoWriter(path, fourcc_of(*fourcc_str), float(fps), size)
+            if w.isOpened():
+                return cls(w, cv2)
+            w.release()
+        return None
+
+    def write(self, frame: np.ndarray):
+        self._writer.write(self._cv2.cvtColor(frame, self._cv2.COLOR_RGB2BGR))
+
+    def release(self):
+        self._writer.release()
+
+
+class FFmpegWriter:
+    """Encoder that preserves colours exactly.
+
+    OpenCV converts every frame to limited range YUV, which moves the
+    theme colours. Encoding through ffmpeg keeps them intact, so what the
+    palette says is what the player shows.
+    """
+
+    def __init__(self, proc, exact_colour: bool):
+        self._proc = proc
+        self.exact_colour = exact_colour
+
+    @classmethod
+    def open(cls, path: str, fps: int, size: Tuple[int, int],
+             exact_colour: bool = False):
+        exe = ffmpeg_exe()
+        if not exe:
+            return None
+
+        if exact_colour:
+            # RGB in, RGB out: no colour conversion, no chroma subsampling.
+            # Exact, but this is H.264 High 4:4:4 Predictive, which Windows
+            # Media Player refuses to open. VLC and mpv play it.
+            codec = ["-c:v", "libx264rgb", "-crf", "12", "-pix_fmt", "bgr0"]
+        else:
+            # Ordinary High profile that plays everywhere. Full range keeps
+            # the luma untouched, where limited range would compress it into
+            # 16..235 and lose a level on the dark tones a code theme uses.
+            codec = ["-c:v", "libx264", "-crf", "16", "-pix_fmt", "yuv420p",
+                     "-color_range", "pc", "-colorspace", "bt709",
+                     "-color_primaries", "bt709", "-color_trc", "bt709",
+                     "-vf", "scale=in_range=full:out_range=full"]
+
+        cmd = [
+            exe, "-y", "-loglevel", "error",
+            "-f", "rawvideo", "-pix_fmt", "rgb24",
+            "-s", f"{size[0]}x{size[1]}", "-r", str(fps),
+            "-i", "-",
+            "-an", *codec,
+            "-preset", "medium",
+            "-movflags", "+faststart",
+            path,
+        ]
+        try:
+            proc = subprocess.Popen(cmd, stdin=subprocess.PIPE,
+                                    stdout=subprocess.DEVNULL,
+                                    stderr=subprocess.PIPE)
+        except OSError:
+            return None
+        return cls(proc, exact_colour)
+
+    def write(self, frame: np.ndarray):
+        self._proc.stdin.write(frame.tobytes())
+
+    def release(self):
+        try:
+            if self._proc.stdin:
+                self._proc.stdin.close()
+        except OSError:
+            pass
+        try:
+            self._proc.wait(timeout=60)
+        except subprocess.TimeoutExpired:
+            self._proc.kill()
+
+
+def open_writer(path: str, fps: int, size: Tuple[int, int],
+                exact_colour: bool = True):
+    """ffmpeg if there is one, else OpenCV, else None."""
+    writer = FFmpegWriter.open(path, fps, size, exact_colour=exact_colour)
+    if writer is None:
+        writer = OpenCVWriter.open(path, fps, size)
+        if writer is not None:
+            log.warning("ffmpeg not found; using the OpenCV writer, which "
+                        "shifts dark colours slightly. pip install imageio-ffmpeg "
+                        "to fix that.")
+    return writer

cvr/fonts.py

@@ -0,0 +1,121 @@
+"""Finding a monospace font, and measuring text with it."""
+
+import functools
+import logging
+import os
+import platform
+from typing import List, Optional
+
+from PIL import ImageFont
+
+log = logging.getLogger(__name__)
+
+
+def font_candidates() -> List[str]:
+    """Monospace fonts worth trying on this OS, best first."""
+    sys_name = platform.system()
+    if sys_name == "Windows":
+        return [
+            r"C:\Windows\Fonts\CascadiaCode.ttf",
+            r"C:\Windows\Fonts\CascadiaCode-Regular.ttf",
+            r"C:\Windows\Fonts\CascadiaMono.ttf",
+            r"C:\Windows\Fonts\consola.ttf",
+            r"C:\Windows\Fonts\cour.ttf",
+            r"C:\Windows\Fonts\lucon.ttf",
+        ]
+    if sys_name == "Darwin":
+        return [
+            "/Library/Fonts/Courier New.ttf",
+            "/System/Library/Fonts/Monaco.ttf",
+            "/System/Library/Fonts/Menlo.ttc",
+            "/System/Library/Fonts/SFMono-Regular.otf",
+        ]
+    return [
+        "/usr/share/fonts/truetype/liberation/LiberationMono-Regular.ttf",
+        "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
+        "/usr/share/fonts/truetype/ubuntu/UbuntuMono-R.ttf",
+    ]
+
+
+def _open(path: str, size: int) -> ImageFont.FreeTypeFont:
+    kwargs = {"index": 0} if path.lower().endswith(".ttc") else {}
+    return ImageFont.truetype(path, size, **kwargs)
+
+
+@functools.lru_cache(maxsize=16)
+def _font_file(font_path: Optional[str]) -> Optional[str]:
+    """First font file that actually opens, `font_path` first.
+
+    Cached because the last resort walks the whole Windows font folder.
+    """
+    candidates = ([font_path] if font_path else []) + font_candidates()
+    for path in candidates:
+        if not path or not os.path.exists(path):
+            continue
+        try:
+            _open(path, 12)
+            return path
+        except (IOError, OSError):
+            continue
+
+    fonts_dir = r"C:\Windows\Fonts"
+    if platform.system() == "Windows" and os.path.exists(fonts_dir):
+        for fname in os.listdir(fonts_dir):
+            if fname.lower().endswith((".ttf", ".ttc")):
+                path = os.path.join(fonts_dir, fname)
+                try:
+                    _open(path, 12)
+                    return path
+                except (IOError, OSError):
+                    continue
+    return None
+
+
+def load_font(font_path: Optional[str], size: int) -> ImageFont.FreeTypeFont:
+    """A TrueType font at `size` px: `font_path` if it opens, else a system mono.
+
+    Each call returns a fresh font object, so the GUI thread and a render
+    thread never share one FreeType face.
+    """
+    if font_path and not os.path.exists(font_path):
+        log.warning("Font %s not found; using a system font.", font_path)
+    path = _font_file(font_path)
+    if path:
+        try:
+            return _open(path, size)
+        except (IOError, OSError):
+            pass
+    log.warning("No TrueType font found; falling back to bitmap default.")
+    return ImageFont.load_default()
+
+
+_TW_CACHE: dict = {}
+
+
+def text_width(font, text: str) -> float:
+    """Advance width of `text` in pixels.
+
+    `getbbox` returns *ink* extents, which drift from the real pen advance and
+    would slowly push the cursor away from the text it follows; `getlength`
+    is the advance, so widths stay additive across tokens.
+    """
+    if not text:
+        return 0.0
+    key = (font, text)
+    width = _TW_CACHE.get(key)
+    if width is None:
+        try:
+            width = float(font.getlength(text))
+        except (AttributeError, TypeError):
+            bb = font.getbbox(text)
+            width = float(bb[2] - bb[0])
+        if len(_TW_CACHE) > 100_000:
+            _TW_CACHE.clear()
+        _TW_CACHE[key] = width
+    return width
+
+
+def text_height(font, text: str = "Mg") -> int:
+    """Ink height of `text` in pixels."""
+    bb = font.getbbox(text)
+    return bb[3] - bb[1]

cvr/gui/__init__.py

@@ -0,0 +1,5 @@
+"""The Tkinter desktop app. Start it with `cvr`, `cvr-gui` or `python -m cvr.gui`."""
+
+from .app import TypewriterVideoApp, main
+
+__all__ = ["TypewriterVideoApp", "main"]

cvr/gui/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m cvr.gui` opens the app."""
+
+from .app import main
+
+main()