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