ulf 0.1.0__py3-none-any.whl

ulf/__init__.py

@@ -0,0 +1,116 @@
+"""Python API for Unicode Lossful Format (ULF).
+
+The functions in this module expose the same settings as the command-line
+tools.  Optional features need their matching extra: ``ulf[all]`` installs
+GPU playback/matching and live audio playback support.
+"""
+
+from __future__ import annotations
+
+from os import PathLike
+from typing import Literal
+
+__version__ = "0.1.0"
+
+Pathish = str | PathLike[str]
+Backend = Literal["auto", "vulkan", "cpu"]
+Quality = Literal["high", "medium", "low"]
+Encoder = Literal["auto", "nvenc", "amf", "qsv", "vaapi", "cpu"]
+
+
+def _path(value: Pathish) -> str:
+    return str(value)
+
+
+def encode(
+    input: Pathish,
+    output: Pathish | None = None,
+    *,
+    size: str = "80x40",
+    fps: float = 0,
+    font: Pathish | None = None,
+    every: int = 1,
+    backend: Backend = "auto",
+    keyframe_interval: int = 24,
+    emojiless: bool = False,
+    hackerman: bool = False,
+    audio_waves: int = 8,
+    audio_segment: float = 0.05,
+    mute: bool = False,
+    debug: bool = False,
+) -> None:
+    """Encode a video as ULF.
+
+    ``output`` defaults to the input filename with a ``.ulf`` suffix.
+    Keyword names correspond to the CLI options with hyphens replaced by
+    underscores.
+    """
+    from pathlib import Path
+    from ulf_encode import main
+
+    source = _path(input)
+    destination = _path(output) if output is not None else str(Path(source).with_suffix(".ulf"))
+    argv = [source, destination, "--size", size, "--fps", str(fps), "--every", str(every),
+            "--backend", backend, "--keyframe-interval", str(keyframe_interval),
+            "--audio-waves", str(audio_waves), "--audio-segment", str(audio_segment)]
+    if font is not None:
+        argv += ["--font", _path(font)]
+    if emojiless:
+        argv.append("--emojiless")
+    if hackerman:
+        argv.append("--hackerman")
+    if mute:
+        argv.append("--mute")
+    if debug:
+        argv.append("--debug")
+    main(argv)
+
+
+def play(
+    input: Pathish,
+    *,
+    window: str = "1000x700",
+    font: Pathish | None = None,
+    backend: Backend = "auto",
+    mute: bool = False,
+    debug: bool = False,
+) -> None:
+    """Play a ULF file in a window."""
+    from ulf_play import main
+
+    argv = [_path(input), "--window", window, "--backend", backend]
+    if font is not None:
+        argv += ["--font", _path(font)]
+    if mute:
+        argv.append("--mute")
+    if debug:
+        argv.append("--debug")
+    main(argv)
+
+
+def convert(
+    input: Pathish,
+    output: Pathish,
+    *,
+    font: Pathish | None = None,
+    backend: Backend = "auto",
+    mute: bool = False,
+    export_size: str | None = None,
+    export_quality: Quality = "high",
+    encoder: Encoder = "auto",
+) -> None:
+    """Export a ULF file to MP4 using FFmpeg."""
+    from ulf_play import main
+
+    argv = [_path(input), "--backend", backend, "--export", _path(output),
+            "--export-quality", export_quality, "--encoder", encoder]
+    if font is not None:
+        argv += ["--font", _path(font)]
+    if mute:
+        argv.append("--mute")
+    if export_size is not None:
+        argv += ["--export-size", export_size]
+    main(argv)
+
+
+__all__ = ["convert", "encode", "play", "__version__"]

ulf/__main__.py

