{"id":21093807,"url":"https://github.com/umactually/asciipixels","last_synced_at":"2026-05-12T16:05:27.871Z","repository":{"id":132735770,"uuid":"524850906","full_name":"UmActually/asciipixels","owner":"UmActually","description":"Generate dynamic ASCII art with images and videos.","archived":false,"fork":false,"pushed_at":"2023-01-18T09:03:43.000Z","size":918,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-14T06:44:22.024Z","etag":null,"topics":["ascii-art","ffmpeg","imagemagick","multiprocessing","pypi-package","python","python-library"],"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/UmActually.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":"2022-08-15T04:06:15.000Z","updated_at":"2023-01-07T18:20:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"4a332a76-a2b0-4a27-8a19-78af178212df","html_url":"https://github.com/UmActually/asciipixels","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UmActually%2Fasciipixels","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UmActually%2Fasciipixels/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UmActually%2Fasciipixels/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UmActually%2Fasciipixels/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UmActually","download_url":"https://codeload.github.com/UmActually/asciipixels/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243538113,"owners_count":20307101,"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":["ascii-art","ffmpeg","imagemagick","multiprocessing","pypi-package","python","python-library"],"created_at":"2024-11-19T22:12:38.019Z","updated_at":"2026-05-12T16:05:22.833Z","avatar_url":"https://github.com/UmActually.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# asciipixels\n\n### Generate dynamic ASCII art with images and videos.\n\nBy Leonardo - UmActually\n\n`asciipixels` is a quick-and-easy library for converting **images** and **videos** to highly customizable [**ASCII art**](#cool-but-what-is-ascii-art). The library has four primary functions that do all the asciification work, and save the result as an image, gif, or video: `image.asciify()`, `image.dynamic_asciify()`, `video.asciify()` and `video.dynamic_asciify()`.\n\nFor a more granular control of what the program should do, the `CoreAsciifier` class (the class behind the primary asciipixels functions) and wrapper functions for both ImageMagick and FFmpeg are also available.\n\n### What Is 'Dynamic' \n\nWhat really sets the asciipixels library apart is the _dynamic_ functionality. In the functions `image.dynamic_asciify()` and `video.dynamic_asciify()` some parameters can change over time. The user can pass **callables** that receive the frame number and return the parameter value, rather than passing the hard-coded value itself. In the example below, the `definition` parameter increases by 16 units every frame. It is modeled by a very simple `lambda` expression.\n\n![Bigweld ASCII Art](https://github.com/UmActually/asciipixels/raw/main/src/asciipixels/resources/example.gif)\n\n### Basic Usage\n\n_Note: asciipixels **depends** on two particular command-line software: **ImageMagick** and **FFmpeg**. If you're a CLI nerd and already have these installed, then go ahead with this guide. If not, go to the [Installation](#installation) section._\n\nUse the corresponding function depending on your use case:\n\n- `image.asciify()` converts image to image. The generated ASCII art is returned as a string and optionally saved in a txt.\n\n- `image.dynamic_asciify()` converts image to gif or mp4 video. Supports dynamic parameters.\n\n- `video.asciify()` converts video to video.\n\n- `video.dynamic_asciify()` converts video to video. Supports dynamic parameters.\n\nAll four have the `path` of the input file as the first argument. The rest of the arguments all have **default values**. Something along these lines is enough to get you started:\n\n```python\nimport asciipixels as ap\nap.image.asciify('foo.png')\n```\n\nThis will generate a new asciified image named `foo2.png`.\n\nIt is important to note that **all functions** except `image.asciify()` **require** a `if __name__ == '__main__'` check in the top level of the user code (_unless_ you are using interactive python on the command line). This is because the library uses **multiprocessing** to speed up frame generation. So, in order to asciify a video, for example, you can do the following:\n\n```python\nimport asciipixels as ap\nif __name__ == '__main__':\n    ap.video.asciify('foo.mp4')\n```\n\nThe most important **parameter** to play around with is the `definition`. It is simply the number of characters in the **horizontal** axis. Defaults to 100 in all functions. Set it too high and the ASCII art will just look like art. Set it too low and it will just look like ASCII.\n\nAlso, keep in mind that you can set the **output resolution** of the image/video. The output dimensions approximate the input dimensions by default, but you can change that with the `out_width` argument.\n\nLastly, if you decide to work with **dark text** on a **light background**, remember to set `reverse_chars` to `True` in order to correct the pixel-to-ASCII mapping.\n\nAs a final example, I made the Bigweld gif in the [What Is 'Dynamic'](#what-is-dynamic) section with the following code:\n\n```python\nimport asciipixels as ap\n\nif __name__ == '__main__':\n    ap.image.dynamic_asciify(\n        'ceo.png',\n        bg_color=255,\n        txt_color=0,\n        definition=lambda f: f * 16,\n        fps=2,\n        frame_count=7,\n        out_width=1000,\n        reverse_chars=True\n    )\n```\n\nThe complete list of parameters/arguments of a given primary function can be found in its documentation.\n\n---\n\n## Installation\n\nTo install asciipixels, use **pip** in the terminal:\n\n**Windows**\n```commandline\npip install asciipixels\n```\n\n**macOS / Linux**\n```commandline\npython3 -m pip install asciipixels\n```\n\nAsciipixels has two **dependencies** that aren't installed automatically. These are **ImageMagick**, for image manipulation, and **FFmpeg**, for video and audio manipulation. You can download them from their **official sites** or by using **Homebrew** (if applicable).\n\n[Install ImageMagick Here](https://imagemagick.org/script/download.php)\n\n[Install FFmpeg Here](https://ffmpeg.org/download.html)\n\n---\n\n## Cool, But What Is ASCII Art\n\nASCII art is simply the representation of images (or video) with **characters** and letters. This art can be composed by using characters that match either the **brightness** or **contour** of a part of an image. This library works with the brightness aspect.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumactually%2Fasciipixels","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fumactually%2Fasciipixels","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumactually%2Fasciipixels/lists"}