{"id":26600870,"url":"https://github.com/iapetus-11/to-ascii","last_synced_at":"2025-04-06T20:08:40.242Z","repository":{"id":47918791,"uuid":"289816796","full_name":"Iapetus-11/To-ASCII","owner":"Iapetus-11","description":"Convert videos, images, gifs, and even live video to ASCII art! (Now with color support)","archived":false,"fork":false,"pushed_at":"2025-03-10T11:38:48.000Z","size":384,"stargazers_count":66,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-06T20:08:34.481Z","etag":null,"topics":["2ascii","ascii","ascii-art","ascii-video","converter","gif","image","image-processing","text","to-ascii","toascii","video","video-2-ascii","video-processing","video-to-ascii"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Iapetus-11.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-24T03:18:38.000Z","updated_at":"2025-03-10T17:52:11.000Z","dependencies_parsed_at":"2023-12-16T20:09:42.038Z","dependency_job_id":"ef80e5b0-e19d-441e-8993-7a7cd5ac363f","html_url":"https://github.com/Iapetus-11/To-ASCII","commit_stats":{"total_commits":440,"total_committers":6,"mean_commits":73.33333333333333,"dds":0.2318181818181818,"last_synced_commit":"4746487d2aece8c43c6c2d2cd3a9de16d34d329d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iapetus-11%2FTo-ASCII","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iapetus-11%2FTo-ASCII/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iapetus-11%2FTo-ASCII/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iapetus-11%2FTo-ASCII/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Iapetus-11","download_url":"https://codeload.github.com/Iapetus-11/To-ASCII/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247543589,"owners_count":20955865,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2ascii","ascii","ascii-art","ascii-video","converter","gif","image","image-processing","text","to-ascii","toascii","video","video-2-ascii","video-processing","video-to-ascii"],"created_at":"2025-03-23T18:35:50.924Z","updated_at":"2025-04-06T20:08:40.193Z","avatar_url":"https://github.com/Iapetus-11.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# To-ASCII ![Code Quality](https://www.codefactor.io/repository/github/iapetus-11/to-ascii/badge/master) ![PYPI Version](https://img.shields.io/pypi/v/to-ascii.svg) ![PYPI Downloads](https://img.shields.io/pypi/dw/to-ascii?color=0FAE6E)\n*Converts videos, images, gifs, and even live video into ascii art!*\n\n- Works on most image and video types including GIFs\n- Works on LIVE VIDEO\n\n\u003cimg src=\"https://user-images.githubusercontent.com/38477514/180253533-e0725ba5-6c6d-408d-a643-ff02f021cff8.png\" width=\"360\" /\u003e \u003cimg src=\"https://user-images.githubusercontent.com/38477514/180254306-9e8eca93-ea38-47bf-b1c2-72ad75244604.png\" width=\"360\" /\u003e \u003cimg src=\"https://user-images.githubusercontent.com/38477514/180251469-8826a23d-a292-42b2-83c6-c9a637214b5e.png\" width=\"360\" /\u003e \u003cimg src=\"https://user-images.githubusercontent.com/38477514/180251666-49b07f5f-da3c-4790-85b9-ba72dbca606b.png\" width=\"360\" /\u003e\n\n[[DEMO SITE]](https://ascii.iapetus11.me/) [\\[Video Example\\]](https://www.youtube.com/watch?v=S5-_BzdrOkQ) [\\[Video Example 2\\]](https://www.youtube.com/watch?v=eX4pYQjCyYg) \n\n## Installation\nVia pip:\n```\npip install to-ascii[speedups,cli]\n```\n- The `speedups` extra is recommended, [see below](#extensions)\n- The `cli` extra is required for CLI use (it adds [click](https://pypi.org/project/click/) as a dependency)\n\n## CLI Usage\n```\nUsage: toascii [OPTIONS] {image|video} SOURCE {colorconverter|colorconverternim|grayscaleconverter|grayscaleconverternim|htmlcolorconverter|htmlcolorconverternim}\n\nOptions:\n  -g, --gradient TEXT\n  -w, --width INTEGER RANGE       [x\u003e=1]\n  -h, --height INTEGER RANGE      [x\u003e=1]\n  --x-stretch, --xstretch FLOAT RANGE\n                                  [x\u003e0.0]\n  --y-stretch, --ystretch FLOAT RANGE\n                                  [x\u003e0.0]\n  --saturation FLOAT RANGE        [-1.0\u003c=x\u003c=1.0]\n  --contrast FLOAT RANGE          [0.0\u003c=x\u003c=1.0]\n  --blur INTEGER RANGE            [x\u003e=2]\n  --loop\n  --help                          Show this message and exit.\n```\n\n### CLI Examples\n```bash\n# live video\ntoascii video 0 colorconverternim -h 103 --x-stretch 3.5 --blur 10 --contrast 0.01 --saturation 0.0\n```\n```bash\ntoascii image sammie.jpg grayscaleconverter -h 32 --x-stretch 2.1 --blur 20 --contrast 0.0 --saturation 0.0\n```\n```bash\ntoascii video IMG_7845.MOV colorconverternim -h 81 --x-stretch 2.5 --blur 15 --contrast 0.01 --saturation 0.0 --loop\n```\n\n## API Reference\n### [Usage Examples Folder](examples)\n#### *class* [`ConverterOptions`](toascii/converters/options.py)(\\*, `gradient`: *`str`*, `width`: *`Optional[int]`*, `height`: *`Optional[int]`*, `x_stretch`: *`float`*, `y_stretch`: *`float`*, `saturation`: *`float`*, `contrast`: *`Optional[float]`*)\n- *pydantic model for converter options*\n- Parameters / Attributes:\n    - `gradient`: *`str`* - *string containing the characters the converter will use when converting the image to ascii*\n        - must be at least one character\n    - `width`: *`Optional[int]`* - *width in characters of the final converted image*\n        - default value is `None`\n        - must be greater than `0`\n    - `height`: *`Optional[int]`* - *height in characters of the final converted image*\n        - default value is `None`\n        - must be greater than `0`\n    - `x_stretch`: *`float`* - *how much to stretch the width by*\n        - default value is `1.0` (which doesn't change the width by anything)\n        - must be greater than `0.0`\n    - `y_stretch`: *`float`* - *how much to stretch the height by*\n        - default value is `1.0` (which doesn't change the height by anything)\n        - must be greater than `0.0`\n    - `saturation`: *`float`* - *how much to adjust the saturation*\n        - default value is `0.5` (which increases the saturation)\n        - must be between `-1.0` and `1.0`, `0.0` is no change to saturation\n    - `contrast`: *`Optional[float]`* - *how much to increase the contrast by*\n        - default value is `None` (which doesn't apply any contrast filter)\n        - must be between `0.0` and `1.0`\n    - `blur`: *`Optional[int]`* - *how much to blur the image by*\n        - default value is `None` (which doesn't apply any blur)\n        - must be greater than `0`\n#### *class* [`ConverterBase`](toascii/converters/base_converter.py)(`options`: *`ConverterOptions`*)\n- *base class for implementing converters*\n- Parameters:\n    - `options`: *`ConverterOptions`* - *Options used when converting media*\n- Methods:\n    - *abstract* `asciify_image`(`image`: *`numpy.ndarray`*) -\u003e *`str`*\n    - `calculate_dimensions`(`initial_height`: *`int`*, `initial_width`: *`int`*) -\u003e *`Tuple[int, int]`*\n    - `apply_opencv_fx`(`image`: *`numpy.ndarray`*, \\*, `resize_dims`: *`Optional[Tuple[int, int]]`*) -\u003e *`numpy.ndarray`*\n- Implementations:\n    - [`GrayscaleConverter`](toascii/converters/grayscale_converter.py) - *converts media to grayscale ascii*\n    - [`GrayscaleConverterNim`](toascii/converters/extensions/grayscale_converter_nim.py) - *converters media to grayscale ascii, see the [Extensions](#extensions) section*\n    - [`ColorConverter`](toascii/converters/color_converter.py) - *converts media to colored ascii using [Colorama](https://pypi.org/project/colorama/)*\n    - [`ColorConverterNim`](toascii/converters/extensions/color_converter_nim.py) - *converts media to colored ascii using [Colorama](https://pypi.org/project/colorama/), see the [Extensions](#extensions) section*\n    - [`HtmlColorConverter`](toascii/converters/html_color_converter.py) - *converts media to ascii in colored html spans*\n    - [`HtmlColorConverterNim`](toascii/converters/extensions/html_color_converter_nim.py) - *converts media to ascii in colored html spans, see the [Extensions](#extensions) section*\n#### *class* [`Image`](toascii/image.py)(`source`: *`Union[str, bytes, IOBase]`*, `converter`: *`BaseConverter`*)\n- *class for converting an image to ascii*\n- Parameters:\n    - `source`: *`Union[str, bytes, IOBase]`* - *the source of the image that is to be loaded and converted*\n        - if `source` is a `str`, it's assumed that it's a path to an image file\n        - if `source` is `bytes` or `IOBase` it's assumed to be the data of an image and is decoded in-memory\n    - `converter`: *`ConverterBase`* - *the converter used to convert the image*\n        - takes anything that implements `ConverterBase`\n- Methods:\n    - `to_ascii`() -\u003e *`str`*\n        - *returns the image converted by the converter*\n    - `view`() -\u003e *`None`*\n        - *prints out the converted image to the console*\n#### *class* [`Video`](toascii/video.py)(`source`: *`Union[str, int, bytes, IOBase]`*, `converter`: *`BaseConverter`*, \\*, `fps`: *`Optional[float]`*, `loop`: *`bool`*)\n- *class for converting a video to ascii*\n- Parameters:\n    - `source`: *`Union[str, int bytes, IOBase]`* - *the source of the video that is to be loaded and converted*\n        - if `source` is a `str`, it's assumed that it's a path to an image file\n        - if `source` is `bytes` or `IOBase` it's assumed to be the data of an image and is written to a temporary file before being loaded and decoded by OpenCV\n        - if `source` is an `int`, it's assumed to be the index of a camera device\n        - see [OpenCV's `VideoCapture`](https://docs.opencv.org/3.4/d8/dfe/classcv_1_1VideoCapture.html) for more information\n    - `converter`: *`ConverterBase`* - *the converter used to convert the image*\n        - takes anything that implements `ConverterBase`\n    - `fps`: *`Optional[float]`* - *the fps to play the video at*\n        - default value is `None`\n        - if `None` then the fps used is fetched from OpenCV's `VideoCapture` API\n    - `loop`: *`bool`* - *whether or not to loop the video when it's done playing*\n        - default value is `False`\n        - if the video source is live, this parameter is ignored\n- Methods:\n    - `get_ascii_frames`() -\u003e *`Generator[str, None, None]`* - *returns a generator which yields each ascii frame as it is converted*\n    - `view`() -\u003e *`None`* - *prints out each frame of the converted video*\n        - if the video source is not live, this method will first generate all frames and cache them in memory for a smoother playback\n        - if the `loop` parameter was set to `True` earlier, then this will play the video and restart it when it finishes unless the source is live\n\n## Extensions\n- For each converter available, there is a separate implementation written in [Nim](https://nim-lang.org/)\n- These implementations are generally orders of magnitude faster than their Python counterparts\n- To use these extensions you must [install Nim](https://nim-lang.org/install.html) and install the `to-ascii[speedups]` package via pip or your package manager of choice\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiapetus-11%2Fto-ascii","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiapetus-11%2Fto-ascii","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiapetus-11%2Fto-ascii/lists"}