Metadata-Version: 2.4
Name: dur-converter
Version: 0.3.0
Summary: A simple converter CLI that convert your video into .dur file
Author: VaitoSoi
Author-email: VaitoSoi <me@vaito.dev>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: numpy>=2.5.1
Requires-Dist: opencv-python>=5.0.0.93
Requires-Dist: pillow>=12.3.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: tqdm>=4.70.0
Requires-Python: >=3.13
Project-URL: Homepage, https://git.vaito.dev/vaito/dur_convert
Project-URL: Issues, https://git.vaito.dev/vaito/dur_convert/issues
Description-Content-Type: text/markdown

# dur_convert

A simple converter CLI that convert your video into .dur file

## I. Introduction

As said in the description, this is a tool to convert a video into .dur file format (specifically version 7). See more about the [.dur format](https://github.com/durdraw/durdraw/blob/cf63d7445c00c5db1ee2dd28df8325649045b803/durformat.md)

It first slicing video into multiple image, then convert the image into an ansi and note down the color at the position.

~~Normally, a terminal character height is double compare to its width, so this project use a trick is using the upper half block unicode character ("▀").~~ Not working for now since it is the known issue of `durdraw` (or Python's `curses`), see more [here](https://github.com/durdraw/durdraw/issues/47)

### The upper half trick (Not working for now)

This program compress two pixels into one character, then set the foreground color to the upper pixel and the background to the lower one.

### The workaround of current issue

As mentioned before, an known issue in Python's `curses` library make coloring the background with 256 color is impossible. So the `--half-frame` flag is introduced as the workaround. The `--half-frame` flag still compressing two pixels into one character, but this time, it use the full block one ("█") and choose the upper pixel color.

## II. Installation

You can install it from PYPI using your favorite tool:

```bash
pip install dur_converter
```

Or

```bash
uv add dur_converter
```

Then calling it with using `dc` keyword:

```bash
dc --help
# usage: dc [-h] [-R <Width>x<Heigth>] [-c COL] [-r ROW] [-f FPS] [-H] [-o OUTPUT] input
# 
# A simple python script that convert your video into .dur file
# 
# positional arguments:
#   input                 the input
# 
# options:
#   -h, --help            show this help message and exit
#   -R, --resolution <Width>x<Heigth>
#                         the target output resolution
#   -c, --col COL         the target output width, will be overwritten --resolution flag
#   -r, --row ROW         the target output height, will be overwritten --resolution flag
#   -f, --fps FPS         the target output frame-per-second
#   -H, --half-frame      Cut the height in half, result in wider image but reduced quality
#   -o, --output OUTPUT   output destination, default to ./data/out.dur
# 
# Originally, this software is targetted for Ly (a screen manager for Linux)
```

Or using [uvx](https://docs.astral.sh/uv/guides/tools/#running-tools)

```bash
uvx --from dur_converter dc --help
# usage: dc [-h] [-R <Width>x<Heigth>] [-c COL] [-r ROW] [-f FPS] [-m {1,2,3}] [-o OUTPUT] [-d] input
# 
# A simple python script that convert your video into .dur file
# 
# positional arguments:
#   input                 the input
# 
# options:
#   -h, --help            show this help message and exit
#   -R, --resolution <Width>x<Heigth>
#                         the target output resolution
#   -c, --col COL         the target output width, will be overwritten --resolution flag
#   -r, --row ROW         the target output height, will be overwritten --resolution flag
#   -f, --fps FPS         the target output frame-per-second
#   -m, --mode {1,2,3}    1 = normal, 2 = compress, 3 = halved
#   -o, --output OUTPUT   output destination, default to ./data/out.dur
#   -d, --dither          Use Floyd-Steinberg dithering
# 
# Originally, this software is targetted for Ly (a screen manager for Linux)
```

## III. Usage

**Note:** Some part of this usage guide is built intentionally for [Ly (a screen manager for Linux)](https://codeberg.org/fairyglade/ly/), which will be noted with asterisk "*"

**1.** Download your video and put it somewhere, saying `/path/to/video`

**2.** Call the converter

```bash
dc -c 240 -r 150 -f 5 -o /path/to/output /path/to/video
```

Here, specify your:

+ Resolution with flag `--row` and `--col` or flag `--resolution`.

    Recommending 240x150 *

+ (Optionally) FPS with flag `--fps`, this flag will downsample your video, or in other word, slicing your video to reduce the size of the output. 

    Recommending 5 FPS for video under 10 secs and 1-2 for longer. *

+ (Optionally) the output path with `--output`, if it is not specified, default to `./data/out.dur`

+ (Optionally) the quantizing mode with `--mode`, more specific:

    + `--mode 1` ~ normal, just map pixel-by-pixel to each console character

    + `--mode 2` ~ compress, see [this section](#the-upper-half-trick-not-working-for-now)

    + `--mode 3` ~ halved, see [this section](#the-workaround-of-current-issue)

+ (Optionally) using the [Floyd-Steinberg dithering](https://en.wikipedia.org/wiki/Floyd%E2%80%93Steinberg_dithering) with flag `--dither`. Without Floyd-Steinberg dithering, the result may return darker but also smoother.

**Note:** The input and output path must be the path to input and output **FILE, not DIRECTORY**

**3.** Wait for it running:

```bash
dc -c 240 -r 150 -f 5 data/blackhole.mp4
# 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 105/104.58333333333334 [00:03<-00:00, 27.24it/s]
# Done :D
```

**4.** Grab the result :D

## IV. For previewing with durdraw

The durdraw has a known bug that it still expects the old internal format while this project is built based on newer format, which will create a conflict. In order to preview the output, please use the dev branch. [More info on this](https://github.com/durdraw/durdraw/issues/131).