@@ -0,0 +1,39 @@
+"""Unified ``ulf`` command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def main(argv=None) -> None:
+    parser = argparse.ArgumentParser(prog="ulf", description="Unicode Lossful Format tools")
+    commands = parser.add_subparsers(dest="command", required=True)
+    # Disable subcommand help here so it is forwarded to the established
+    # encoder/player parsers, which own the option documentation.
+    commands.add_parser("encode", help="Encode video as ULF", add_help=False)
+    commands.add_parser("play", help="Play a ULF file", add_help=False)
+    convert_parser = commands.add_parser(
+        "convert", help="Export a ULF file to MP4", add_help=False
+    )
+    convert_parser.add_argument("input", nargs="?")
+    convert_parser.add_argument("output", nargs="?")
+    namespace, remaining = parser.parse_known_args(argv)
+
+    if namespace.command == "encode":
+        from ulf_encode import main as command
+        command(remaining)
+    elif namespace.command == "play":
+        from ulf_play import main as command
+        command(remaining)
+    else:
+        from ulf_play import main as command
+        if "-h" in remaining or "--help" in remaining:
+            command(["--help"])
+            return
+        if namespace.input is None or namespace.output is None:
+            convert_parser.error("the following arguments are required: input, output")
+        command([namespace.input, "--export", namespace.output, *remaining])
+
+
+if __name__ == "__main__":
+    main()

ulf/_optional.py

@@ -0,0 +1,23 @@
+
+"""Checks and messages for features supplied by optional dependencies."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+
+INSTALL_ALL = 'python -m pip install "unicode-lossful-format[all]"'
+
+
+def has_optional_dependencies(*modules: str) -> bool:
+    """Return True when all requested optional modules are available."""
+    return all(importlib.util.find_spec(module) is not None for module in modules)
+
+
+def warn_optional(feature: str) -> None:
+    """Tell users how to enable an optional enhancement."""
+    print(
+        f"WARNING: {feature} will not work without optional dependencies. "
+        f"Install every optional feature with: {INSTALL_ALL}",
+        file=sys.stderr,
+    )

