Metadata-Version: 2.4
Name: cvf
Version: 1.0.4
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
