curlcast 0.1.0__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.
@@ -0,0 +1,28 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .eggs/
6
+ build/
7
+ dist/
8
+ .venv/
9
+ venv/
10
+
11
+ # Tooling
12
+ .pytest_cache/
13
+ .mypy_cache/
14
+ .ruff_cache/
15
+ .coverage
16
+ htmlcov/
17
+
18
+ # OS
19
+ .DS_Store
20
+ Thumbs.db
21
+
22
+ # Local media fixtures
23
+ *.mp4
24
+ *.mov
25
+ *.webm
26
+ *.mkv
27
+ *.gif
28
+ !tests/**/*.gif
curlcast-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CurlCast Contributors
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.
@@ -0,0 +1,411 @@
1
+ Metadata-Version: 2.5
2
+ Name: curlcast
3
+ Version: 0.1.0
4
+ Summary: Render photos, GIFs, and videos in crisp terminal art with synced audio.
5
+ Project-URL: Homepage, https://github.com/VutukuriEswar/CurlCast
6
+ Project-URL: Repository, https://github.com/VutukuriEswar/CurlCast
7
+ Project-URL: Bug Tracker, https://github.com/VutukuriEswar/CurlCast/issues
8
+ Author: CurlCast Contributors
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: animation,ascii-art,cli,image,terminal,truecolor,video
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Topic :: Multimedia :: Video
23
+ Classifier: Topic :: Terminals
24
+ Classifier: Typing :: Typed
25
+ Requires-Python: >=3.10
26
+ Requires-Dist: imageio-ffmpeg>=0.4.9
27
+ Requires-Dist: numpy>=1.24.0
28
+ Requires-Dist: pillow>=10.0.0
29
+ Requires-Dist: rich>=13.0.0
30
+ Requires-Dist: sounddevice>=0.4.6
31
+ Requires-Dist: typer>=0.12.0
32
+ Provides-Extra: dev
33
+ Requires-Dist: build>=1.0; extra == 'dev'
34
+ Requires-Dist: mypy>=1.8; extra == 'dev'
35
+ Requires-Dist: pytest>=7.0; extra == 'dev'
36
+ Requires-Dist: ruff>=0.5; extra == 'dev'
37
+ Requires-Dist: twine>=5.0; extra == 'dev'
38
+ Description-Content-Type: text/markdown
39
+
40
+ # CurlCast 🎬
41
+
42
+ > Render any **photo, GIF, or video** directly inside your terminal in crisp,
43
+ > high-definition terminal art — with synced audio.
44
+
45
+ ```console
46
+ pip install curlcast
47
+ curlcast demo
48
+ ```
49
+
50
+ No media file, no system `ffmpeg`, no config: `demo` generates a colourful
51
+ NumPy animation so you can verify the install immediately.
52
+
53
+ ---
54
+
55
+ ## Features
56
+
57
+ | Feature | Detail |
58
+ |---|---|
59
+ | **HD block mode** (default) | Unicode `▀` with 24-bit TrueColor — two pixels per character cell, doubling vertical resolution |
60
+ | **ASCII mode** | 70-glyph density ramp with adaptive contrast and optional per-glyph truecolor |
61
+ | **Synced audio** | ffmpeg → PortAudio streaming (sounddevice), with `ffplay` / `mpv` / `afplay` fallbacks |
62
+ | **Drift-corrected playback** | Audio-master clock, absolute frame deadlines, late-frame dropping |
63
+ | **Zero-flicker** | Cursor-home repaint (`ESC[H`), no full-screen clears, `ESC[J` cleanup |
64
+ | **True aspect ratio** | 2:1 cell correction for ASCII, 1:1 pixel pairs for HD |
65
+ | **GIF support** | Per-frame delays and correct compositing via Pillow |
66
+ | **Built-in demo** | Plasma and z-buffered spinning torus, generated with NumPy |
67
+ | **No system ffmpeg** | `imageio-ffmpeg` bundles a portable ffmpeg binary |
68
+ | **Plug-in renderers** | `BaseRenderer` strategy interface + public registry |
69
+
70
+ ---
71
+
72
+ ## Requirements
73
+
74
+ - **Python ≥ 3.10**
75
+ - A terminal with **24-bit TrueColor** (Windows Terminal, iTerm2, most modern
76
+ Linux terminals). Legacy `conhost` works on Windows 10+ because CurlCast
77
+ enables UTF-8 output and virtual terminal processing itself.
78
+ - Audio is optional; `sounddevice` ships with the package and bundles PortAudio.
79
+
80
+ ---
81
+
82
+ ## Installation
83
+
84
+ ```console
85
+ pip install curlcast
86
+ ```
87
+
88
+ From source (editable):
89
+
90
+ ```console
91
+ git clone https://github.com/VutukuriEswar/CurlCast.git
92
+ cd curlcast
93
+ python -m venv .venv
94
+ .venv\Scripts\activate # Windows
95
+ # source .venv/bin/activate # macOS / Linux
96
+ pip install -e ".[dev]"
97
+ ```
98
+
99
+ ---
100
+
101
+ ## Usage
102
+
103
+ ### View a still image
104
+
105
+ ```console
106
+ curlcast view photo.jpg
107
+ curlcast view photo.jpg --mode ascii
108
+ curlcast view photo.jpg --width 120
109
+ curlcast view logo.png --no-color --no-upscale
110
+ ```
111
+
112
+ `view` applies EXIF orientation (phone photos appear upright), fits the image
113
+ inside the terminal without distortion, and never hides the cursor.
114
+
115
+ | Option | Default | Description |
116
+ |---|---|---|
117
+ | `--mode`, `-m` | `hd` | `hd` (half blocks) or `ascii` |
118
+ | `--width`, `-w` | terminal width − 1 | Output width in character columns (`0` = auto) |
119
+ | `--no-color` | off | Monochrome output |
120
+ | `--no-upscale` | off | Do not enlarge images smaller than the terminal |
121
+
122
+ ### Play a video or GIF
123
+
124
+ ```console
125
+ curlcast play video.mp4
126
+ curlcast play video.mp4 --mode ascii --fps 30
127
+ curlcast play video.mp4 --loop --no-audio
128
+ curlcast play animation.gif --loop
129
+ ```
130
+
131
+ | Option | Default | Description |
132
+ |---|---|---|
133
+ | `--mode`, `-m` | `hd` | `hd` or `ascii` |
134
+ | `--width`, `-w` | terminal width − 1 | Output width in columns (`0` = auto) |
135
+ | `--fps` | `20` | Display rate, capped at the source rate (1–120) |
136
+ | `--loop`, `-l` | off | Restart when the file ends |
137
+ | `--no-audio` | off | Mute |
138
+ | `--no-color` | off | Monochrome output |
139
+
140
+ Press **Ctrl+C** to stop. The cursor is always restored, audio is terminated,
141
+ and the decoder process is cleaned up.
142
+
143
+ ### Run the demo
144
+
145
+ ```console
146
+ curlcast demo
147
+ curlcast demo --animation torus --duration 30
148
+ curlcast demo --mode ascii --duration 0
149
+ ```
150
+
151
+ `--duration 0` runs until Ctrl+C. `--animation` accepts `plasma` (default) or
152
+ `torus`.
153
+
154
+ ### Other
155
+
156
+ ```console
157
+ curlcast --version
158
+ curlcast --help
159
+ python -m curlcast demo # same CLI without the console script
160
+ ```
161
+
162
+ ---
163
+
164
+ ## How it works
165
+
166
+ ### Renderers own geometry and encoding
167
+
168
+ `PIXEL_ASPECT` is the number of sampled pixel **rows per character row**, and it
169
+ is the whole aspect-ratio story:
170
+
171
+ | Mode | Sampling grid | Why |
172
+ |---|---|---|
173
+ | `hd` | `cols × (rows × 2)` | Each `▀` cell paints a 1×2 pixel pair, so pixels stay square |
174
+ | `ascii` | `cols × rows` | A glyph cell is already ~2:1 tall, so one glyph per pixel restores the aspect |
175
+
176
+ Getting ASCII backwards is the classic bug: it emits twice the requested rows
177
+ and stretches the picture vertically. The test suite asserts output never
178
+ exceeds the terminal budget for 16:9, 4:3, 1:1, 9:16 and ultrawide sources.
179
+
180
+ **HD encoding** uses foreground colour for the top pixel and background colour
181
+ for the bottom pixel. Both escape sequences are cached by packed colour and
182
+ only re-emitted when the colour changes between neighbouring cells; video has
183
+ long horizontal runs, so this is several times faster than formatting two
184
+ escapes per cell. `--no-color` keeps the full 2-pixel resolution using `' '`,
185
+ `â–€`, `â–„` and `â–ˆ`.
186
+
187
+ **ASCII encoding** clips luminance to its 2nd–98th percentile before mapping to
188
+ the 70-character ramp, with exponential smoothing across frames so video does
189
+ not visibly "pump" when the scene changes.
190
+
191
+ ### Video pipeline
192
+
193
+ ```
194
+ ffmpeg -re -i clip.mp4 -an
195
+ -vf fps=<min(source, target)>,scale=<w>:<h>:flags=lanczos,setsar=1
196
+ -f rawvideo -pix_fmt rgb24 -
197
+ ```
198
+
199
+ 1. `ffmpeg` (bundled by `imageio-ffmpeg`) decodes **already scaled** frames, so
200
+ Python never touches a 4K frame.
201
+ 2. A decoder thread reads exact-size frame buffers and pushes them into a small
202
+ bounded queue; backpressure protects memory, and the render loop drops
203
+ frames that are more than two intervals late.
204
+ 3. Frame deadlines are absolute (`index / fps`), so render jitter never
205
+ accumulates into drift.
206
+ 4. Frames are painted with `ESC[H` + frame + `ESC[J`, in one write per frame.
207
+ The cursor is hidden on entry and restored in `finally`.
208
+
209
+ ### Audio pipeline
210
+
211
+ The audio **is the clock**. PortAudio's stream time (minus its output latency)
212
+ tells the renderer which media timestamp should be on screen right now:
213
+
214
+ ```
215
+ audio position = stream.time - baseline - stream.latency
216
+ ```
217
+
218
+ `prepare()` opens the device before the first frame is decoded and `start()`
219
+ begins playback once frame 1 is ready, so device initialisation cannot skip the
220
+ opening seconds. `position()` drives video pacing, which keeps audio and video
221
+ locked even when rendering is slow.
222
+
223
+ Backend order: `sounddevice` → `ffplay` → `mpv` → `afplay` (macOS, via a
224
+ temporary M4A) → silence (one warning). GIFs and files without an audio stream
225
+ skip the audio stack entirely.
226
+
227
+ ---
228
+
229
+ ## Architecture
230
+
231
+ ```text
232
+ src/curlcast/
233
+ ├── __init__.py # version and public metadata
234
+ ├── __main__.py # python -m curlcast
235
+ ├── cli.py # Typer commands: view / play / demo
236
+ ├── terminal.py # ANSI setup, terminal sizing, flicker-free Screen
237
+ ├── ffmpeg.py # bundled binary lookup + media probing
238
+ ├── player.py # frame sources, decoder threads, pacing loop
239
+ ├── audio.py # audio backends + audio-master clock
240
+ ├── demo.py # NumPy plasma and torus sources
241
+ ├── py.typed # PEP 561 marker
242
+ └── renderers/
243
+ ├── __init__.py # registry: register_renderer / get_renderer
244
+ ├── base.py # BaseRenderer strategy + fit() geometry
245
+ ├── _pixels.py # shared NumPy helpers
246
+ ├── blocks.py # --mode hd
247
+ └── ascii.py # --mode ascii
248
+ ```
249
+
250
+ ## Adding your own renderer
251
+
252
+ A renderer receives an `(H, W, 3)` `uint8` RGB array and returns terminal text.
253
+ Set `PIXEL_ASPECT` to match your cell geometry, then register it:
254
+
255
+ ```python
256
+ import numpy as np
257
+
258
+ from curlcast.renderers import BaseRenderer, register_renderer
259
+
260
+
261
+ class BrailleRenderer(BaseRenderer):
262
+ PIXEL_ASPECT = 1.0 # one sample row per character row
263
+
264
+ def render(self, frame: np.ndarray) -> str:
265
+ # frame.shape == (height, width, 3)
266
+ ...
267
+
268
+
269
+ register_renderer("braille", BrailleRenderer)
270
+ ```
271
+
272
+ ```console
273
+ curlcast play video.mp4 --mode braille
274
+ ```
275
+
276
+ `register_renderer` replaces an existing name if you want to override a built-in
277
+ for a session. Renderers can also be used directly:
278
+
279
+ ```python
280
+ from PIL import Image
281
+ from curlcast.renderers import get_renderer
282
+
283
+ renderer = get_renderer("hd", width=100)
284
+ print(renderer.render_image(Image.open("photo.jpg"), upscale=True))
285
+ ```
286
+
287
+ ---
288
+
289
+ ## Performance
290
+
291
+ Measured on a Windows laptop (Python 3.11) with a 120×45 terminal:
292
+
293
+ | Mode | Grid | Render time | Budget |
294
+ |---|---|---|---|
295
+ | `hd` | 120 × 68 | ~14 ms/frame | 70 fps |
296
+ | `hd` | 178 × 100 | ~35 ms/frame | 28 fps |
297
+ | `ascii` | 80 × 45 | ~10 ms/frame | 100 fps |
298
+
299
+ The default 20 fps has comfortable headroom. On a slower terminal the player
300
+ drops late frames rather than drifting away from the audio.
301
+
302
+ ---
303
+
304
+ ## Troubleshooting
305
+
306
+ **Blocks look like `?` or mojibake on Windows.**
307
+ Use Windows Terminal (recommended) or Windows 10+ `conhost`. CurlCast calls
308
+ `SetConsoleOutputCP(65001)` and enables `ENABLE_VIRTUAL_TERMINAL_PROCESSING`,
309
+ but a font without block glyphs will still show boxes — Cascadia Mono, Consolas
310
+ and most programming fonts are fine.
311
+
312
+ **No sound.**
313
+ `curlcast --help` does not report audio status. Check that the file has an audio
314
+ stream, then install a system player (`ffplay` or `mpv`) as a fallback. Run
315
+ `python -c "from curlcast.audio import available_backends; print(available_backends())"`
316
+ to see what is usable.
317
+
318
+ **The image looks stretched.**
319
+ Terminal cells are assumed to be 2:1. Fonts with unusual cell ratios (some
320
+ CJK fonts) can differ; `--mode hd` is closest to 1:1 because it encodes pixels
321
+ in pairs. `--no-upscale` also helps when a small image is being enlarged.
322
+
323
+ **Output wraps / adds a blank line.**
324
+ CurlCast reserves the last column and bottom row. If your terminal has an
325
+ unusual width, pass an explicit `--width` two columns narrower than the window.
326
+
327
+ **Ctrl+C left the cursor hidden.**
328
+ This should not happen (`Screen.close()` runs in `finally`), but any terminal
329
+ can be restored with `tput cnorm` (macOS/Linux) or by reopening the tab.
330
+
331
+ ---
332
+
333
+ ## Development
334
+
335
+ ```console
336
+ pip install -e ".[dev]"
337
+
338
+ python -m pytest # 115 tests
339
+ ruff check src tests
340
+ mypy src
341
+ ```
342
+
343
+ The test suite covers geometry budgets and aspect ratios for both modes,
344
+ ANSI/colour invariants, the 70-character ramp, adaptive contrast, GIF timing,
345
+ real ffmpeg decoding (a synthetic clip is generated with the bundled binary),
346
+ probe parsing (including rotation metadata), pacing/drop behaviour, audio clock
347
+ semantics, cursor restoration, packaging metadata, and every CLI command.
348
+
349
+ ### Manual smoke test
350
+
351
+ Generate a clip with audio and a GIF, then try both modes:
352
+
353
+ ```console
354
+ ffmpeg -f lavfi -i testsrc2=size=1280x720:rate=30 ^
355
+ -f lavfi -i sine=frequency=440 -t 10 ^
356
+ -c:v libx264 -pix_fmt yuv420p -c:a aac sample.mp4
357
+
358
+ curlcast play sample.mp4
359
+ curlcast play sample.mp4 --mode ascii --loop
360
+ curlcast demo --animation torus
361
+ ```
362
+
363
+ ---
364
+
365
+ ## Publishing to PyPI
366
+
367
+ The package name `curlcast` is available on PyPI as of this release. The version
368
+ lives in exactly one place — `__version__` in `src/curlcast/__init__.py` — and
369
+ hatchling reads it from there, so a release is just a tag.
370
+
371
+ ```console
372
+ pip install build twine
373
+ python -m build # dist/curlcast-<version>.tar.gz + wheel
374
+ twine check dist/*
375
+ ```
376
+
377
+ Publish to TestPyPI first:
378
+
379
+ ```console
380
+ twine upload --repository testpypi dist/*
381
+ pip install -i https://test.pypi.org/simple/ \
382
+ --extra-index-url https://pypi.org/simple/ curlcast
383
+ ```
384
+
385
+ Then to PyPI (use an API token: username `__token__`):
386
+
387
+ ```console
388
+ twine upload dist/*
389
+ pip install curlcast
390
+ ```
391
+
392
+ ### Automated releases
393
+
394
+ `.github/workflows/pypi-publish.yml` publishes on `v*` tags using PyPI
395
+ **Trusted Publishing** (OIDC), so no API token is stored in the repository.
396
+ Configure the publisher once in the PyPI project settings:
397
+
398
+ - Owner/repository: your GitHub account and repo
399
+ - Workflow: `pypi-publish.yml`
400
+ - Environment: `pypi`
401
+
402
+ ```console
403
+ git tag v0.1.0
404
+ git push origin v0.1.0
405
+ ```
406
+
407
+ ---
408
+
409
+ ## License
410
+
411
+ MIT © 2026 CurlCast Contributors. See [LICENSE](LICENSE).