Metadata-Version: 2.4
Name: cvf_runtime
Version: 1.0.3
Summary: Runtime for CVF — Console Video File playback
Home-page: 
Author: Suleiman
Author-email: 
License: MIT
Keywords: terminal ascii video cvf runtime playback 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
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_runtime

Console Video File runtime — play `.cvf` files in the terminal.

`cvf_runtime` reads a `.cvf` file and plays it frame-by-frame
in the terminal. No keybinds, no editing, no interface.
Just playback.

## Install

    pip install cvf_runtime

Installs `cuifw` automatically (required for rendering).

## Usage

### Python

    import cvf_runtime

    cvf_runtime.execute("movie.cvf")

### With parameters

    cvf_runtime.execute("movie.cvf", loop=True)
    cvf_runtime.execute("movie.cvf", speed=2.0)
    cvf_runtime.execute("movie.cvf", fps=30)
    cvf_runtime.execute("movie.cvf", start=100, end=200)

### In the background

    import cvf_runtime
    import time

    handle = cvf_runtime.execute_async("movie.cvf", loop=True)
    time.sleep(5)
    handle.stop()

## API

### `cvf_runtime.execute(path, loop=False, speed=1.0, fps=None, start=0, end=None)`

Play a `.cvf` file in the terminal. Blocks until finished.

| Argument | Type | Description |
|----------|------|-------------|
| `path` | str | `.cvf` file |
| `loop` | bool | Loop forever |
| `speed` | float | Playback speed multiplier |
| `fps` | int | Override fps from file |
| `start` | int | First frame index |
| `end` | int | Last frame index (exclusive) |

Returns the number of frames shown.

### `cvf_runtime.execute_async(path, loop=False, speed=1.0, fps=None, start=0, end=None)`

Start a `.cvf` player in a background Python process.

Returns a handle with:

- `handle.is_playing()` — True if still running
- `handle.stop()` — graceful stop
- `handle.kill()` — force kill
- `handle.wait()` — block until done

### `cvf_runtime.Runtime(path, loop=False, speed=1.0, fps_override=None, start=0, end=None)`

Low-level player class.

Methods:

- `run()` — play, returns frames shown
- `info()` — dict with metadata

## Info about a file

    import cvf_runtime

    r = cvf_runtime.Runtime("movie.cvf")
    info = r.info()

    print(info["width"], "x", info["height"])
    print(info["fps"])
    print(info["frames"])
    print(info["duration"])
    print(info["color_mode"])

## Requirements

- Python 3.7+
- `cuifw` (installed automatically)
- Terminal with UTF-8 support

## Supported platforms

| Platform | Status |
|----------|--------|
| Linux | ✅ |
| macOS | ✅ |
| Windows (Terminal) | ✅ |
| Termux | ✅ |
| Pydroid 3 | ❌ (no ANSI rendering) |

## Difference from cvf

| | `cvf` | `cvf_runtime` |
|---|-------|---------------|
| Create video | ✅ | ❌ |
| Edit video | ✅ | ❌ |
| Interactive player | ✅ | ❌ |
| Keybinds | ✅ | ❌ |
| Background play | ⚠️ | ✅ |
| Size | ~30 KB | ~6 KB |
| Purpose | Tool | Runtime |

`cvf` — full library for creating and editing `.cvf` files.
`cvf_runtime` — minimal runtime for playing `.cvf` files.

## License

MIT — see LICENSE.

## Author

Suleiman

## Changelog

### 1.0.3

- Initial release
- `execute()` — synchronous playback
- `execute_async()` — background playback
- `Runtime` — low-level player
- `info()` — file metadata
- Grayscale and TrueColor support
