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.
- curlcast-0.1.0/.gitignore +28 -0
- curlcast-0.1.0/LICENSE +21 -0
- curlcast-0.1.0/PKG-INFO +411 -0
- curlcast-0.1.0/README.md +372 -0
- curlcast-0.1.0/pyproject.toml +94 -0
- curlcast-0.1.0/src/curlcast/__init__.py +20 -0
- curlcast-0.1.0/src/curlcast/__main__.py +8 -0
- curlcast-0.1.0/src/curlcast/audio.py +463 -0
- curlcast-0.1.0/src/curlcast/cli.py +208 -0
- curlcast-0.1.0/src/curlcast/demo.py +158 -0
- curlcast-0.1.0/src/curlcast/ffmpeg.py +115 -0
- curlcast-0.1.0/src/curlcast/player.py +383 -0
- curlcast-0.1.0/src/curlcast/py.typed +0 -0
- curlcast-0.1.0/src/curlcast/renderers/__init__.py +70 -0
- curlcast-0.1.0/src/curlcast/renderers/_pixels.py +37 -0
- curlcast-0.1.0/src/curlcast/renderers/ascii.py +114 -0
- curlcast-0.1.0/src/curlcast/renderers/base.py +128 -0
- curlcast-0.1.0/src/curlcast/renderers/blocks.py +138 -0
- curlcast-0.1.0/src/curlcast/terminal.py +146 -0
- curlcast-0.1.0/tests/conftest.py +31 -0
- curlcast-0.1.0/tests/test_cli.py +110 -0
- curlcast-0.1.0/tests/test_gif.py +60 -0
- curlcast-0.1.0/tests/test_media.py +116 -0
- curlcast-0.1.0/tests/test_package.py +35 -0
- curlcast-0.1.0/tests/test_player.py +92 -0
- curlcast-0.1.0/tests/test_renderers.py +116 -0
- curlcast-0.1.0/tests/test_sizing.py +78 -0
|
@@ -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.
|
curlcast-0.1.0/PKG-INFO
ADDED
|
@@ -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).
|