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

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

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:

pip install dur_converter

Or

uv add dur_converter

Then calling it with using dc keyword:

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

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), which will be noted with asterisk "*"

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

2. Call the converter

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

  • --mode 3 ~ halved, see this section

• (Optionally) using the Floyd-Steinberg 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:

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.