cvf 1.0.0__py3-none-any.whl

cvf/__init__.py

@@ -0,0 +1,297 @@
+"""
+cvf — Console Video File (.cvf) Making and Executing.
+Author: Suleiman
+Version: 1.0.0
+License: MIT.
+Copyright (c) Suleiman 2026
+"""
+
+import os
+import json
+import time
+import lzma
+import zipfile
+from datetime import datetime
+
+try:
+    import cuifw
+    _HAVE_CUIFW = True
+except ImportError:
+    _HAVE_CUIFW = False
+
+
+__version__ = "1.0.0"
+__author__ = "Suleiman"
+__all__ = ["CreateVideo", "PlayVideo", "VideoData"]
+
+
+DEFAULT_CHARS = " .:-=+*#%@"
+MAGIC_FORMAT = "CVF"
+FORMAT_VERSION = "1.0"
+
+
+# ═════════════════════════════════════════════════════════
+#  Writer
+# ═════════════════════════════════════════════════════════
+
+def _write_cvf(path, frames, width, height,
+               fps, chars, metadata, compress_level):
+    if not frames:
+        raise ValueError("cvf: no frames")
+
+    expected = width * height
+    for i, f in enumerate(frames):
+        if len(f) != expected:
+            raise ValueError(
+                "cvf: frame %d size %d, expected %d"
+                % (i, len(f), expected)
+            )
+
+    raw = b"".join(frames)
+    compressed = lzma.compress(
+        raw, format=lzma.FORMAT_XZ, preset=int(compress_level)
+    )
+
+    meta = {
+        "format": MAGIC_FORMAT,
+        "version": FORMAT_VERSION,
+        "width": int(width),
+        "height": int(height),
+        "fps": int(fps),
+        "frame_count": len(frames),
+        "chars": chars,
+        "compression": "lzma-xz",
+        "raw_size": len(raw),
+        "compressed_size": len(compressed),
+        "created": datetime.now().isoformat(),
+    }
+    if metadata:
+        meta["user"] = metadata
+
+    with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as z:
+        z.writestr("meta.json", json.dumps(meta, indent=2, ensure_ascii=False))
+        z.writestr("chars.txt", chars)
+        z.writestr("frames.lzma", compressed)
+
+    return path
+
+
+# ═════════════════════════════════════════════════════════
+#  Reader
+# ═════════════════════════════════════════════════════════
+
+def _read_cvf(path, load_frames=True):
+    with zipfile.ZipFile(path, "r") as z:
+        meta = json.loads(z.read("meta.json").decode("utf-8"))
+        chars = z.read("chars.txt").decode("utf-8")
+        compressed = z.read("frames.lzma")
+
+    result = {
+        "meta": meta,
+        "chars": chars,
+        "frames": None,
+        "frame_count": meta.get("frame_count", 0),
+    }
+
+    if load_frames:
+        raw = lzma.decompress(compressed)
+        w = meta["width"]
+        h = meta["height"]
+        size = w * h
+        count = meta["frame_count"]
+        result["frames"] = [
+            raw[i * size:(i + 1) * size] for i in range(count)
+        ]
+
+    return result
+
+
+# ═════════════════════════════════════════════════════════
+#  Player (CuiFW widget)
+# ═════════════════════════════════════════════════════════
+
+if _HAVE_CUIFW:
+
+    class _CVFWidget(cuifw.RenderWidget):
+        def __init__(self, x, y, w, h, chars, color, bg):
+            super().__init__(x, y, w, h)
+            self.chars = chars
+            self.color = color or cuifw.Colors.WHITE
+            self.bg = bg
+            self.frame = None
+            self.fw = 0
+            self.fh = 0
+
+        def set_frame(self, frame, w, h):
+            self.frame = frame
+            self.fw = w
+            self.fh = h
+
+        def clear_frame(self):
+            self.frame = None
+            self.fw = 0
+            self.fh = 0
+
+        def draw(self, canvas):
+            if self.frame is None:
+                return
+            w = min(self.fw, self.w)
+            h = min(self.fh, self.h)
+            nchars = len(self.chars)
+            for row in range(h):
+                base = row * self.fw
+                for col in range(w):
+                    idx = self.frame[base + col]
+                    if idx >= nchars:
+                        idx = 0
+                    ch = self.chars[idx]
+                    if ch != " ":
+                        canvas.set(self.x + col, self.y + row, ch,
+                                   self.color, self.bg)
+
+
+    class _CVFPlayer:
+        def __init__(self, path, color=None, bg=None,
+                     show_status=True, loop=False):
+            data = _read_cvf(path, load_frames=True)
+            self.path = path
+            self.meta = data["meta"]
+            self.chars = data["chars"]
+            self.frames = data["frames"]
+            self.width = self.meta["width"]
+            self.height = self.meta["height"]
+            self.fps = self.meta["fps"] or 15
+            self.frame_time = 1.0 / self.fps
+            self.loop = loop
+            self.show_status = show_status
+
+            self.app = cuifw.App(alt_screen=True)
+            self.W, self.H = self.app.size()
+            h = self.H - 1 if show_status else self.H
+
+            self.widget = _CVFWidget(0, 0, self.W, h,
+                                     chars=self.chars,
+                                     color=color, bg=bg)
+            self.app.add(self.widget)
+
+            self.index = 0
+            self.last = 0.0
+            self.shown = 0
+            self.start = 0.0
+
+        def _draw_status(self):
+            if not self.show_status:
+                return
+            canvas = self.app.canvas
+            if canvas is None:
+                return
+
+            elapsed = time.time() - self.start
+            fps = self.shown / elapsed if elapsed > 0 else 0
+            total = len(self.frames)
+            name = os.path.basename(self.path)
+
+            text = " %s | %d/%d | %.1f FPS " % (name, self.index, total, fps)
+
+            y = self.H - 1
+            canvas.fill_rect(0, y, self.W - 1, y, " ",
+                             cuifw.Colors.BLACK, cuifw.Colors.BG_BLACK)
+            canvas.text(0, y, text[:self.W],
+                        cuifw.Colors.CYAN, cuifw.Colors.BG_BLACK)
+
+        def _on_tick(self):
+            now = time.time()
+            if now - self.last < self.frame_time:
+                return
+            self.last = now
+
+            if self.index >= len(self.frames):
+                if self.loop:
+                    self.index = 0
+                else:
+                    self.app.quit()
+                    return
+
+            frame = self.frames[self.index]
+            self.widget.set_frame(frame, self.width, self.height)
+            self.index += 1
+            self.shown += 1
+
+            self.app.redraw()
+            self._draw_status()
+
+        def run(self):
+            self.start = time.time()
+            try:
+                self.app.run(on_tick=self._on_tick, tick_interval=0.005)
+            except KeyboardInterrupt:
+                pass
+
+
+# ═════════════════════════════════════════════════════════
+#  Public API
+# ═════════════════════════════════════════════════════════
+
+def CreateVideo(path, frames, width, height,
+                fps=15, chars=DEFAULT_CHARS,
+                metadata=None, compress_level=6):
+    """
+    Create a .cvf video file.
+
+    path            — output .cvf path
+    frames          — list of bytes (each width*height)
+    width, height   — frame dimensions
+    fps             — playback framerate
+    chars           — character palette (max 256)
+    metadata        — optional dict of extra info
+    compress_level  — LZMA 0-9 (default 6)
+
+    Returns path.
+    """
+    return _write_cvf(path, frames, width, height,
+                      fps=fps, chars=chars,
+                      metadata=metadata,
+                      compress_level=compress_level)
+
+
+def PlayVideo(path, color=None, bg=None,
+              show_status=True, loop=False):
+    """
+    Play a .cvf file in the terminal using CuiFW.
+
+    path        — input .cvf file
+    color       — ANSI color (default: WHITE)
+    bg          — background color (default: none)
+    show_status — show filename + FPS at bottom
+    loop        — loop playback
+
+    Requires CuiFW. Raises RuntimeError if CuiFW is not installed.
+
+    Returns the player object.
+    """
+    if not _HAVE_CUIFW:
+        raise RuntimeError(
+            "cvf: CuiFW is required for PlayVideo(). "
+            "Install CuiFW or use VideoData() to read frames manually."
+        )
+    player = _CVFPlayer(path, color=color, bg=bg,
+                        show_status=show_status, loop=loop)
+    player.run()
+    return player
+
+
+def VideoData(path, load_frames=True):
+    """
+    Read a .cvf file.
+
+    Returns dict:
+        {
+            "meta":        {...},
+            "chars":       "...",
+            "frames":      [bytes, ...] or None,
+            "frame_count": int,
+        }
+
+    Set load_frames=False to read only metadata.
+    """
+    return _read_cvf(path, load_frames=load_frames)