ulf-0.1.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: ulf
+Version: 0.1.0
+Summary: Encode, play, and export Unicode Lossful Format video files.
+Author: ULF contributors
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/EquinoxDaFurry/ULF
+Project-URL: Repository, https://github.com/EquinoxDaFurry/ULF
+Project-URL: Issues, https://github.com/EquinoxDaFurry/ULF/issues
+Keywords: video,unicode,encoder,terminal,ulf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fonttools
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: pillow
+Requires-Dist: regex
+Provides-Extra: gpu
+Requires-Dist: wgpu; extra == "gpu"
+Requires-Dist: rendercanvas; extra == "gpu"
+Requires-Dist: glfw; extra == "gpu"
+Provides-Extra: audio
+Requires-Dist: sounddevice; extra == "audio"
+Provides-Extra: all
+Requires-Dist: wgpu; extra == "all"
+Requires-Dist: rendercanvas; extra == "all"
+Requires-Dist: glfw; extra == "all"
+Requires-Dist: sounddevice; extra == "all"
+Dynamic: license-file
+
+# Unicode Lossful Format (ULF)
+
+A deliberately silly text-based video format. ULF represents video frames using Unicode characters, choosing glyphs that visually resemble parts of the original image.
+
+It supports audio, delta-frame compression, GPU acceleration, and MP4 export.
+
+## Comparison
+
+<img src="ULF_comparison.gif" alt="ULF Comparison" width="600">
+
+## Requirements
+
+Python 3.10+.
+
+Install the package (with all optional playback features):
+
+```bash
+python -m pip install "unicode-lossful-format[all]"
+```
+
+FFmpeg must be installed and available on your system PATH for MP4 export.
+It is an external system dependency and is not installed by pip or by any ULF
+extra. Verify it with `ffmpeg -version` before using `ulf convert` or
+`ulf.convert()`.
+
+## Encode
+
+```bash
+ulf-encode input.mp4 output.ulf --size 80x40
+```
+
+### Options
+
+- `--size WIDTHxHEIGHT`: Character-grid resolution (default: `80x40`).
+- `--fps N`: Output frame rate.
+- `--font PATH`: Font used for glyph matching.
+- `--every N`: Encode every Nth source frame.
+- `--backend auto|vulkan|cpu`: Select processing backend.
+- `--keyframe-interval N`: Set the interval between full frames.
+- `--mute`: Disable audio.
+- `--audio-waves N`: Set audio reconstruction detail.
+- `--emojiless`: Exclude emoji characters.
+- `--hackerman`: Use printable keyboard ASCII characters only.
+- `--debug`: Enable diagnostic output.
+
+## Play
+
+```bash
+ulf-play output.ulf
+```
+
+### Options
+
+- `--window WIDTHxHEIGHT`: Set playback window size.
+- `--font PATH`: Select playback font.
+- `--backend auto|vulkan|cpu`: Select playback backend.
+- `--mute`: Disable audio.
+- `--debug`: Enable diagnostic output.
+
+## Convert to MP4
+
+```bash
+ulf convert output.ulf output.mp4 --encoder auto --export-quality high
+```
+
+The legacy equivalent remains `ulf-play output.ulf --export output.mp4`.
+
+## Python API
+
+The same options are available as keyword arguments, using underscores in
+place of CLI hyphens:
+
+```python
+import ulf
+
+ulf.encode("example.mp4", "example.ulf", size="80x40", backend="auto")
+ulf.play("example.ulf", window="1280x720", mute=False)
+ulf.convert("example.ulf", "example.mp4", encoder="auto", export_quality="high")
+```
+
+`encode()` derives an `.ulf` output path when its `output` argument is omitted.
+`convert()` requires FFmpeg on your system `PATH`, just like the CLI.
+
+## File format
+
+ULF files use the `.ulf` extension and are stored as UTF-8 text.
+
+The format uses the `ULF/1.0` signature and supports full-frame and delta-frame video, with optional audio data.
+
+## Limitations
+
+- Video is grayscale.
+- Audio reconstruction is lossy.
+- Visual quality depends on the selected font and renderer.
+- Vulkan requires compatible hardware and drivers.
+- MP4 export requires FFmpeg.
+- Large resolutions can increase processing time and file size.
+
+## Have fun
+
+ULF makes video less efficient on purpose.
+
+Now with compression, GPU acceleration, sound, and MP4 export!

ulf-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ulf_encode.py,sha256=QN16ruYiV0V7WOd-3Cdv5LK_JXPdltUpCa0T_BDnzU8,33888
+ulf_play.py,sha256=I5_2eXmq4rIlBgUQ_aKDuIqHm5SY927UZ_drsy-unGg,57224
+ulf/__init__.py,sha256=rg_IwHyWM_-jvwonivtRGOiat_UVWRYrUOxl2aJKL-o,3189
+ulf/__main__.py,sha256=H4GnPXVM8o_O0CXuAA0CeIxq3lnyLL3KNoQBKn4ACgs,1512
+ulf/_optional.py,sha256=6hJVgK50liDsj7YMuZYMOdaU4bU4KW_ymRN4KipIWgg,710
+ulf-0.1.0.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+ulf-0.1.0.dist-info/METADATA,sha256=u1qqJvnKnLDSsXGg_orW5iGHr9K4OBpGaLbUtuqdzs4,4487
+ulf-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+ulf-0.1.0.dist-info/entry_points.txt,sha256=BjmilIMsQTtvd0hzEw8dDkBItyeCvBcg-Y3yq1U0b1s,96
+ulf-0.1.0.dist-info/top_level.txt,sha256=yiDrSbNvzVHvoxW6gsxkz_1ZJ0vhZneEpvTGxsZan3c,24
+ulf-0.1.0.dist-info/RECORD,,

ulf-0.1.0.dist-info/WHEEL

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

ulf-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+ulf = ulf.__main__:main
+ulf-encode = ulf_encode:main
+ulf-play = ulf_play:main