Metadata-Version: 2.1
Name: pixelfuse
Version: 2.0.0
Summary: Convert any file to video and video to file
Home-page: https://github.com/TheTS-labs/PixelFuse
License: GPL-3.0
Keywords: video,file,converter
Author: Roman
Author-email: romantovt31@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: ffmpegio (>=0.8.3,<0.9.0)
Requires-Dist: numpy (>=1.24.2,<2.0.0)
Requires-Dist: opencv-python (>=4.7.0.72,<5.0.0.0)
Requires-Dist: typer[all] (>=0.7.0,<0.8.0)
Project-URL: Repository, https://github.com/TheTS-labs/PixelFuse
Description-Content-Type: text/markdown

# 📄🔄🎞️ PixelFuse

Convert any file to video and video to file.

**WARNING: videos created from files are extremely fragile**

## 💿 Installation

* Set up using `pip`:
```bash
pip install pixelfuse
```
* Install from `Git`:
```bash
pip install git+https://github.com/TheTS-labs/PixelFuse.git
```

## 🎬 Usage

### Convert file to video(`fileToVideo`)

To convert a file into a video just write the following command:
```bash
python -m pixelfuse fileToVideo "test/example.text.txt"
```

Where ["test/example.text.txt"](./test/example.text.txt) the file you want to convert to video

As output you get the file `output.avi` - video 640x480, 1.0 FPS, codec HFYU [like this](https://drive.google.com/file/d/1OTZ9rF-6SI73BiLEwY4gJeJ2RVddLsfn/edit)

As for the parameters:
* `path: Path` - mandatory, the path to the file you want to convert
* `fps: float` - frame rate, default is `1.0`
* `width: int` - Video length, default is `480px`
* `height: int` - Video height, `640px` by default
* `fourcc: str` - Codec, a string of 4 characters, **WARNING: Use lossless codecs ONLY**, default is "`HFYU`".
* `output: Path` - Path to output file, default is "`output.avi`", **note you need to use file extension compatible with codec, for example if you use `HFYU` codec you can NOT specify `output` as `output.mp4`**
* `verbose: int` - Output level, from 0 to 3, default is 2

### 🆕 Convert files to video(`filesToVideo`)

To convert a file into a video just write the following command:
```bash
python -m pixelfuse filesToVideo "test/example.text.txt" "test/example.image.jpg"
```

Where ["test/example.text.txt"](./test/example.text.txt) and ["test/example.image.jpg"](./test/example.image.jpg) the files you want to convert to video

This command will create a tar.gz archive which will later convert to a video, and delete the archive

This command will also create a hash map in which it will write the hash of **each** file. Then `convertToFile` unpacks all files and checks them according to this map

As output you get the file `output.avi` - video 640x480, 1.0 FPS, codec HFYU [like this](https://drive.google.com/file/d/1OTZ9rF-6SI73BiLEwY4gJeJ2RVddLsfn/edit)

As for the parameters:
* `paths: list[Path]` - mandatory, the paths to the files you want to convert
* `fps: float` - frame rate, default is `1.0`
* `width: int` - Video length, default is `480px`
* `height: int` - Video height, `640px` by default
* `fourcc: str` - Codec, a string of 4 characters, **WARNING: Use lossless codecs ONLY**, default is "`HFYU`".
* `output: Path` - Path to output file, default is "`output.avi`", **note you need to use file extension compatible with codec, for example if you use `HFYU` codec you can NOT specify `output` as `output.mp4`**
* `verbose: int` - Output level, from 0 to 3, default is 2

### Convert video to file(`videoToFile`)

To get your file(s) back now you need to use this command:
```bash
python -m pixelfuse videoToFile "test/example.video.avi"
```

Where ["test/example.video.avi"](./test/example.video.avi) is the video you want to convert into file(s)

As output, you will get the file with the name it was converted into a video. For example, if you converted the file "example.image.jpg", when you convert the video back to a file you get a file named example.image.jpg

Or a folder with files, if you converted several files. By default, the folder name is the name of the video file without path or extension, but you can specify something else with the `exctractDir` parameter

Regarding the parameters:
* `path: Path` - Mandatory, the path to the video you want to convert back to a file
* `verbose: int` - Output level, from 0 to 2, default is 2
* `exctractDir: str` - Path to extract archive files

## ⚠️ Warning

Because of the way this converter works, the video output is **very, very** fragile

In order for you to be able to convert the file back, every pixel **MUST remain unchanged**, that is what you should avoid:
* Use ONLY lossless codecs, as all other codecs corrupt the pixels. E.g. FFMPEG `FFV1`, Huffman `HFYU`, Lagarith `LAGS`, etc.
* Do not convert videos to other formats, as this will most likely cause pixel damage
* Keep in mind that if you upload videos to YouTube, it will re-encode the video(and, guess what, damage the pixels), so if you want to download videos from YouTube, you'll need to use [Google Takeout](https://takeout.google.com/)
* Do not trim the video, it will trim some of the information, and therefore the file you converted
* Do not apply filters to the video, for example. Anything that can change pixels will damage the file and you won't be able to decode it
* Never convert zip archives, for some unknown reason the decoder (or encoder) cannot handle these archives properly, if you want to convert multiple files you better use the `filesToVideo` command

