ascii-art-python 0.2.1__tar.gz → 0.2.3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/LICENSE +21 -21
- {ascii_art_python-0.2.1/ascii_art_python.egg-info → ascii_art_python-0.2.3}/PKG-INFO +250 -207
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/README.md +215 -173
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/ascii_art_python/__init__.py +2 -2
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/ascii_art_python/new_school.py +344 -340
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3/ascii_art_python.egg-info}/PKG-INFO +250 -207
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/ascii_art_python.egg-info/requires.txt +3 -0
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/pyproject.toml +56 -55
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/setup.cfg +4 -4
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/MANIFEST.in +0 -0
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/ascii_art_python/assets/fonts/KreativeSquare.ttf +0 -0
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/ascii_art_python/assets/fonts/OFL.txt +0 -0
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/ascii_art_python.egg-info/SOURCES.txt +0 -0
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/ascii_art_python.egg-info/dependency_links.txt +0 -0
- {ascii_art_python-0.2.1 → ascii_art_python-0.2.3}/ascii_art_python.egg-info/top_level.txt +0 -0
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 Guillem Prieur
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Guillem Prieur
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -1,207 +1,250 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: ascii_art_python
|
|
3
|
-
Version: 0.2.
|
|
4
|
-
Summary: A Python library and CLI tool for converting images and videos into ASCII art.
|
|
5
|
-
Author-email: Guillem Prieur <prieurguillem38@gmail.com>
|
|
6
|
-
Project-URL: Homepage, https://gitlab.pprriieeuurr.fr/guill_prieur/ascii-art-python
|
|
7
|
-
Project-URL: Bug Tracker, https://gitlab.pprriieeuurr.fr/guill_prieur/ascii-art-python/-/issues
|
|
8
|
-
Project-URL: Source Code, https://gitlab.pprriieeuurr.fr/guill_prieur/ascii-art-python
|
|
9
|
-
Keywords: ascii,ascii-art,image-to-ascii,video-to-ascii,cli,terminal,terminal-graphics,generator,converter
|
|
10
|
-
Classifier: Development Status :: 4 - Beta
|
|
11
|
-
Classifier: Intended Audience :: Developers
|
|
12
|
-
Classifier: Intended Audience :: End Users/Desktop
|
|
13
|
-
Classifier: Topic :: Multimedia :: Graphics
|
|
14
|
-
Classifier: Topic :: Multimedia :: Video
|
|
15
|
-
Classifier: Topic :: Terminals
|
|
16
|
-
Classifier: Environment :: Console
|
|
17
|
-
Classifier: Programming Language :: Python :: 3
|
|
18
|
-
Classifier: Programming Language :: Python :: 3.9
|
|
19
|
-
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
-
Classifier: License :: OSI Approved :: MIT License
|
|
23
|
-
Classifier: Operating System :: OS Independent
|
|
24
|
-
Requires-Python: >=3.9
|
|
25
|
-
Description-Content-Type: text/markdown
|
|
26
|
-
License-File: LICENSE
|
|
27
|
-
Requires-Dist: pillow>=10.0.0
|
|
28
|
-
Requires-Dist: tqdm>=4.65.0
|
|
29
|
-
Requires-Dist: opencv-python-headless>=4.8.0
|
|
30
|
-
Requires-Dist: moviepy>=1.0.3
|
|
31
|
-
Requires-Dist: numpy>=1.24.0
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
[](https://pypi.org/project/ascii-art-python/)
|
|
40
|
+
[](https://pypi.org/project/ascii-art-python/)
|
|
41
|
+
[](https://pypi.org/project/ascii-art-python/)
|
|
42
|
+
[](https://opensource.org/licenses/MIT)
|
|
43
|
+
|
|
44
|
+
</div>
|
|
45
|
+
|
|
46
|
+
This module provides advanced tools for converting classic images and videos into ASCII Art. It allows exporting the results as text files, new images, or new videos (with or without audio), and even playing videos directly in your terminal.
|
|
47
|
+
|
|
48
|
+
## 👀 Examples
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
@@@@@@@@@@@@@@@@@@@@@@@@@@$&#{{{{{{{{{{{#&$@@@@@@@@@@@@@@@@@@@@@@@@@@@
|
|
52
|
+
@@@@@@@@@@@@@@@@@@@@@&{*********{{{{{{{{{{{{{*{#@@@@@@@@@@@@@@@@@@@@@@
|
|
53
|
+
@@@@@@@@@@@@@@@@@@@#**********{{{{{{{{{{{{{{{{{{{{$@@@@@@@@@@@@@@@@@@@
|
|
54
|
+
@@@@@@@@@@@@@@@@@@#***{$@@@${*{{{{{{{{{{{{{{{{{{{{{&@@@@@@@@@@@@@@@@@@
|
|
55
|
+
@@@@@@@@@@@@@@@@@@{***&@@@@@&*{{{{{{{{{{{{{{{{{{{{{{@@@@@@@@@@@@@@@@@@
|
|
56
|
+
@@@@@@@@@@@@@@@@@@{***{$@@@${{{{{{{{{{{{{{{{{{{{{{{{@@@@@@@@@@@@@@@@@@
|
|
57
|
+
@@@@@@@@@@@@@@@@@@{***{****{{{{{{{{{{{{{{{{{{{{{{{{{@@@@@@@@@@@@@@@@@@
|
|
58
|
+
@@@@@@@@@@@@@@@@@@{*************{{{{{{{{{{{{{{{{{{{{@@@@@@@@@@@@@@@@@@
|
|
59
|
+
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@#{{{{{{{{{{{{{{{{@@@@@@@@@@@@@@@@@@
|
|
60
|
+
@@@@@@@@&#{{{{{{{{{{{{#############{{{{{{{{{{{{{{{{{@@;.:::.::=#@@@@@@
|
|
61
|
+
@@@@${********{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{@@;.::::::::.=@@@@
|
|
62
|
+
@@@{********{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{@@;.::::::::::.#@@
|
|
63
|
+
@$********{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{@@;.::::::::::::#@
|
|
64
|
+
@{******{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{@@;:::::::::::::;@
|
|
65
|
+
&*****{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{&@$:::::::::::::::{
|
|
66
|
+
{***{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{$@@=.::::::::::::::=
|
|
67
|
+
{*{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{#$@@@=.::::::::::::::::
|
|
68
|
+
{{{{{{{{{{{{{{{{{{{{{#$@@@@@@@@@@@@@@@@@@@@@@@@@@$=.::::::::::::::::::
|
|
69
|
+
{{{{{{{{{{{{{{{{{{#@@@@&*=;;;;;;;;;;;;;;;;;;;;:..:::::::::::::::::::::
|
|
70
|
+
{{{{{{{{{{{{{{{{{$@@#:........:::::::::::::::::::::::::::::::::::::::;
|
|
71
|
+
#*{{{{{{{{{{{{{{$@@:........:::::::::::::::::::::::::::::::::::::::::(
|
|
72
|
+
${{{{{{{{{{{{{{{@@=.......:::::::::::::::::::::::::::::::::::::::::::&
|
|
73
|
+
@#*{{{{{{{{{{{{{@$:.....::::::::::::::::::::::::::::::::::::::::::::*@
|
|
74
|
+
@@{{{{{{{{{{{{{{@$:...:::::::::::::::::::::::::::::::::::::::::::::(@@
|
|
75
|
+
@@@#*{{{{{{{{{{{@$:..:::::::::::::::::::::::::::::::::::::::::::::&@@@
|
|
76
|
+
@@@@@#{{{{{{{{{{@$:.:::::::::::::::.:::::::::::::::::::::::::::($@@@@@
|
|
77
|
+
@@@@@@@@@$$$$$$@@$:.:::::::::::::.=@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
|
|
78
|
+
@@@@@@@@@@@@@@@@@$:.:::::::::::::::================*@@@@@@@@@@@@@@@@@@
|
|
79
|
+
@@@@@@@@@@@@@@@@@$:::::::::::::::::::::::::::::::::=@@@@@@@@@@@@@@@@@@
|
|
80
|
+
@@@@@@@@@@@@@@@@@$:::::::::::::::::::::::::({(:::::=@@@@@@@@@@@@@@@@@@
|
|
81
|
+
@@@@@@@@@@@@@@@@@$:::::::::::::::::::::::(@@@@@(:::=@@@@@@@@@@@@@@@@@@
|
|
82
|
+
@@@@@@@@@@@@@@@@@@;.:::::::::::::::::::::*@@@@@*:::=@@@@@@@@@@@@@@@@@@
|
|
83
|
+
@@@@@@@@@@@@@@@@@@$::::::::::::::::::::::::*#*:::::#@@@@@@@@@@@@@@@@@@
|
|
84
|
+
@@@@@@@@@@@@@@@@@@@@#:.::::::::::::::::::::::::::(@@@@@@@@@@@@@@@@@@@@
|
|
85
|
+
@@@@@@@@@@@@@@@@@@@@@@@$*;::::::::::::::::::;(#@@@@@@@@@@@@@@@@@@@@@@@
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
## 🔧 Features
|
|
91
|
+
|
|
92
|
+
- Image to ASCII conversion
|
|
93
|
+
- Video to ASCII animation with sound extraction
|
|
94
|
+
- Play video directly in the terminal
|
|
95
|
+
- Export to .txt, .png, .mp4, or .avi
|
|
96
|
+
|
|
97
|
+
## 📦 Installation
|
|
98
|
+
|
|
99
|
+
You can install the module via pip:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
pip install ascii-art-python
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## 🚀 Basic Usage
|
|
106
|
+
|
|
107
|
+
To use the module, import it as follows:
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
import ascii_art_python as aap
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## 📚 API Reference
|
|
114
|
+
|
|
115
|
+
### 1. Enumerations (Enums)
|
|
116
|
+
|
|
117
|
+
These enumerations are used to define the export format or quality.
|
|
118
|
+
|
|
119
|
+
`aap.new_school.ExportType` : Defines the file type when exporting an image or a video.
|
|
120
|
+
|
|
121
|
+
- `aap.new_school.ExportType.IMAGE_FILE` (0): Exports as classic media (PNG image or MP4/AVI video).
|
|
122
|
+
|
|
123
|
+
- `aap.new_school.ExportType.TEXT_FILE` (1): Exports as a plain text file (.txt or .vid.txt).
|
|
124
|
+
|
|
125
|
+
`aap.new_school.VideoAscii.ExportQuality` : Defines the video compression quality (and the codec used) during export.
|
|
126
|
+
|
|
127
|
+
- `aap.new_school.VideoAscii.ExportQuality.LOW` (0): Low quality (mp4v codec, .mp4 format).
|
|
128
|
+
|
|
129
|
+
- `aap.new_school.VideoAscii.ExportQuality.HIGH` (1): High quality (FFV1 codec, .avi format).
|
|
130
|
+
|
|
131
|
+
### 2. Class `ImageAscii`
|
|
132
|
+
|
|
133
|
+
Manages the conversion and manipulation of a still image into ASCII art.
|
|
134
|
+
|
|
135
|
+
#### Constructors
|
|
136
|
+
|
|
137
|
+
- `ImageAscii(image: PIL.Image.Image, max_size: int = 100_000, grid: list[str] = None)`
|
|
138
|
+
- Description: Initializes an instance from an image object of the PIL/Pillow library.
|
|
139
|
+
- Parameters:
|
|
140
|
+
- `image`: The source image (Pillow).
|
|
141
|
+
- `max_size`: The maximum size (number of pixels/characters) for the generated ASCII image.
|
|
142
|
+
- `grid`: The list of characters to use (from darkest to lightest). If None, uses the default grid.
|
|
143
|
+
- `ImageAscii.from_path(path: str, max_size: int = 10_000, grid: list[str] = None) -> ImageAscii`
|
|
144
|
+
- Description: Convenient class method to instantiate directly from a file path.
|
|
145
|
+
|
|
146
|
+
#### Methods
|
|
147
|
+
|
|
148
|
+
- `to_list() -> list[str]`
|
|
149
|
+
- Description: Converts the image into a list of strings (one string per line).
|
|
150
|
+
- `to_image() -> PIL.Image.Image`
|
|
151
|
+
- Description: Generates and returns a new Pillow image where the ASCII has been drawn using a specific font (KreativeSquare.ttf by default).
|
|
152
|
+
- `export(filename: str = "mika_export", mode: ExportType = 0) -> None`
|
|
153
|
+
- Description: Exports the generated image to the disk.
|
|
154
|
+
- Parameters:
|
|
155
|
+
- `filename`: The target file name (without extension).
|
|
156
|
+
- `mode`: If ExportType.IMAGE_FILE, saves a .png. If `ExportType.TEXT_FILE`, saves a .txt.
|
|
157
|
+
|
|
158
|
+
### 3. Class VideoAscii
|
|
159
|
+
|
|
160
|
+
Manages the conversion of a complete video into an ASCII animation.
|
|
161
|
+
|
|
162
|
+
#### Constructor
|
|
163
|
+
|
|
164
|
+
- `VideoAscii(path: str, fps: int = 10, frame_size: int = 12_000)`
|
|
165
|
+
- Description: Prepares a video for ASCII processing.
|
|
166
|
+
- Parameters:
|
|
167
|
+
- `path`: Path to the source video.
|
|
168
|
+
- `fps`: Target frames per second for the ASCII render (maximum framerate).
|
|
169
|
+
- `frame_size`: Maximum size of each processed frame.
|
|
170
|
+
|
|
171
|
+
#### Properties
|
|
172
|
+
|
|
173
|
+
- fps -> float: Retrieves the native FPS of the source video.
|
|
174
|
+
- size -> tuple[int, int]: Retrieves the dimensions (width, height) of the exported ASCII video.
|
|
175
|
+
|
|
176
|
+
#### Methods
|
|
177
|
+
|
|
178
|
+
- `export(filename: str = "mika_export", export_type: ExportType = 0, quality: ExportQuality = 0, sound: bool = False)`
|
|
179
|
+
- Description: Exports the processed video.
|
|
180
|
+
- Parameters:
|
|
181
|
+
- `filename`: The target file name (without extension).
|
|
182
|
+
- `export_type`: If `IMAGE_FILE`, generates a video. If `TEXT_FILE`, generates a custom animated text file (.vid.txt).
|
|
183
|
+
- `quality`: Determines the generated video codec if the export is a video file.
|
|
184
|
+
- `sound`: If True, extracts audio from the source and adds it to the final exported video.
|
|
185
|
+
- `print_in_terminal() -> None`
|
|
186
|
+
- Description: Plays the source video as an ASCII animation directly in the terminal console, respecting the framerate limit (max_fps).
|
|
187
|
+
|
|
188
|
+
#### Static Methods
|
|
189
|
+
|
|
190
|
+
- `VideoAscii.print_from_txt(txt: str)`
|
|
191
|
+
- Description: Reads and displays in the terminal the content of a .vid.txt file previously generated by the export(export_type=ExportType.TEXT_FILE) method.
|
|
192
|
+
- `VideoAscii.transfer_audio(source_video_path: str, target_video_path: str, output_path: str)`
|
|
193
|
+
- Description: Extracts audio from `source_video_path` and applies it to `target_video_path` to generate `output_path`.
|
|
194
|
+
|
|
195
|
+
## 💡 Usage Examples
|
|
196
|
+
|
|
197
|
+
### Example 1: Convert and Export an Image
|
|
198
|
+
|
|
199
|
+
```python
|
|
200
|
+
import ascii_art_python as aap
|
|
201
|
+
# Create an object from a local file
|
|
202
|
+
my_image = aap.new_school.ImageAscii.from_path("my_image.jpg", max_size=50_000)
|
|
203
|
+
|
|
204
|
+
# Display ASCII in the console
|
|
205
|
+
print(my_image)
|
|
206
|
+
|
|
207
|
+
# Export the ASCII image in text format (.txt)
|
|
208
|
+
my_image.export("text_result", mode=aap.new_school.ExportType.TEXT_FILE)
|
|
209
|
+
|
|
210
|
+
# Export the ASCII image as a new readable image (.png)
|
|
211
|
+
my_image.export("image_result", mode=aap.new_school.ExportType.IMAGE_FILE)
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
### Example 2: Play a Video in the Terminal
|
|
215
|
+
|
|
216
|
+
```python
|
|
217
|
+
import ascii_art_python as aap
|
|
218
|
+
|
|
219
|
+
my_video = aap.new_school.VideoAscii("my_video.mp4", fps=15, frame_size=8_000)
|
|
220
|
+
|
|
221
|
+
# Play the animation live in the terminal
|
|
222
|
+
my_video.print_in_terminal()
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### Example 3: Convert a Video with Sound
|
|
226
|
+
|
|
227
|
+
```python
|
|
228
|
+
import ascii_art_python as aap
|
|
229
|
+
|
|
230
|
+
my_video = aap.new_school.VideoAscii("my_video.mp4", fps=24, frame_size=15_000)
|
|
231
|
+
|
|
232
|
+
# Export the video with sound in MP4 format (Low Quality by default)
|
|
233
|
+
my_video.export(
|
|
234
|
+
filename="final_ascii_video",
|
|
235
|
+
export_type=aap.new_school.ExportType.IMAGE_FILE,
|
|
236
|
+
sound=True
|
|
237
|
+
)
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
## ⚠️ Troubleshooting
|
|
241
|
+
|
|
242
|
+
### Important Note Regarding OpenCV Dependencies
|
|
243
|
+
|
|
244
|
+
This project uses **`opencv-python-headless`** for background image processing.
|
|
245
|
+
|
|
246
|
+
Please be aware that installing both `opencv-python` (the standard version with GUI features) and `opencv-python-headless` in the **same Python environment** will cause conflicts. Doing so may break OpenCV's display capabilities (such as `cv2.imshow()`) in your other projects.
|
|
247
|
+
|
|
248
|
+
**To avoid any issues, it is highly recommended to:**
|
|
249
|
+
- **Use a Virtual Environment:** Always install this project inside an isolated virtual environment (using `venv`, `conda`, or Docker).
|
|
250
|
+
- **Check Existing Packages:** If you are installing globally and already have `opencv-python` installed, please remove it first (`pip uninstall opencv-python`) before installing this project's requirements.
|