cvf-1.0.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: cvf
+Version: 1.0.0
+Summary: Console Video File - ASCII video format for the terminal
+Home-page: 
+Author: Suleiman
+Author-email: 
+License: MIT
+Keywords: terminal ascii video cui cvf cuifw
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Terminals
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cuifw==1.7.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# cvf
+
+Console Video File — ASCII video format for the terminal.
+
+Stores ASCII frames in a ZIP container with JSON metadata and LZMA-compressed
+frames. Playback uses CuiFW to render frames in the terminal.
+
+## Features
+
+- JSON metadata
+- LZMA-compressed frames
+- ZIP container
+- No ffmpeg for playback
+- Stdlib only
+- Windows, Linux, macOS, Termux
+
+## Install
+
+    pip install cvf
+
+Optional, for playback:
+
+    pip install cuifw
+
+## API
+
+    import cvf
+
+    cvf.CreateVideo(path, frames, width, height, fps=15, chars=..., metadata=None, compress_level=6)
+    cvf.PlayVideo(path, color=None, bg=None, show_status=True, loop=False)
+    cvf.VideoData(path, load_frames=True)
+
+### CreateVideo
+
+Write a .cvf file.
+
+    import cvf
+
+    frames = [...]  # list of bytes, each width*height
+    cvf.CreateVideo("out.cvf", frames, width=80, height=24, fps=15)
+
+Returns the output path.
+
+### PlayVideo
+
+Play a .cvf file using CuiFW. Requires CuiFW installed.
+
+    import cvf
+
+    cvf.PlayVideo("out.cvf")
+
+Returns the player object.
+
+### VideoData
+
+Read a .cvf file.
+
+    import cvf
+
+    data = cvf.VideoData("out.cvf")
+    print(data["meta"]["fps"])
+    print(data["frame_count"])
+
+    for frame in data["frames"]:
+        pass
+
+Metadata only:
+
+    data = cvf.VideoData("out.cvf", load_frames=False)
+
+## File format
+
+A .cvf file is a standard ZIP archive:
+
+    file.cvf
+    ├── meta.json
+    ├── chars.txt
+    └── frames.lzma
+
+### meta.json
+
+    {
+        "format": "CVF",
+        "version": "1.0",
+        "width": 80,
+        "height": 24,
+        "fps": 15,
+        "frame_count": 450,
+        "chars": " .:-=+*#%@",
+        "compression": "lzma-xz",
+        "raw_size": 864000,
+        "compressed_size": 312450,
+        "created": "2026-10-07T12:34:56"
+    }
+
+### chars.txt
+
+Character palette. Each byte in the frame data is an index into this string.
+
+Default:
+
+     .:-=+*#%@
+
+### frames.lzma
+
+All frames concatenated, then compressed with LZMA (XZ).
+
+Frame size = width * height bytes.
+Total raw size = width * height * frame_count bytes.
+
+## Size
+
+    80x24, 15 FPS, 10s   raw 288 KB   cvf ~110 KB
+    80x24, 15 FPS, 60s   raw 1.7 MB   cvf ~600 KB
+    120x40, 15 FPS, 60s  raw 4.3 MB   cvf ~1.4 MB
+
+## Requirements
+
+- Python 3.7+
+- Stdlib only
+- Optional: CuiFW for playback
+
+## Limitations
+
+- ASCII only
+- Fixed frame size
+- No audio
+- Fixed FPS
+- No seek during playback
+
+## License
+
+MIT — see LICENSE.
+
+## Author
+
+Suleiman
+
+## Changelog
+
+### 1.0.0
+
+- Initial release
+- CreateVideo, PlayVideo, VideoData
+- JSON metadata
+- LZMA-compressed frames
+- ZIP container

cvf-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+cvf/__init__.py,sha256=g2_KfULX7O86x7V-Vqgb4DvRTGZawBF1P3wNI5IyJA4,9517
+cvf-1.0.0.dist-info/licenses/LICENSE,sha256=XABCXMEhX5-sSW6dVui3V35LHqtlwNF4Rj0Rfhuo4_8,1064
+cvf-1.0.0.dist-info/METADATA,sha256=o0u1Ma8AnmNRGg4u2hqSX9aI8bM_CcjjYZ9DPvzqyD8,3788
+cvf-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cvf-1.0.0.dist-info/top_level.txt,sha256=naqdI6HXCxjbrjA_gr-Yg4TJLsPhkV-O9jDZarmgLOE,4
+cvf-1.0.0.dist-info/RECORD,,

cvf-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cvf-1.0.0.dist-info/licenses/LICENSE

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

cvf-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cvf